{% extends "_base.html" %}

{% block page_title %}{{ title }}{% endblock %}

{% block extra_css %}
/* ── Parameter & Guidance Tables ─────────────────── */
.param-table, .guidance-table {
    width: 100%;
    border-collapse: collapse;
    font-size: 0.875rem;
}
.param-table th, .guidance-table th {
    background: #2d3748;
    color: #90cdf4;
    padding: 0.6rem 1rem;
    text-align: left;
    font-weight: 600;
    white-space: nowrap;
}
.param-table td, .guidance-table td {
    padding: 0.5rem 1rem;
    border-bottom: 1px solid #2d3748;
    vertical-align: top;
}
.param-table td.param-name {
    font-family: "SFMono-Regular", Consolas, monospace;
    color: #63b3ed;
    white-space: nowrap;
    font-weight: 600;
}
.param-table td.param-value {
    font-family: "SFMono-Regular", Consolas, monospace;
    color: #68d391;
    white-space: nowrap;
}
.param-table td.param-constraint {
    font-family: "SFMono-Regular", Consolas, monospace;
    color: #f6ad55;
    white-space: nowrap;
}
.param-table td.param-description { color: #cbd5e0; }
.param-table tbody tr:hover,
.guidance-table tbody tr:hover { background: #1e2a3a; }
.guidance-table td.regime { color: #cbd5e0; white-space: nowrap; }
.guidance-table td.shrink-range { color: #f6ad55; font-weight: 600; }
.guidance-table td.notes { color: #a0aec0; }

/* ── Theory Section ───────────────────────────────── */
.theory-block {
    background: #1a202c;
    border: 1px solid #2d3748;
    border-radius: 12px;
    padding: 1.5rem 2rem;
    line-height: 1.8;
}
.theory-block h3 {
    color: #90cdf4;
    font-size: 1rem;
    font-weight: 600;
    margin: 1.25rem 0 0.5rem;
}
.theory-block h3:first-child { margin-top: 0; }
.theory-block p { color: #cbd5e0; margin-bottom: 0.75rem; }
.theory-block code {
    font-family: "SFMono-Regular", Consolas, monospace;
    background: #2d3748;
    padding: 0.1em 0.4em;
    border-radius: 4px;
    font-size: 0.875em;
    color: #63b3ed;
}
.theory-block .math-block {
    font-family: "SFMono-Regular", Consolas, monospace;
    background: #2d3748;
    border-left: 3px solid #4299e1;
    padding: 0.75rem 1rem;
    border-radius: 0 8px 8px 0;
    margin: 0.75rem 0;
    color: #e2e8f0;
    font-size: 0.9rem;
}
.theory-block ul {
    list-style: none;
    padding: 0;
}
.theory-block ul li {
    color: #cbd5e0;
    padding: 0.2rem 0;
    padding-left: 1.5rem;
    position: relative;
}
.theory-block ul li::before {
    content: "▸";
    position: absolute;
    left: 0;
    color: #4299e1;
}
.theory-block a { color: #63b3ed; }
.theory-block a:hover { text-decoration: underline; }
.refs { color: #a0aec0; font-size: 0.85rem; margin-top: 1rem; }
{% endblock %}

{% block header %}
<header class="report-header">
  <h1>&#x2699;&#xFE0F; {{ title }}</h1>
  <div class="report-meta">
    <span><strong>vola:</strong> {{ vola }}</span>
    <span><strong>corr:</strong> {{ corr }}</span>
    <span><strong>clip:</strong> {{ clip }}</span>
    <span><strong>shrink&nbsp;(λ):</strong> {{ shrink }}</span>
    <span><strong>AUM:</strong> {{ aum }}</span>
  </div>
</header>
{% endblock %}

{% block nav %}
<nav class="toc">
  <a href="#parameters">Parameters</a>
  {{ toc_extra_sep | safe }}{{ toc_lambda | safe }}
  <a href="#guidance">Shrinkage Guidance</a>
  <a href="#theory">Theory</a>
</nav>
{% endblock %}

{% block content %}
  <section class="section" id="parameters">
    <h2 class="section-title">Configuration Parameters</h2>
    <div class="chart-card" style="overflow-x: auto;">{{ params_html | safe }}</div>
  </section>

  <section class="section" id="lambda-sweep">
    <h2 class="section-title">Lambda (Shrinkage) Sweep</h2>
    {{ sweep_section | safe }}
  </section>

  <section class="section" id="guidance">
    <h2 class="section-title">Shrinkage Guidance &#x2014; n / T Regimes</h2>
    <div class="chart-card" style="overflow-x: auto;">{{ guidance_html | safe }}</div>
  </section>

  <section class="section" id="theory">
    <h2 class="section-title">Theory &amp; References</h2>
    <div class="theory-block">
      <h3>Linear Shrinkage toward the Identity</h3>
      <p>
        The <code>shrink</code> parameter (&lambda;) controls how much the EWMA sample
        correlation matrix <em>C<sub>EWMA</sub></em> is regularised before being
        passed to the linear solver.  The shrunk matrix is:
      </p>
      <div class="math-block">C_shrunk = &lambda; &middot; C_EWMA + (1 - &lambda;) &middot; I_n</div>
      <p>
        where <em>I<sub>n</sub></em> is the n x n identity matrix.
        Setting &lambda; = 1 uses the raw EWMA correlation matrix (no shrinkage); setting
        &lambda; = 0 replaces it entirely with the identity (positions become purely
        signal-proportional, uncorrelated).
      </p>

      <h3>Why Shrinkage?</h3>
      <p>
        When the number of assets <em>n</em> is large relative to the lookback
        window <em>T</em> (high concentration ratio <em>n/T</em>), the sample
        covariance matrix is poorly estimated.  Extreme eigenvalues amplify
        estimation noise and cause the linear solver to allocate excessive
        leverage to a few eigendirections.  Shrinkage toward the identity damps
        these extremes, improves the condition number, and produces more stable,
        diversified positions.
      </p>

      <h3>When to Prefer Strong Shrinkage (low &lambda;)</h3>
      <ul>
        <li>Fewer than ~30 assets with a <code>corr</code> lookback shorter than 100 days.</li>
        <li>High-volatility or crisis regimes where correlations spike and the
            sample matrix is less representative of the true structure.</li>
        <li>Portfolios where estimation noise is more costly than correlation bias
            (low signal-to-noise ratio of <code>mu</code>).</li>
      </ul>

      <h3>When to Prefer Light Shrinkage (high &lambda;)</h3>
      <ul>
        <li>Many assets with a long lookback (low concentration ratio).</li>
        <li>The EWMA correlation structure carries genuine diversification
            information that the solver should exploit.</li>
        <li>Out-of-sample testing shows that position stability is not a concern.</li>
      </ul>

      <h3>EWMA Parameters &#x2014; vola and corr</h3>
      <p>
        Both <code>vola</code> and <code>corr</code> are span-equivalent EWMA
        lookbacks (in trading periods).  The EWMA decay factor is
        <em>a = 2 / (span + 1)</em>, giving a centre-of-mass of
        <em>span / 2</em> periods.  <code>corr</code> must be &gt;= <code>vola</code>
        to ensure the correlation estimator sees at least as much history as the
        volatility normaliser.
      </p>

      <h3>References</h3>
      <p class="refs">
        Ledoit, O. &amp; Wolf, M. (2004).
        <em>A well-conditioned estimator for large-dimensional covariance matrices.</em>
        Journal of Multivariate Analysis, 88(2), 365-411.<br/>
        Chen, Y., Wiesel, A., Eldar, Y. C., &amp; Hero, A. O. (2010).
        <em>Shrinkage Algorithms for MMSE Covariance Estimation.</em>
        IEEE Transactions on Signal Processing, 58(10), 5016-5029.<br/>
        See also: <code>basanos.math._signal.shrink2id</code> for the implementation.
      </p>
    </div>
  </section>
{% endblock %}