MCPInstall

statistics-fundamentals

Apply statistical methods to financial data including descriptive statistics, covariance estimation, regression, hypothesis testing, and resampling. Use when the user asks about return distributions, correlation between assets, building a covariance matrix, running a CAPM regression, testing whether alpha is significant, checking if returns are normal, or estimating confidence intervals. Also trigger when users mention 'volatility', 'how correlated are these', 'fat tails', 'skewness', 'R-squared', 'beta of a fund', 'bootstrap a Sharpe ratio', 'shrinkage estimator', 'Ledoit-Wolf', or ask why their optimizer produces unstable weights.

Installs
817
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/joellewis/finance_skills --skill statistics-fundamentals
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads statistics-fundamentals automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

Statistics Fundamentals

Core Concepts

Conventions and Decision Rules

Sample variance: use n-1

When estimating variance or standard deviation from a sample of returns, divide by n - 1 (Bessel's correction), not n. Dividing by n systematically underestimates dispersion. Standard deviation of returns is "volatility"; annualize with sigma_annual = sigma_period * sqrt(periods_per_year) (e.g., * sqrt(12) for monthly, * sqrt(252) for daily).

Normality testing: Jarque-Bera and its limits

JB = (n/6) * (skew^2 + excess_kurtosis^2 / 4), distributed chi-squared with 2 df under the null of normality (5% critical value: 5.99).

Low-power caveat: with small samples (n below roughly 50), JB rarely rejects even for clearly non-normal data — failing to reject is weak evidence of normality, not confirmation. With large samples, financial return series almost always reject due to fat tails and (for equities) negative skewness. Treat the test as a screen, and pair it with a look at the actual skew/kurtosis magnitudes and extreme observations.

Covariance estimation and Ledoit-Wolf shrinkage

The sample covariance matrix Sigma_hat = (1/(n-1)) (X - X_bar)^T (X - X_bar) becomes poorly conditioned or singular when the number of assets p approaches the number of observations n. Plugging it into a mean-variance optimizer then produces extreme, unstable weights that flip with small data changes.

Shrinkage blends the sample matrix toward a structured target:

$$\hat{\Sigma}_{shrunk} = \delta \cdot F + (1 - \delta) \cdot \hat{\Sigma}$$

where F is the target (e.g., scaled identity) and delta is the shrinkage intensity. Ledoit-Wolf (2004) derives the delta that minimizes expected squared Frobenius distance to the true covariance matrix, trading a little bias for a large variance reduction — yielding better-conditioned, invertible matrices and stable portfolio weights.

Note: the bundled script's shrunk_covariance implements a simplified shrinkage-intensity estimate, not the full Ledoit-Wolf estimator. For production work use sklearn.covariance.LedoitWolf.

Regression diagnostics (CAPM and factor models)

For the single-factor CAPM regression R_i - R_f = alpha + beta * (R_m - R_f) + epsilon:

  • beta = rho * sigma_i / sigma_m (market sensitivity); alpha is the risk-adjusted excess return.
  • In a single-factor regression, R^2 = rho^2.
  • Judge coefficients by t-statistics (t = coefficient / SE); with n - 2 df, |t| above roughly 2 indicates 5% significance. A positive alpha point estimate with |t| < 2 is not evidence of skill.
  • Adding regressors always raises R-squared; use adjusted R-squared, AIC/BIC, or cross-validation to guard against overfitting.

Bootstrap procedure

Non-parametric resampling for the sampling distribution of a statistic when analytical standard errors are unavailable (Sharpe ratio, alpha), the distribution is non-normal, or samples are small:

  1. From the original n observations, draw B resamples of size n with replacement (B = 1,000-10,000).
  2. Compute the statistic on each resample.
  3. Percentile method: the (1 - alpha) confidence interval is the alpha/2 and 1 - alpha/2 percentiles of the bootstrap distribution; the bootstrap standard error is the std of the B statistics.

Caveat: the i.i.d. bootstrap ignores autocorrelation and volatility clustering; use block bootstrap for serially dependent return series.

Standard Analysis Workflow

Given a return series, run this sequence:

  1. Descriptive stats — mean, volatility (n-1), skewness, excess kurtosis; annualize for reporting.
  2. Distribution checks — Jarque-Bera (mind the low-power caveat), inspect skew/kurtosis magnitudes and largest outliers; decide whether normal-based methods (parametric VaR, t-tests) are defensible.
  3. Covariance/correlation (multi-asset) — sample covariance and correlation matrices; if p is large relative to n, apply shrinkage before any optimization.
  4. Regression diagnostics — CAPM or factor regression; report alpha/beta with t-stats and R-squared; check residuals for structure.
  5. Bootstrap CIs — for statistics without clean analytical standard errors (Sharpe, alpha, drawdown), bootstrap confidence intervals rather than reporting bare point estimates.

Worked Examples

Example 1: Descriptive Statistics and Normality Test

Given: 12 monthly returns (%): [2.1, -0.5, 1.8, -3.2, 4.5, 0.3, -1.1, 2.7, -0.8, 3.4, 1.2, -0.6]

Mean      = 9.8 / 12 = 0.8167% per month  (~9.8% annualized, simple x12)
s^2       = 52.977 / 11 = 4.816   ->   s = 2.195% per month
Ann. vol  = 2.195% * sqrt(12) = 7.60%
Skewness  = -0.045  (bias-corrected; near symmetric)
Ex. kurt  = -0.42   (bias-corrected; lighter tails than normal)

JB = (12/6) * ((-0.045)^2 + (-0.42)^2 / 4) = 0.09

JB = 0.09 < 5.99 (chi-squared 5% critical, df=2): fail to reject normality. With only 12 observations the test has very low power — this is not evidence that the returns are truly normal.

Example 2: CAPM Regression from Summary Statistics

Given: 24 monthly observations. Fund excess returns: mean 0.8%, std 4.2%. Market excess returns: mean 0.6%, std 3.8%. Correlation 0.85.

beta  = rho * sigma_i / sigma_m = 0.85 * 4.2 / 3.8 = 0.939
alpha = 0.8% - 0.939 * 0.6% = 0.236% per month (~2.84% annualized)
R^2   = rho^2 = 0.7225

Residual std = 4.2% * sqrt(1 - 0.7225) = 2.213%
SE(alpha) = 2.213% / sqrt(24) = 0.452%   ->  t(alpha) = 0.236 / 0.452 = 0.52
SE(beta)  = 2.213% / (3.8% * sqrt(23)) = 0.121  ->  t(beta) = 0.939 / 0.121 = 7.74

With 22 df, the 5% two-tailed critical t is 2.074. Beta is highly significant (7.74 >> 2.074); alpha is not significant (0.52 < 2.074) — despite the positive point estimate, the sample cannot distinguish it from zero.

Common Pitfalls

  • Using population variance instead of sample variance: always use n - 1 (Bessel's correction) when estimating from a sample.
  • Assuming normality when financial returns have fat tails: equity returns typically show negative skewness and positive excess kurtosis; normal-based models (standard VaR) underestimate tail risk. Use Student-t or non-parametric methods.
  • Ignoring non-stationarity: return distributions shift over time (regime changes, volatility clustering). Rolling-window estimation or GARCH may be more appropriate than full-sample statistics.
  • Overfitting with too many regressors: R-squared always rises with added factors; use adjusted R-squared, information criteria, or cross-validation.
  • Unstable covariance matrices with small samples: when p approaches or exceeds n, apply Ledoit-Wolf shrinkage or factor-based covariance models before optimizing.

Running the Script

scripts/statistics_fundamentals.py provides a StatisticsFundamentals class with static methods descriptive_stats, covariance_matrix, correlation_matrix, shrunk_covariance (simplified Ledoit-Wolf — see note above), ols_regression, rolling_regression, bootstrap_mean, and jarque_bera_test.

  • Run: uv run scripts/statistics_fundamentals.py (PEP 723 inline metadata resolves numpy and scipy), or python3 scripts/statistics_fundamentals.py with numpy/scipy installed.
  • Bare invocation (or --verify) prints a demo on synthetic data and asserts the Example 1 worked-example values above (mean 0.8167, std 2.195, JB 0.09 on the 12-month series), exiting nonzero on any mismatch.
  • --help lists the available methods and import usage.
  • For programmatic use, import rather than run: from statistics_fundamentals import StatisticsFundamentals, then call e.g. StatisticsFundamentals.descriptive_stats(...).

Cross-References

  • return-calculations (core plugin): Arithmetic and geometric mean returns, log returns for statistical modeling
  • time-value-of-money (core plugin): Discount rate estimation via CAPM regression; NPV and IRR calculations use statistical inputs
  • factor-investing (wealth-management plugin): Extends the single-factor CAPM/OLS regression to Fama-French multifactor models for alpha attribution and fund evaluation
  • financial-statements (wealth-management plugin): applies descriptive statistics and trend analysis to financial ratios and peer comparisons

FAQ

What does the statistics-fundamentals skill do?

Apply statistical methods to financial data including descriptive statistics, covariance estimation, regression, hypothesis testing, and resampling. Use when the user asks about return distributions, correlation between assets, building a covariance matrix, running a CAPM regression, testing whether alpha is significant, checking if returns are normal, or estimating confidence intervals. Also trigger when users mention 'volatility', 'how correlated are these', 'fat tails', 'skewness', 'R-squared', 'beta of a fund', 'bootstrap a Sharpe ratio', 'shrinkage estimator', 'Ledoit-Wolf', or ask why their optimizer produces unstable weights.

How do I install statistics-fundamentals?

Run npx skills add https://github.com/joellewis/finance_skills --skill statistics-fundamentals in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/statistics-fundamentals/ (personal) or .claude/skills/statistics-fundamentals/ (project).

Which AI agents can use statistics-fundamentals?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is statistics-fundamentals safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains statistics-fundamentals?

It is published by joellewis in joellewis/finance_skills. It has 817 recorded installs.

More from joellewis/finance_skills

View all →

asset-allocation

joellewis/finance_skills

Determine how to distribute capital across asset classes using strategic and tactical allocation frameworks. Use when the user asks about portfolio allocation, mean-variance optimization, Black-Litterman, risk parity, glide paths, or target-date strategies. Also trigger when users mention 'how much in stocks vs bonds', '60/40 portfolio', 'policy portfolio', 'core-satellite', 'liability-driven investing', 'asset-liability matching', or ask how to split their money across investments.

Business & Finance852 installs

quantitative-valuation

joellewis/finance_skills

Estimate intrinsic value of stocks and companies using DCF, dividend discount models, comparable multiples, and residual income. Use when the user asks about discounted cash flow, DCF models, WACC, terminal value, dividend discount models, comparable multiples, or sum-of-the-parts valuation. Also trigger when users mention 'what is this stock worth', 'fair value estimate', 'Gordon growth model', 'free cash flow valuation', 'cost of equity', 'sensitivity analysis', 'exit multiple', or ask whether a stock is overvalued or undervalued.

Business & Finance787 installs

finance-psychology

joellewis/finance_skills

Recognize and mitigate cognitive biases that impair financial decisions, and coach clients toward values-driven financial lives. Use when the user asks about behavioral finance, money psychology, loss aversion, overconfidence, herd behavior, or emotional investing. Also trigger when users mention 'why do I panic sell', 'money fights with my spouse', 'I can never save enough', 'fear of investing', 'lifestyle creep', 'keeping up with the Joneses', 'Rich Life', 'money scripts', or ask how emotions affect financial decisions.

Business & Finance780 installs

commodities

joellewis/finance_skills

Analyze commodity markets including futures curve dynamics, roll yield, and supply/demand fundamentals. Use when the user asks about commodity investing, commodity ETFs, contango, backwardation, roll yield, commodity indices (GSCI, BCOM), or commodities as an inflation hedge. Also trigger when users mention 'oil prices', 'gold as a safe haven', 'agricultural futures', 'convenience yield', 'storage costs', 'natural gas', 'copper demand', or ask why commodity ETF returns differ from spot price changes.

Business & Finance774 installs

investment-policy

joellewis/finance_skills

Construct comprehensive Investment Policy Statements governing return objectives, risk tolerance, and portfolio constraints. Use when the user asks about building an IPS, setting return objectives, assessing risk tolerance, defining investment constraints, or establishing rebalancing and benchmark policies. Also trigger when users mention 'investment plan', 'policy portfolio', 'risk capacity vs willingness', 'spending rate for an endowment', 'foundation payout', 'manager selection criteria', or ask how to document their investment strategy.

order-lifecycle

joellewis/finance_skills

Guide the design and implementation of order lifecycle management in trading systems. Owns FIX application-layer message flows (NewOrderSingle, ExecutionReport, cancel/replace) and order state. Use when building an order state machine for an OMS or EMS, handling cancel/replace race conditions, defining pre-submission validation rules (buying power, position limits, restricted lists), selecting order types and time-in-force instructions, designing multi-leg or OCO or bracket orders, building CAT-compliant audit trails, troubleshooting order rejections or unexpected state transitions, hardening an OMS against edge cases, or implementing order persistence and recovery for failover. Also covers execution-report handling, ClOrdID chaining, and partial fill aggregation. For FIX session management (logon, sequence gaps, disconnects) see exchange-connectivity.

Business & Finance747 installs

Popular testing & qa skills

View category →

tdd

mattpocock/skills

Test-driven development. Use when the user wants to build features or fix bugs test-first, mentions "red-green-refactor", or wants integration tests.

Testing & QA1.2M installs

grilling

mattpocock/skills

Grill the user relentlessly about a plan, decision, or idea. Use when the user wants to stress-test their thinking, or uses any 'grill' trigger phrases.

Testing & QA996.2K installs

migrate-to-shoehorn

mattpocock/skills

Migrate test files from as type assertions to @total-typescript/shoehorn. Use when user mentions shoehorn, wants to replace as in tests, or needs partial test data.

Testing & QA484.1K installs

run-train

lllllllama/rigorpilot-skills

Rigor Train skill for deep learning research repositories. Use when a documented or selected training command should be run conservatively for startup verification, short-run verification, full kickoff, or resume, with command, config, seed, log, checkpoint, status, and metric evidence written to standardized trainoutputs/. Do not use for environment setup, exploratory sweeps, speculative idea implementation, or end-to-end orchestration.

Testing & QA337.8K installs

test-driven-development

obra/superpowers

Use when implementing any feature or bugfix, before writing implementation code

Testing & QA261.8K installs

Use when implementation is complete, all tests pass, and you need to decide how to integrate the work

Testing & QA216.8K installs