Two Sides of Schur Damping: arXiv package, web edition, citation

.github/workflows/ci.yml

@@ -29,25 +29,25 @@ jobs:
         run: pytest
 
   docs-up-to-date:
-    # The web edition of the paper is generated from papers/schur_likelihood_paper.tex.
-    # Fail if the committed HTML is stale (i.e. the .tex changed but docs/build_paper.sh
+    # The web editions of the papers are generated from their LaTeX sources in papers/.
+    # Fail if any committed HTML is stale (i.e. a .tex changed but docs/build_paper.sh
     # was not rerun). Pandoc is pinned so the regenerated output matches byte-for-byte.
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
       - uses: r-lib/actions/setup-pandoc@v2
         with:
           pandoc-version: '3.9.0.2'
-      - name: Regenerate the web paper from LaTeX
+      - name: Regenerate the web papers from LaTeX
         run: ./docs/build_paper.sh
-      - name: Fail if the generated web paper is stale
+      - name: Fail if any generated web paper is stale
         run: |
-          if ! git diff --quiet -- docs/papers/schur-likelihood/index.html; then
-            echo "::error::docs/papers/schur-likelihood/index.html is out of date — run ./docs/build_paper.sh and commit."
-            git diff -- docs/papers/schur-likelihood/index.html | head -60
+          if ! git diff --quiet -- docs/papers/schur-likelihood/index.html docs/papers/two-sides-of-schur-damping/index.html; then
+            echo "::error::a generated web paper under docs/papers/ is out of date — run ./docs/build_paper.sh and commit."
+            git diff -- docs/papers/schur-likelihood/index.html docs/papers/two-sides-of-schur-damping/index.html | head -120
             exit 1
           fi
-          echo "web paper is in sync with the LaTeX source"
+          echo "web papers are in sync with the LaTeX sources"
 
   test-minimal:
     # Verify the package imports and the full test suite passes with numpy only

docs/_paper_template.html

@@ -28,7 +28,7 @@
     <h1>$title$</h1>$if(subtitle)$<div class="subtitle">$subtitle$</div>$endif$
   </div></div>
   <div class="container">
-$if(author)$    <p class="paper-meta">$for(author)$$author$$sep$, $endfor$$if(date)$ &middot; $date$$endif$ &middot; <a href="https://github.com/microprediction/precise/blob/main/papers/schur_likelihood_paper.pdf">PDF</a></p>
+$if(author)$    <p class="paper-meta">$for(author)$$author$$sep$, $endfor$$if(date)$ &middot; $date$$endif$$if(pdfurl)$ &middot; <a href="$pdfurl$">PDF</a>$endif$</p>
 $endif$$if(abstract)$    <div class="abstract">$abstract$</div>
 $endif$
 $body$

docs/build_paper.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# Regenerate a paper's WEB edition from its LaTeX source — single source of truth, so the
+# Regenerate each paper's WEB edition from its LaTeX source — single source of truth, so the
 # online version cannot drift from the PDF. Requires pandoc (with citeproc).
 #
 #   ./docs/build_paper.sh
@@ -8,14 +8,35 @@ set -euo pipefail
 here="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"     # docs/
 root="$(dirname "$here")"
 
-mkdir -p "$here/papers/schur-likelihood"
-pandoc "$root/papers/schur_likelihood_paper.tex" \
-  --from=latex \
-  --katex \
-  --citeproc --bibliography="$root/papers/refs.bib" \
-  --shift-heading-level-by=1 \
-  --template="$here/_paper_template.html" \
-  --metadata title="Schur Covariance Evaluation" \
-  --metadata subtitle="A Principled Pseudo-Likelihood in High Dimensions" \
-  -o "$here/papers/schur-likelihood/index.html"
-echo "wrote docs/papers/schur-likelihood/index.html (generated from papers/schur_likelihood_paper.tex)"
+# build_one <tex-basename> <out-slug> <title> <subtitle>
+# The PDF lives next to the .tex in papers/ and is linked from the web header.
+# The source keeps numbered equation environments (for the arXiv/PDF edition); for the
+# web we strip them to unnumbered \[ \] display math, which KaTeX renders cleanly. The
+# prose refers to equations descriptively, so no cross-references break in the process.
+build_one() {
+  local tex="$1" slug="$2" title="$3" subtitle="$4"
+  local pdfurl="https://github.com/microprediction/precise/blob/main/papers/${tex}.pdf"
+  local websrc; websrc="$(mktemp)"
+  sed -e 's/\\begin{equation}/\\[/g' -e 's/\\end{equation}/\\]/g' "$root/papers/${tex}.tex" > "$websrc"
+  mkdir -p "$here/papers/$slug"
+  pandoc "$websrc" \
+    --from=latex \
+    --katex \
+    --citeproc --bibliography="$root/papers/refs.bib" \
+    --shift-heading-level-by=1 \
+    --template="$here/_paper_template.html" \
+    --metadata title="$title" \
+    --metadata subtitle="$subtitle" \
+    --metadata pdfurl="$pdfurl" \
+    -o "$here/papers/$slug/index.html"
+  rm -f "$websrc"
+  echo "wrote docs/papers/$slug/index.html (generated from papers/${tex}.tex)"
+}
+
+build_one schur_likelihood_paper schur-likelihood \
+  "Schur Covariance Evaluation" \
+  "A Principled Pseudo-Likelihood in High Dimensions"
+
+build_one two_sides_of_schur_damping two-sides-of-schur-damping \
+  "Two Sides of Schur Damping" \
+  "High-Dimensional Pseudo-Likelihoods and Portfolio Allocation"

docs/index.html

@@ -35,7 +35,7 @@
                 <a href="#install">Install</a>
                 <a href="#quickstart">Quick start</a>
                 <a href="#estimators">Estimators</a>
-                <a href="#schur">Schur likelihood</a>
+                <a href="papers/">Papers</a>
                 <a href="https://github.com/microprediction/precise">GitHub</a>
                 <a href="https://pypi.org/project/precise/">PyPI</a>
             </div>
@@ -167,7 +167,7 @@ <h2>Links</h2>
                 <li><a href="https://pypi.org/project/precise/">PyPI</a> — <code>pip install precise</code></li>
                 <li><a href="https://github.com/microprediction/precise">GitHub repository</a></li>
                 <li><a href="https://github.com/microprediction/precise/blob/main/MIGRATING.md">Migrating from the 0.16.x skater API</a></li>
-                <li><a href="https://github.com/microprediction/precise/blob/main/papers/schur_likelihood_paper.pdf">Schur pseudo-likelihood paper (PDF)</a></li>
+                <li><a href="papers/">Papers</a> — working papers on covariance/correlation estimation and the Schur likelihood</li>
                 <li><a href="https://allocation.microprediction.org">allocation.microprediction.org</a> — portfolio / allocation (Schur-complementary; moved out of precise)</li>
             </ul>
         </section>

docs/papers/index.html

@@ -38,7 +38,20 @@ <h3><a href="schur-likelihood/">Schur Covariance Evaluation</a></h3>
          <a class="btn btn-secondary" href="https://github.com/microprediction/precise/blob/main/papers/schur_likelihood_paper.pdf">PDF</a></p>
     </div>
 
-    <p class="text-muted">More to come. The web editions are generated from their LaTeX sources
+    <div class="paper-card">
+      <h3><a href="two-sides-of-schur-damping/">Two Sides of Schur Damping</a></h3>
+      <p class="text-muted" style="margin:4px 0 12px">High-Dimensional Pseudo-Likelihoods and Portfolio Allocation &middot; Peter Cotton</p>
+      <p>Spatial statisticians fitting high-dimensional weather fields and quantitative investors
+      building portfolios have independently arrived at the same object: a Schur complement damped by
+      one interpretable parameter — a conditional covariance for the statistician, a hedged residual
+      risk for the investor. We show these are one operation, so the closed-form reliability that sets
+      the damping is at once a James–Stein shrinkage and a Ledoit–Wolf intensity, and note what each
+      literature has supplied that the other lacks.</p>
+      <p><a class="btn" href="two-sides-of-schur-damping/">Read online</a>
+         <a class="btn btn-secondary" href="https://github.com/microprediction/precise/blob/main/papers/two_sides_of_schur_damping.pdf">PDF</a></p>
+    </div>
+
+    <p class="text-muted">The web editions are generated from their LaTeX sources
     (<code>docs/build_paper.sh</code>), so they never drift from the PDF.</p>
   </div>