squarequant 0.2.3__tar.gz → 0.4.0.dev1__tar.gz

squarequant-0.4.0.dev1/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changes
+
+## 0.4.0.dev1
+
+This edition retains the original risk statistics, VaR, simulations, data adapters
+and utilities. Contract definitions, trade capture, persistence, payment
+schedules, valuation/scenario layers, their tests, examples, benchmarks and
+associated documentation have been removed from the source distribution.
+
+Retained numerical corrections and new consistency/validation improvements are
+described in `docs/audit.md`. 
+The portfolio VaR column remains part of the statistical API.
+
+The package requires Python 3.11+. The function-level default VaR horizon remains
+10 observations; users should pass their chosen horizon explicitly. Supplied
+risk-free rates remain daily unless the annual convention is selected.
+Delta-gamma VaR requires an explicit Hessian and retains the documented
+moment-matching approximation. Invalid numerical/grid inputs now fail clearly.
+
+Data-provider dependencies remain optional. Complete install/build/API checks
+and their actual outcomes are recorded in `VALIDATION_REPORT.md`.

{squarequant-0.2.3 → squarequant-0.4.0.dev1}/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2025 Gabriel Bosch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+MIT License
+
+Copyright (c) 2025 Gabriel Bosch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.

squarequant-0.4.0.dev1/MANIFEST.in

@@ -0,0 +1,8 @@
+recursive-include tests *.py
+recursive-include docs *.md *.py
+prune docs/_build
+include examples/risk_metrics_demo.py
+include requirements-validation-py312.txt
+include VALIDATION_REPORT.md
+include CHANGELOG.md
+include START_HERE.txt

squarequant-0.4.0.dev1/PKG-INFO

@@ -0,0 +1,114 @@
+Metadata-Version: 2.4
+Name: squarequant
+Version: 0.4.0.dev1
+Summary: Financial risk metrics, Monte Carlo simulations, and optional market-data adapters
+Author-email: Gabriel Bosch <contact@squarequant.org>
+License-Expression: MIT
+Project-URL: Documentation, https://www.squarequant.org
+Project-URL: Bug Tracker, https://github.com/SquareQuant/squarequant-package/issues
+Project-URL: Homepage, https://github.com/SquareQuant/squarequant-package
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 4 - Beta
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=2.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Provides-Extra: data
+Requires-Dist: yfinance>=0.2.0; extra == "data"
+Requires-Dist: requests>=2.25.0; extra == "data"
+Provides-Extra: optimization
+Requires-Dist: cvxpy>=1.0.0; extra == "optimization"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.11; extra == "dev"
+Requires-Dist: mypy>=1.15; extra == "dev"
+Requires-Dist: hypothesis>=6; extra == "dev"
+Requires-Dist: build>=1; extra == "dev"
+Requires-Dist: requests>=2.25.0; extra == "dev"
+Requires-Dist: sphinx>=4.0.0; extra == "dev"
+Requires-Dist: myst-parser>=1.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=2.12.0; extra == "dev"
+Dynamic: license-file
+
+# SquareQuant — financial risk statistics
+
+Version `0.4.0.dev1` provides rolling financial risk metrics, historical/parametric
+VaR, Monte Carlo simulations, and optional market-data downloads. Python 3.11+
+is required.
+
+## Install and run
+
+```bash
+python -m venv .venv
+```
+
+On Windows:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\python.exe examples\risk_metrics_demo.py
+```
+
+On macOS/Linux:
+
+```bash
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest -q
+.venv/bin/python examples/risk_metrics_demo.py
+```
+
+## Example
+
+```python
+import pandas as pd
+import squarequant as sq
+
+returns = pd.DataFrame({'Asset': [-0.04, -0.02, 0.01, 0.02]})
+var = sq.var(returns, ['Asset'], window=4, holding_period=1)
+es = sq.cvar(returns, ['Asset'], window=4, holding_period=1, confidence=0.625)
+print(var['Portfolio'].iloc[-1])  # 0.037
+print(es['Asset'].iloc[-1])       # 0.03333333333333333
+```
+
+The public API contains `DownloadConfig`, `download_tickers`, `sharpe`, `sortino`,
+`vol`, `mdd`, `calmar`, `var`, `cvar`, `semidev`, `avgdd`, `ulcer`, `mad`, `erm`,
+`evar`, `cdar`, `simplemc`, `brownian`, `correlated_brownian`, `gbm_paths`, and
+`gbm_correlated_paths`.
+
+The `data` extra installs yfinance/requests for optional downloads. It is not
+needed to import SquareQuant or run the offline statistics example. The
+`optimization` extra is retained for installation compatibility.
+
+## Documentation and validation
+
+- [Usage, assumptions and numerical examples](docs/usage.md)
+- [Public API reference](docs/api.md)
+- [Audit and corrections](docs/audit.md)
+- [Release changes](CHANGELOG.md)
+- [Executed verification results](VALIDATION_REPORT.md)
+
+```bash
+python -m ruff check squarequant tests examples/risk_metrics_demo.py
+python -m ruff format --check squarequant tests examples/risk_metrics_demo.py
+python -m mypy --no-incremental
+python -m sphinx -W -b html docs docs/_build/html
+python -m build
+```
+
+CI is configured for Python 3.11/3.12/3.13. Actual local validation versions and
+results are recorded in `VALIDATION_REPORT.md`. Legacy `examples/*_test.py` files
+are vendor/plotting scripts; the isolated offline suite is under `tests/`.
+Those legacy scripts require optional provider packages and matplotlib.
+
+Code is licensed under MIT. See [CONTRIBUTING.md](CONTRIBUTING.md).

squarequant-0.4.0.dev1/README.md

@@ -0,0 +1,72 @@
+# SquareQuant — financial risk statistics
+
+Version `0.4.0.dev1` provides rolling financial risk metrics, historical/parametric
+VaR, Monte Carlo simulations, and optional market-data downloads. Python 3.11+
+is required.
+
+## Install and run
+
+```bash
+python -m venv .venv
+```
+
+On Windows:
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e ".[dev]"
+.\.venv\Scripts\python.exe -m pytest -q
+.\.venv\Scripts\python.exe examples\risk_metrics_demo.py
+```
+
+On macOS/Linux:
+
+```bash
+.venv/bin/python -m pip install -e '.[dev]'
+.venv/bin/python -m pytest -q
+.venv/bin/python examples/risk_metrics_demo.py
+```
+
+## Example
+
+```python
+import pandas as pd
+import squarequant as sq
+
+returns = pd.DataFrame({'Asset': [-0.04, -0.02, 0.01, 0.02]})
+var = sq.var(returns, ['Asset'], window=4, holding_period=1)
+es = sq.cvar(returns, ['Asset'], window=4, holding_period=1, confidence=0.625)
+print(var['Portfolio'].iloc[-1])  # 0.037
+print(es['Asset'].iloc[-1])       # 0.03333333333333333
+```
+
+The public API contains `DownloadConfig`, `download_tickers`, `sharpe`, `sortino`,
+`vol`, `mdd`, `calmar`, `var`, `cvar`, `semidev`, `avgdd`, `ulcer`, `mad`, `erm`,
+`evar`, `cdar`, `simplemc`, `brownian`, `correlated_brownian`, `gbm_paths`, and
+`gbm_correlated_paths`.
+
+The `data` extra installs yfinance/requests for optional downloads. It is not
+needed to import SquareQuant or run the offline statistics example. The
+`optimization` extra is retained for installation compatibility.
+
+## Documentation and validation
+
+- [Usage, assumptions and numerical examples](docs/usage.md)
+- [Public API reference](docs/api.md)
+- [Audit and corrections](docs/audit.md)
+- [Release changes](CHANGELOG.md)
+- [Executed verification results](VALIDATION_REPORT.md)
+
+```bash
+python -m ruff check squarequant tests examples/risk_metrics_demo.py
+python -m ruff format --check squarequant tests examples/risk_metrics_demo.py
+python -m mypy --no-incremental
+python -m sphinx -W -b html docs docs/_build/html
+python -m build
+```
+
+CI is configured for Python 3.11/3.12/3.13. Actual local validation versions and
+results are recorded in `VALIDATION_REPORT.md`. Legacy `examples/*_test.py` files
+are vendor/plotting scripts; the isolated offline suite is under `tests/`.
+Those legacy scripts require optional provider packages and matplotlib.
+
+Code is licensed under MIT. See [CONTRIBUTING.md](CONTRIBUTING.md).

squarequant-0.4.0.dev1/docs/api.md

@@ -0,0 +1,16 @@
+# Public API reference
+
+## Risk statistics and simulations
+
+```{automodule} squarequant.api
+:members:
+```
+
+## Optional data configuration and retrieval
+
+```{autoclass} squarequant.data.data.DownloadConfig
+:members:
+```
+
+```{autofunction} squarequant.data.data.download_tickers
+```

squarequant-0.4.0.dev1/docs/audit.md

@@ -0,0 +1,67 @@
+# Statistics audit and corrections
+
+This source edition contains the financial statistics, Monte Carlo and optional
+data-download components. The upstream audit baseline is commit
+`024363059e7af6a23e0e95167a6294b5d449e33a`.
+
+## Retained corrections
+
+| Component | Confirmed issue | Correction |
+|---|---|---|
+| Drawdowns | A boolean was compared with the string `absolute`; double rolling leaked an earlier peak outside the window; return inputs omitted initial losses. | Explicit return conventions and a within-window path with an initial wealth baseline. |
+| Shared preprocessing | Whole-frame missing-value removal discarded unrelated valid observations; forward filling manufactured zero price returns. | Process selected columns, retain dates/per-asset missing values, use price conversion without imputation. |
+| Risk-free rates | The risk-free column could be price-converted; daily versus annual inputs were implicit. | Preserve the rate series; add explicit annual effective conversion while retaining daily explicit-input defaults. |
+| Delta-gamma VaR | Squared returns/correlations did not identify instrument price curvature, and the expected gamma term was added to volatility. | Explicit supplied portfolio Hessian, Gaussian quadratic P&L moments and covariance-level horizon scaling. |
+| Historical VaR | Multiple-period results relied on square-root scaling. | Preserve/document the approximation and add overlapping empirical horizon returns. |
+| Calmar | Log annual returns and simple annual returns were inconsistent. | Convert annualized log returns with `expm1`. |
+| CVaR/ES | Tail counts were rounded up; parametric mean was scaled with square-root time. | Fractional empirical tail mass; separate mean/volatility horizon scaling. |
+| Entropic statistics | The fixed-z formula mixed z and its reciprocal, could overflow and normal EVaR ignored the horizon. | Stable log-sum-exp bound with documented legacy naming; normal EVaR horizon scaling. |
+| Monte Carlo | Default multi-factor GBM reused one factor; fitted log drift was presented as price drift; parameter checks were incomplete. | Correct default correlation dimension, half-variance drift correction and validation. |
+| Data/packaging | Date defaults were fixed at import; single-ticker MultiIndexes were mishandled; optional provider imports blocked numerical use; Python/version metadata disagreed. | Per-instance defaults, response normalization, lazy provider imports and one version source with an explicit Python baseline. |
+
+## Additional corrections in 0.4.0.dev1
+
+- Calmar now calculates both numerator and drawdown denominator from the same
+  return window. Equivalent price and return inputs are regression-tested.
+- Relative/log drawdowns use log-wealth differences to avoid overflowing a long
+  compounded wealth path; a -100% simple return remains a valid total loss.
+- Confidence, z, grids and holding periods reject non-finite values, booleans and
+  inappropriate non-integer counts. NumPy integer counts are accepted.
+- VaR aligns labelled Series weights by asset name and retains zero-net
+  exposures. Invalid/missing gamma labels have explicit errors. The reserved
+  aggregate result label cannot overwrite an input factor.
+- Nullable pandas numeric data are supported; complex observations are rejected.
+- Monte Carlo instance methods delegate to their static implementations,
+  reducing duplicate code and making API equivalence directly testable.
+- Date helpers enforce ISO format and date ordering. Downloaded symbols retain
+  requested order; `Count` is accepted, `Adj Close` is retrieved coherently, and
+  intraday requests are rejected by the EOD-only adapter.
+- Optional annotations, public VaR documentation, supported-method constants,
+  fixtures, build manifests and CI targets are aligned with the retained API.
+  Static checks cover all package source modules rather than a selected subset.
+
+## Validation approach and remaining assumptions
+
+The suite exercises every public export with offline inputs. It includes
+analytical VaR/ES/ratio examples, price-versus-return consistency, drawdown
+properties, simulation moments/correlations, seeded API equivalence, bad-input
+checks, and provider-response fixtures. A network guard forbids outbound
+connections. Provider tests use deterministic doubles rather than credentials or
+live subscriptions. The complete example is an executable numerical regression.
+
+Delta-gamma VaR uses Gaussian moment matching, so it is an approximate quantile
+of generally non-Gaussian quadratic P&L. Delta-normal uses a zero-mean convention.
+Square-root historical risk scaling is an approximation. The `erm` legacy name
+refers to a fixed-z tail bound; it is not an optimized empirical EVaR or the
+confidence-independent entropic risk measure. The assumptions and units are
+specified in [usage.md](usage.md).
+
+Minimum observations and window sizes remain metric-specific. Strict rolling
+drawdown calculation costs O(observations × window × assets), while historical
+quantiles and standard moments use pandas rolling methods. No universal
+performance claim is made for arbitrary data sizes.
+
+Python 3.11/3.12/3.13 are configured in CI. Executed interpreter/dependency
+versions, test counts, coverage, build and installed-artifact results are
+recorded in the accompanying validation report. CI configuration is distinct
+from having executed every interpreter locally.

squarequant-0.4.0.dev1/docs/conf.py

@@ -0,0 +1,8 @@
+project = "SquareQuant"
+author = "SquareQuant contributors"
+extensions = ["myst_parser", "sphinx.ext.autodoc"]
+source_suffix = {".md": "markdown"}
+master_doc = "index"
+exclude_patterns = ["_build"]
+html_theme = "alabaster"
+myst_enable_extensions = ["colon_fence"]

squarequant-0.4.0.dev1/docs/index.md

@@ -0,0 +1,9 @@
+# SquareQuant financial statistics
+
+```{toctree}
+:maxdepth: 2
+
+usage
+api
+audit
+```

squarequant-0.4.0.dev1/docs/usage.md

@@ -0,0 +1,201 @@
+# Using SquareQuant
+
+## Inputs and output conventions
+
+Risk functions accept a pandas DataFrame and an explicit sequence of asset column
+names. Inputs must be real numeric observations with a unique, increasing index.
+Missing observations are retained per asset; unrelated columns are not processed.
+A requested missing asset produces a warning and a NaN output column. Date filters
+require a DatetimeIndex. Calculations return DataFrames indexed by observation
+date; output columns retain the requested names. VaR adds a `Portfolio` column,
+so that name is reserved as an input asset name for VaR.
+
+Set `use_returns=True` for returns/P&L and `False` for prices. Return conventions:
+
+| `returns_type` | Price conversion | Multi-period aggregation |
+|---|---|---|
+| `relative` | `P_t / P_(t-1) - 1` | Compound `(1+r)` |
+| `log` | `log(P_t/P_(t-1))`, requiring positive prices | Sum |
+| `absolute` | `P_t-P_(t-1)` | Sum |
+
+Relative price returns use no forward filling. A missing price leaves adjacent
+returns unknown. Nullable pandas numeric columns are supported. Use integer
+observation windows/horizons; booleans, fractions, NaN and infinite counts/risk
+parameters are rejected where applicable. Annualization uses 252 observations
+per year. Change data frequency before interpreting annualized outputs.
+
+## Core metrics
+
+```python
+import pandas as pd
+import squarequant as sq
+
+returns = pd.DataFrame({'A': [-0.04, -0.02, 0.01, 0.02]})
+vol = sq.vol(returns, ['A'], window=4)
+sharpe = sq.sharpe(returns, ['A'], window=4, freerate_value=0)
+var = sq.var(returns, ['A'], window=4, holding_period=1)
+es = sq.cvar(returns, ['A'], window=4, holding_period=1, confidence=0.625)
+assert abs(var['Portfolio'].iloc[-1] - 0.037) < 1e-12
+assert abs(es['A'].iloc[-1] - 1/30) < 1e-12
+```
+
+Volatility uses sample standard deviation and square-root annualization. Sharpe
+uses annualized mean excess return divided by annualized standard deviation.
+Sortino/downside deviation count all observations in the denominator and set
+positive excess returns to zero. Semi-deviation's default target is estimated
+inside each rolling window; an explicit target stays constant.
+
+Explicit `freerate_value` or `freerate` columns are **daily** by default. Select
+`risk_free_period='annual'` for annual effective rates. Relative returns subtract
+`(1+r_annual)^(1/252)-1`; log returns subtract `log(1+r_annual)/252`. A risk-free
+column is not price-converted. With no explicit risk-free input, the default is
+2% annual effective. Absolute P&L needs a compatible daily currency risk-free
+amount, such as an explicitly supplied zero, rather than an annual percentage.
+
+Drawdowns are calculated entirely within the rolling window. Return inputs
+include initial wealth of one (zero for absolute P&L), so a first-period loss is
+captured. Relative/log drawdowns use stable log-wealth differences. MDD and
+average drawdown are nonpositive; ulcer and CDaR are nonnegative. CDaR is the
+conditional mean of observed drawdowns at/below the empirical lower-tail
+quantile, with observations tied at the threshold included.
+
+A price-input drawdown window contains that many price observations. Calmar
+instead uses a window of converted returns for both its annualized numerator and
+its maximum drawdown denominator, requiring the preceding price observation.
+Relative and log inputs yield equivalent Calmar ratios. Absolute inputs define
+annualized P&L divided by absolute-currency maximum drawdown. Zero drawdown or
+zero standard/downside deviation yields NaN where a ratio is undefined.
+
+MAD/downside square-root annualization is a retained daily-return convention;
+it is not a distribution-free identity for multi-period P&L.
+
+## VaR and expected shortfall
+
+VaR is reported in input return/P&L units; positive numbers denote losses. A VaR
+quantile may be negative when the relevant outcome is a gain; it is not floored
+at zero. The package-level `sq.var` default horizon is **10 observations**, while
+`ValueAtRisk` directly defaults to **1**. Specify `holding_period` explicitly in
+research code.
+
+- `historical`: negative empirical lower-tail return quantile.
+- `delta-normal` (`parametric` alias): zero-mean Gaussian linear approximation.
+- `delta-gamma-normal`: supplied-Hessian quadratic P&L with moment-matched normal
+  quantiles.
+
+VaR supports `sqrt_time`, `linear`, `none`, and historical `overlapping` scaling.
+`sqrt_time` is a modelling approximation and warns when applied to historical
+VaR for multiple periods. `overlapping` first constructs the observed horizon
+returns, then uses the requested rolling number of those horizon observations.
+Adjacent horizon observations overlap and are dependent. No false independence
+assumption is needed to calculate their empirical quantile.
+
+Weights may be a sequence, dictionary or labelled pandas Series. Series are
+aligned to asset labels; positive-net weights normalize to sum to one. Zero-net
+or negative-net vectors are retained as supplied. Missing active-factor values
+make that portfolio observation unknown; a zero-weight factor does not remove
+it. For log/absolute inputs, aggregation is a linear factor combination, not a
+claim about an exact discrete buy-and-hold wealth process.
+
+For zero-mean Gaussian factors and quadratic P&L:
+
+```{math}
+X\sim N(0,\Sigma),\quad P=w^\top X+\tfrac12 X^\top G X,
+```
+
+```{math}
+m=\tfrac12\operatorname{tr}(G\Sigma),\quad
+v=w^\top\Sigma w+\tfrac12\operatorname{tr}(G\Sigma G\Sigma),\quad
+\operatorname{VaR}_\alpha\approx z_\alpha\sqrt{v}-m.
+```
+
+`gamma_matrix` must be finite, symmetric, labelled/dimensioned for the selected
+factors, in the same input units and already position-weighted. It cannot be
+inferred from squared historical factor returns. Per-asset delta-gamma columns
+are unit-delta single-factor diagnostics using the supplied `G_ii`; the
+`Portfolio` result uses the full weights and Hessian. These columns are not an
+additive risk allocation. The quadratic P&L generally has a non-Gaussian
+distribution, so this is an approximation. Under default horizon scaling, use
+`Sigma_h=h*Sigma`; gamma effects are calculated after this covariance change.
+`linear` scales factor shocks by h and therefore covariance by h squared.
+
+The old `market_regime_threshold` and `vol_scaling_factor` arguments remain for
+call compatibility. They do not modify the result and nondefault values emit a
+deprecation warning. Missing gamma emits a deprecation warning and raises an
+error when delta-gamma is selected.
+
+Historical CVaR/ES integrates the fractional empirical tail mass, avoiding a
+rounded-up count bias. Parametric ES/normal EVaR scale the mean by h and volatility
+by square-root h (or by h under linear scaling). Historical ES square-root
+scaling remains an approximation. The legacy `erm` function is a fixed-z
+Chernoff tail bound `(log mean exp(-z*R) - log(1-confidence))/z`; it is not the
+confidence-independent conventional entropic risk measure. `evar` implements
+normal-distribution EVaR. No optimized empirical EVaR or alternate distribution
+calibration is implied.
+
+## Simulations and historical GBM fitting
+
+```python
+import numpy as np
+from squarequant.monte_carlo.montecarlo import MonteCarloSimulator
+import squarequant as sq
+
+w = sq.brownian(T=1, N=32, nsims=100, seed=42)
+gbm = sq.gbm_paths(S0=100, mu=0.05, sigma=0.2, N=32, nsims=100, seed=42)
+correlated = sq.gbm_correlated_paths(
+    np.array([100., 100.]), np.array([0.05, 0.03]), np.array([0.2, 0.15]),
+    N=32, nsims=100, seed=42, correlation_matrix=np.array([[1., 0.5], [0.5, 1.]]),
+)
+```
+
+Paths include time zero. N is the number of grid points, so `dt=T/(N-1)`.
+Correlation matrices must be finite, symmetric, positive definite and have unit
+diagonals. The default multi-asset correlation is the identity matrix. Instance
+and static entry points share the same implementations and preserve seeded
+reproducibility. Zero volatility gives deterministic exponential growth.
+
+`MonteCarloSimulator.fit_params` estimates historical GBM parameters from one
+positive price series using population-variance MLE:
+`sigma=std(log_returns, ddof=0)/sqrt(dt)` and
+`mu=mean(log_returns)/dt + sigma**2/2`. This estimates the drift of price under
+the historical sampling measure; it does not impose a risk-neutral drift or
+perform a change of measure. A user may supply another drift to the path
+simulator for another specified modelling measure.
+
+`simplemc` reports the sample mean, unbiased sample variance and an interval
+formed using the selected distribution's quantile times the estimated standard
+error. The normal interval is an asymptotic approximation with estimated
+variance; the t option uses the supplied degrees of freedom. The Laplace option
+is a distribution-quantile heuristic, not an exact finite-sample confidence
+interval for a mean. Invalid samples and degrees of freedom are rejected.
+
+## Optional data downloads
+
+Install `python -m pip install -e '.[data]'` from source. Both a ticker string and
+a list of unique, nonempty ticker strings are accepted. Results use names such
+as `AAPL_Close`.
+
+The yfinance adapter handles single-level columns and both ticker/field and
+field/ticker MultiIndexes. It requests adjusted data by default; explicitly
+requesting `Adj Close` disables automatic adjustment so the named adjusted-close
+field can be retrieved. If `Close` is requested alongside `Adj Close`, `Close`
+is then the unadjusted field. Missing symbols/fields are logged; reconcile your
+requested output when completeness is required.
+
+The Theta adapter targets the existing v2 EOD endpoint and supports `interval='1d'`
+only; it requires a compatible local Theta terminal. It normalizes fields,
+including `Count`, and keeps requested ticker order even with parallel fetching.
+Partial failures are logged and successful symbols remain available. Live
+terminal compatibility, subscriptions and option-specific request parameters
+are outside the offline adapter checks; no live-vendor validation is claimed.
+
+`DownloadConfig` date defaults are evaluated per instance. Explicit dates require
+zero-padded ISO format and ordered endpoints. Provider dependencies are lazy
+imports, so the numerical API remains usable without them.
+
+## Executable example
+
+`python examples/risk_metrics_demo.py` uses no network or credentials. Its JSON
+output exercises all metric groups and all simulation wrappers. Key expected
+values are historical VaR `0.037`, 62.5% historical ES `0.03333333333333333`,
+sample mean `2.5`, Brownian shape `[3, 8]`, and correlated Brownian/GBM shapes
+`[2, 3, 8]`.

squarequant-0.4.0.dev1/examples/risk_metrics_demo.py

@@ -0,0 +1,63 @@
+"""Deterministic, offline demonstration of every statistics/simulation API group.
+
+Install from the project root with: python -m pip install -e '.[dev]'
+Then run: python examples/risk_metrics_demo.py
+"""
+
+import json
+
+import numpy as np
+import pandas as pd
+
+import squarequant as sq
+
+
+def run() -> dict:
+    returns = pd.DataFrame({"A": [-0.04, -0.02, 0.01, 0.02], "B": [0.01, -0.01, 0.03, -0.02]})
+    result = {}
+    for name in [
+        "sharpe",
+        "sortino",
+        "vol",
+        "mdd",
+        "calmar",
+        "cvar",
+        "semidev",
+        "avgdd",
+        "ulcer",
+        "mad",
+        "erm",
+        "evar",
+        "cdar",
+    ]:
+        kwargs = dict(window=4)
+        if name in {"sharpe", "sortino"}:
+            kwargs["freerate_value"] = 0
+        if name == "cvar":
+            kwargs.update(holding_period=1, confidence=0.625)
+        frame = getattr(sq, name)(returns, ["A"], **kwargs)
+        result[name] = float(frame.iloc[-1, 0])
+    for method in ["historical", "delta-normal", "delta-gamma-normal"]:
+        kwargs = {"gamma_matrix": np.array([[2.0]])} if method == "delta-gamma-normal" else {}
+        frame = sq.var(returns, ["A"], window=4, holding_period=1, method=method, **kwargs)
+        result["var_" + method] = float(frame.Portfolio.iloc[-1])
+    prices = pd.DataFrame({"A": [100.0, 80.0, 90.0, 95.0]})
+    result["calmar_from_prices"] = float(sq.calmar(prices, ["A"], window=3, use_returns=False).iloc[-1, 0])
+    result["sample_mean"] = sq.simplemc([1.0, 2.0, 3.0, 4.0])["sample_mean"]
+    result["brownian_shape"] = list(sq.brownian(N=8, nsims=3, seed=42).shape)
+    result["correlated_brownian_shape"] = list(
+        sq.correlated_brownian(N=8, nsims=3, seed=42, correlation_matrix=np.eye(2)).shape
+    )
+    result["gbm_shape"] = list(sq.gbm_paths(N=8, nsims=3, seed=42).shape)
+    result["correlated_gbm_shape"] = list(
+        sq.gbm_correlated_paths(np.ones(2), np.zeros(2), np.ones(2) * 0.2, N=8, nsims=3, seed=42).shape
+    )
+    result["version"] = sq.__version__
+    assert abs(result["var_historical"] - 0.037) < 1e-12
+    assert abs(result["cvar"] - 1 / 30) < 1e-12
+    print(json.dumps(result, indent=2, allow_nan=False))
+    return result
+
+
+if __name__ == "__main__":
+    run()