econometrics
Read-onlyIdempotent
Analyze price or return series with unit root, cointegration, causality, VAR/ARIMA, regression, and causal-design tests—using tickers or custom indicator series.
Instructions
Statistical and econometric analysis of price or return series: unit root tests (ADF, KPSS, Phillips-Perron, Zivot-Andrews), cointegration (Engle-Granger, Johansen, VECM), Granger causality, VAR forecasts, impulse responses and variance decomposition, ARIMA forecasts, regressions (OLS, WLS, GLS, quantile, logistic, probit, IV/2SLS, Fama-MacBeth, fixed and random effects panels; get_wls estimates its weights from the regression's residuals with weights='feasible' and get_gls an AR(1) error covariance with omega='ar1', the defaults; get_wald_test takes restriction_matrix as rows of numbers, e.g. [[0, 1, 0], [0, 0, 1]], with one column per coefficient, the Intercept first), causal designs (difference-in-differences, event study, regression discontinuity, synthetic control, propensity score matching), diagnostics (ARCH-LM, Jarque-Bera, Ljung-Box, Durbin-Watson, Breusch-Pagan, White, Ramsey RESET, VIF, Chow, CUSUM, variance ratio), forecast comparison (Diebold-Mariano, RMSE, MAE), regimes and dynamics (get_markov_regime_switching: calm and turbulent regimes with their mean, volatility and expected duration, probabilities=true per date; get_structural_breaks: Bai-Perron dates at which the mean shifts; get_time_varying_beta: Kalman filter alpha and beta per date against the benchmark; get_dcc_garch: DCC-GARCH correlation of every pair per date, parameters=true for the estimates) and get_pairs_trading (hedge ratio, half-life, cointegration p-value, z-score and signal per pair, window= for a rolling z-score, time_series=true per date). No need to fetch price data first. Requires tickers='AAPL' — use comma-separated values for multiple tickers. To analyze any other indicator instead of prices, pass series= with references separated by ';', each tool:indicator:tickers-or-countries with an optional :column, e.g. series='valuation:get_price_to_earnings_ratio:AAPL,MSFT' (quarterly=true for quarterly ratios), series='macroeconomics:get_inflation_rate:United States,Germany' or series='rates:get_government_bond_yield_curve:United States:2Y; rates:get_government_bond_yield_curve:United States:10Y'; each ticker or country becomes a series named after it (with the column, e.g. 'United States 10Y'), which dependent_ticker and independent_tickers name. The series themselves are the 'Adj Close' column (unit root, cointegration, breaks) and their changes the 'Return' column (regressions, diagnostics); changes='difference' suits rates and ratios. Use start_date for a long enough history.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| d | No | For get_arima_forecast: The number of times to difference the series. For get_out_of_sample_validation: The ARIMA differencing order (`model="arima"` only). | |
| p | No | For get_arima_forecast: The autoregressive order. For get_out_of_sample_validation: The ARIMA autoregressive order (`model="arima"` only). | |
| q | No | For get_arima_forecast: The moving-average order. For get_out_of_sample_validation: The ARIMA moving-average order (`model="arima"` only). For get_variance_ratio_test: The number of periods to sum returns over. Leave unset to use the default of the indicator you selected. Defaults are 1 for get_arima_forecast, get_out_of_sample_validation; 2 for get_variance_ratio_test. | |
| tau | No | The quantile to fit, in (0, 1). | |
| lags | No | The number of lags (past periods) the test or model uses, e.g. 1 or 5. Leave unset to use the default of the indicator you selected. Defaults are 1 for get_impulse_response_function, get_out_of_sample_validation, get_var_forecast, get_variance_decomposition; None for get_kpss_test, get_phillips_perron_test; 10 for get_ljung_box_test; 5 for get_arch_lm_test. | |
| loss | No | The loss function to compare forecast errors with, one of "squared" or "absolute". | squared |
| trim | No | The fraction of observations excluded from the candidate break date search at the start and end of the sample. Must be in [0, 1/3). | |
| limit | No | The rows to return, like head and tail: 5 for the first five, -5 for the last five (the most recent of a time series). A table with its periods as columns (financial statements, ratios) keeps its first or last periods instead. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. | |
| model | No | Either "arima" or "var". | arima |
| omega | No | The (symmetric, positive-definite) error covariance structure, up to a scalar, shape `(n, n)`, or "ar1" to estimate an AR(1) structure from the regression's own residuals (Prais-Winsten). | ar1 |
| power | No | The highest power of the fitted values to add. | |
| breaks | No | The number of breaks to find instead of choosing it by the BIC. | |
| column | No | The price column to use, e.g. 'Close' or 'Adj Close'. Leave unset to use the default of the indicator you selected. Defaults differ between indicators. | |
| cutoff | No | The threshold value of `running_variable_ticker` at which the discontinuity is estimated. Leave unset to use the default of the indicator you selected. Required by: get_regression_discontinuity. | |
| kernel | No | One of "uniform" or "triangular". | uniform |
| period | No | Observation frequency, e.g. 'daily', 'weekly', 'monthly', 'quarterly', or 'annual' (supported values differ per method). | |
| series | No | Analyze the indicators of other tools instead of the tickers' prices: references separated by ';', each tool:indicator:tickers-or-countries with an optional :column, e.g. 'valuation:get_price_to_earnings_ratio:AAPL,MSFT; macroeconomics:get_inflation_rate:United States' or 'rates:get_government_bond_yield_curve:United States,Germany:10Y'. Every ticker or country becomes a series named after it, which dependent_ticker and independent_tickers then name. Use start_date for a long enough history. | |
| window | No | The number of periods the indicator looks back over, e.g. 14 or 20. | |
| caliper | No | The maximum allowed logit-propensity-score matching distance. | |
| changes | No | With series: how their changes (the 'Return' column the regressions and diagnostics use) are calculated: 'percentage' (default), 'log', 'difference' (for rates and ratios) or 'none' (the series are changes already). The series themselves are the 'Adj Close' column the unit root and cointegration tests use. | |
| lambda_ | No | The decay factor used by the "ewma" method. | |
| max_lag | No | The maximum number of lagged differences to consider. Leave unset to use the default of the indicator you selected. Defaults are None for get_augmented_dickey_fuller, get_engle_granger_cointegration, get_zivot_andrews_test; 5 for get_granger_causality. | |
| maxlags | No | The maximum lag to include when estimating the HAC (Newey-West) covariance matrix, only used when `cov_type="HAC"`. | |
| periods | No | For get_impulse_response_function: The number of periods ahead to trace the response out to. For get_variance_decomposition: The forecast horizon to decompose out to. | |
| regimes | No | The number of regimes. | |
| tickers | No | Comma-separated ticker symbols, e.g. 'AAPL,MSFT,GOOGL'. | |
| weights | No | The (positive) weight of each observation, aligned to the same period index as the return data (e.g. `1 / rolling_variance`), or "feasible" to estimate them from the regression's own residuals with the feasible GLS procedure of Wooldridge (2016). | feasible |
| clusters | No | For get_ols: The cluster label for each observation (e.g. a coarser time bucket derived from the return index, to correct for within-period correlation), required when `cov_type="cluster"`. Aligned to the regression's own index before use, so it may be indexed by the full period index even though the... For get_wls: The cluster label for each observation, required when `cov_type="cluster"`. | |
| cov_type | No | For get_ols: Which covariance estimator to use for the standard errors -- one of "nonrobust" (classical, assumes homoskedastic errors), "HC0"/"HC1"/"HC2"/"HC3" (heteroskedasticity-robust), "cluster" (cluster-robust, requires `clusters`) or "HAC" (Newey-West, heteroskedasticity-and-autocorrelation-consistent,... For get_wls: Which covariance estimator to use, applied to the weighted/ transformed problem -- see `get_ols`'s `cov_type` for the full list of options. | nonrobust |
| end_date | No | End of the date range in YYYY-MM-DD format. | 2026-10-27 |
| gap_days | No | Number of trading days between the end of the estimation window and the event date. | |
| method_a | No | The first volatility forecasting method, one of "ewma" or "rolling". | ewma |
| method_b | No | The second (competing) volatility forecasting method, one of "ewma" or "rolling". | rolling |
| bandwidth | No | The maximum distance from `cutoff` an observation may be to be included in either local regression. | |
| det_order | No | Which deterministic term to include: -1 (none, Johansen's case 1), 0 (an unrestricted constant, case 3) or 1 (a linear trend, evaluated against the case 5 critical values). The critical values are those of MacKinnon, Haug & Michelis (1999). | |
| indicator | Yes | Name of the specific metric to calculate, one of the listed values. Required — search_metrics finds the indicator (and its tool) for a metric by name. | |
| k_ar_diff | No | The number of lagged first differences to include as short-run dynamics. | |
| quarterly | No | Return quarterly data instead of annual when True. | |
| break_date | No | The date (e.g. "2021-06-30") at which to split the sample -- all periods starting on or after this date form the "after" sub-sample, everything before it forms the "before" sub-sample. Leave unset to use the default of the indicator you selected. Required by: get_chow_test. | |
| event_date | No | The date of the event (e.g. "2023-05-04"). Must fall within the Toolkit instance's daily historical data. Leave unset to use the default of the indicator you selected. Required by: get_event_study. | |
| log_prices | No | Whether to use log prices, so the hedge ratio is an elasticity. | |
| max_breaks | No | The most breaks considered. | |
| parameters | No | Whether to return the estimated parameters (a, b and the GARCH persistence of every asset) instead of the correlations. | |
| regression | No | Which deterministic terms to include, one of "n" (none), "c" (constant) or "ct" (constant and trend). | c |
| start_date | No | Start of the date range in YYYY-MM-DD format. | 2021-10-28 |
| n_bootstrap | No | The number of bootstrap resamples used for coefficient standard errors, overriding `statsmodels`' default analytic (kernel density-based) standard errors. | |
| time_series | No | Whether to return the Spread, Z-Score and Signal per date instead of the summary. | |
| window_size | No | The rolling window size used by the "rolling" method. | |
| add_constant | No | Whether to include an intercept. | |
| exit_z_score | No | The z-score whose crossing on the way back closes a position (0 closes when the spread is back at its mean). | |
| show_columns | No | Comma-separated names to filter the output. For historical data use the key names visible in any response record (e.g. 'Close,Volume,Return'). For financial statements use the 'metric' field values from the response (e.g. 'Revenue,Net Income,EBITDA'). Call the tool once without this parameter to see all available names, then repeat with show_columns to reduce response size and token usage. | |
| significance | No | The significance level (one of 0.01, 0.05, 0.10) at which the Johansen trace test determines the cointegrating rank. | |
| time_effects | No | Whether to control for entity-invariant, time-specific shocks. | |
| asset_tickers | No | The ticker(s) forming the cross-section of test assets. | |
| donor_tickers | No | The ticker(s) forming the donor pool the synthetic control is built from. | |
| entry_z_score | No | The z-score at which a position is opened. | |
| other_tickers | No | The other assets to include in the VAR system alongside the ticker being validated (`model="var"` only). | |
| probabilities | No | Whether to return the smoothed probability of every regime per date instead of the summary. | |
| within_period | No | Whether to calculate the test within the specified period or for the entire period. Thus whether to look at the test within a specific year (if period = 'yearly') or look at the entirety of all years. Note that this requires intraday data when period = 'daily', since a single day only nests... | |
| entity_effects | No | Whether to control for time-invariant entity-specific characteristics. | |
| equal_variance | No | Whether to assume the two samples share a common variance (Student's pooled t-test) instead of Welch's (unequal-variance) t-test. | |
| factor_tickers | No | The ticker(s) whose returns are used as the risk factor(s) (e.g. "Benchmark" for a single-factor/CAPM-style test). | |
| forecast_steps | No | The number of periods ahead to forecast. | |
| orthogonalized | No | Whether to orthogonalize the shocks via a Cholesky decomposition of the residual covariance matrix -- see `time_series_model.get_impulse_response_function`. | |
| pre_event_days | No | Number of trading days before the event date included in the event window. | |
| suspect_ticker | No | The (possibly endogenous) asset being tested. Leave unset to use the default of the indicator you selected. Required by: get_hausman_wu_test. | |
| train_fraction | No | The fraction of observations used for training; the remainder is the holdout. | |
| treated_ticker | No | The asset believed to be affected by an event/ intervention starting at `treatment_period`. Leave unset to use the default of the indicator you selected. Required by: get_synthetic_control. | |
| treatment_date | No | The date the event/treatment occurs, in the same format accepted by `pd.Timestamp`. Observations on or after this date are `Post = 1`. Leave unset to use the default of the indicator you selected. Required by: get_difference_in_differences. | |
| control_tickers | No | The untreated comparison asset(s). | |
| minimum_segment | No | The smallest segment as a share of the observations (the trimming). | |
| post_event_days | No | Number of trading days after the event date included in the event window. | |
| treated_tickers | No | The asset(s) subject to the event/treatment. Leave unset to use the default of the indicator you selected. Required by: get_difference_in_differences. | |
| benchmark_ticker | No | Ticker used as the market benchmark, e.g. 'SPY' or '^GSPC'. | SPY |
| dependent_ticker | No | The outcome asset. Leave unset to use the default of the indicator you selected. Required by: get_f_test, get_hausman_wu_test, get_iv_2sls, get_likelihood_ratio_test, get_propensity_score_matching, get_regression_discontinuity. Defaults are None for get_breusch_pagan_test, get_chow_test, get_durbin_watson_test, get_event_study, get_gls, get_logistic_regression, get_ols, get_probit_regression, get_quantile_regression, get_ramsey_reset_test, get_wald_test, get_white_test, get_wls. | |
| include_constant | No | For get_arima_forecast: Whether to estimate the mean of the differenced series (its drift for `d >= 1`). For get_out_of_sample_validation: Whether the ARIMA model estimates a free intercept (`model="arima"` only). | |
| treatment_period | No | The first post-treatment period -- periods at or after this value (within `period`'s index) are treated as post-treatment, everything before as pre-treatment (used to fit the synthetic control's weights). Leave unset to use the default of the indicator you selected. Required by: get_synthetic_control. | |
| treatment_ticker | No | The asset whose return, once it exceeds `treatment_threshold`, defines the treatment indicator. Leave unset to use the default of the indicator you selected. Required by: get_propensity_score_matching. | |
| covariate_tickers | No | The asset(s) used as covariates to estimate the propensity score -- should include asset(s) believed to drive selection into "treatment". Leave unset to use the default of the indicator you selected. Required by: get_propensity_score_matching. | |
| dependent_tickers | No | For get_fixed_effects, get_hausman_test, get_random_effects: The panel of entity tickers to explain. For get_time_varying_beta: The assets whose beta is estimated. | |
| endogenous_ticker | No | The endogenous regressor asset(s) -- suspected correlated with the error term. Leave unset to use the default of the indicator you selected. Required by: get_iv_2sls. | |
| estimation_window | No | Number of trading days used to estimate the market model. | |
| exogenous_tickers | No | Other, non-instrumented control asset(s) included as-is in both stages. | |
| include_benchmark | No | Whether to include "Benchmark" among the assets. | |
| independent_column | No | A different historical data column, taken per-entity from each of `dependent_tickers`' own data, to use as the regressor. Mutually exclusive with `independent_tickers`. | |
| independent_ticker | No | The asset the beta is measured against. | |
| instrument_tickers | No | For get_hausman_wu_test: One or more instrument asset(s) for `suspect_ticker` -- assets correlated with `suspect_ticker` but assumed uncorrelated with `dependent_ticker`'s error term. For get_iv_2sls: The excluded instrument asset(s), correlated with `endogenous_ticker` but assumed uncorrelated with the error term. Must supply at least as many instruments as endogenous regressors. Leave unset to use the default of the indicator you selected. Required by: get_hausman_wu_test, get_iv_2sls. | |
| restriction_matrix | No | The `(q, k)` restriction matrix `R`, one row per restriction, one column per coefficient in the same order as `add_constant` (if True, "Intercept" first) followed by the independent ticker(s), e.g. [[0, 1, 0], [0, 0, 1]]. Leave unset to use the default of the indicator you selected. Required by: get_wald_test. | |
| restriction_values | No | The length-`q` vector of hypothesized values. | |
| switching_variance | No | Whether the volatility switches with the regime as well as the mean. | |
| independent_tickers | No | For get_breusch_pagan_test, get_chow_test, get_durbin_watson_test, get_gls, get_logistic_regression, get_ols, get_probit_regression, get_quantile_regression, get_ramsey_reset_test, get_white_test, get_wls: The independent (predictor) asset(s). For get_fixed_effects, get_hausman_test, get_random_effects: The factor ticker(s), whose `column` values are broadcast identically to every entity at each date. Mutually exclusive with `independent_column`. For get_wald_test: The independent (predictor) asset(s), in the order the restriction matrix's columns (after "Intercept", if `add_constant`) refer to them. | |
| treatment_threshold | No | The return threshold defining treatment. | |
| running_variable_ticker | No | The asset (or column) whose value determines which side of `cutoff` an observation falls on. Leave unset to use the default of the indicator you selected. Required by: get_regression_discontinuity. | |
| other_independent_tickers | No | Any other (assumed exogenous) independent asset(s) to include. | |
| restricted_independent_tickers | No | The independent asset(s) in the restricted (smaller) model. Leave unset to use the default of the indicator you selected. Required by: get_f_test, get_likelihood_ratio_test. | |
| unrestricted_independent_tickers | No | The independent asset(s) in the unrestricted (larger) model -- must be a superset of `restricted_independent_tickers`. Leave unset to use the default of the indicator you selected. Required by: get_f_test, get_likelihood_ratio_test. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |