econometrics
Analyze price and return series with unit root, cointegration, causality, ARIMA/VAR forecasts, regressions, causal designs, diagnostics and regime tests to support financial research.
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) 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) and get_move_significance (how unusual each change of a series is: the change in units of its trailing volatility and VaR, its percentile among earlier moves and 'Largest Since', the last date a move in the same direction was as large; e.g. series='rates:get_treasury_rates:2 Year' with changes='difference' and limit=-1 for the latest daily move of the 2-year yield in points and 'the largest one-day rise since'; start_date a year or more back, as the volatility needs a year of moves). get_level_significance (how unusual the latest value of each series is: its percentile and Rank (1 for the highest, e.g. Rank 3 is 'the 3rd highest since' the Start Date) in the series' own history and the last dates it was at least as high ('Highest Since') and as low ('Lowest Since'), e.g. series='rates:get_long_term_interest_rate:United States' with period='monthly' and start_date='2000-01-01'; the answer depends on start_date, which the Start Date column shows; it also gives the Start Value and the Change Since Start (latest / first - 1, a decimal), the change of any series between start_date and its latest value, e.g. series='macroeconomics:get_housing_starts:United States' with period='monthly' and start_date='2021-01-01'; and the Highest and Lowest of the range (the latest value included) with the first date each was reached (Highest Date, Lowest Date) and the Change From Highest and Change From Lowest (latest / highest - 1 and latest / lowest - 1, decimals), so start_date anchors an event window: tickers='BZ=F' with start_date='2026-02-27' gives Brent's close that day, its peak since, the date of the peak and the fall from it; also the Multiple Since Start and Annualised Change (the compound annual rate between start_date and the latest value, e.g. CPI 1970 to now) and the Largest Drawdown with its Drawdown Peak Date, Drawdown Trough Date and Recovery Date (peak to trough and when the peak was regained, of any series)) and get_streaks (the streak each series is on: the Sign of its latest value, the Run Start and Run Length of the current run, the Previous Sign, Previous Run Start, Previous Run End and Previous Run Length, and the longest earlier run of the same sign, lengths in observations, e.g. months with period='monthly'; column='Return' counts rises and falls instead; level=0.02 counts the runs above and below 2% instead of zero, e.g. years of inflation below 2%) and get_window_change_by_year (the change over the same months of every year, from_month= and to_month= as numbers, e.g. 2 and 10 for February to October, per year with the Start Value, End Value, Change (a decimal), Rank (1 for the largest) and Largest Since (the last earlier year with a change at least as large), e.g. series='macroeconomics:get_consumer_price_index:United States' with start_date='2000-01-01'; for a rate pass changes='difference'). All three take spread_over= (with ratio=true the other series divided by it instead, e.g. exports over GDP) with the name of one of the series to measure every other series minus it instead, e.g. series='macroeconomics:get_economic_calendar:China:Producer Price Index YoY; macroeconomics:get_economic_calendar:China:Inflation Rate YoY' with spread_over='China Inflation Rate YoY' and period='monthly' for the spread of producer over consumer price inflation (named 'China Producer Price Index YoY - China Inflation Rate YoY'). Two indicators with the same country are named after their indicator too, e.g. series='rates:get_mortgage_rate_30_year:United States; rates:get_long_term_interest_rate:United States' with spread_over='United States Long Term Interest Rate' for the mortgage spread over the 10-year Treasury. A spread exists on the dates both series have: without period= a weekly series minus a daily one is measured on the weekly dates; period='weekly' or 'monthly' takes the last value of each period of both. No need to fetch price data first. Requires tickers='AAPL' — use comma-separated values for multiple tickers. With series= of indicators by ticker, basket=true adds the tickers up into one company, 'Total', a series of its own (e.g. series='solvency:get_capex_coverage_ratio:MSFT,AMZN,GOOGL,META' with basket=true and quarterly=true for the level significance of their combined capex coverage). 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, and also gives the changes of get_level_significance (Change Since Start, Change From Highest and Lowest, Largest Drawdown) and get_window_change_by_year in points instead of relative changes, e.g. series='rates:get_long_term_interest_rate:United States' with start_date='2026-09-30', end_date='2026-10-30' and changes='difference' for the change of the 10-year yield over October (-0.0035 is -0.35 percentage points). With series=, period= is also passed to every indicator that is published at that period (period='monthly' reads a monthly series as its source publishes it); an indicator that is not is read at its own frequency. Use start_date for a long enough history.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"indicator": "<indicator>"
},
"name": "econometrics"
}
}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 |
| rank | No | true ranks the tickers (or countries) within every period, from the highest value (rank 1) to the lowest, and compares each with its neighbour toward the middle of the ranking: the Difference (in points for returns) and the Multiple (only when both have the same sign), so the first and last rank show how far the best and the worst stand apart, e.g. a fall more than twice as large as the next one. Needs a value per period and ticker; pick one field with show_columns where there are more. | |
| 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). | |
| alpha | No | The tail probability of the trailing historic Value at Risk the VaR Multiple divides by (0.05 for the 95% VaR). | |
| level | No | Level of government: 'consolidated' (longest history), 'general' (central, state and local government and social security) or 'central'. | |
| 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, and rows per ticker (an earnings calendar) are selected per ticker. For ETF holdings the largest (or, negative, the smallest) by weight, and for a list (e.g. news or a screener) its length. 0 returns every row. | |
| 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. | |
| ratio | No | For get_level_significance: Whether to divide every other series by the spread_over series instead of subtracting it (named "<series> / <spread_over>"), e.g. exports over GDP or one country's yield over another's. For get_streaks, get_window_change_by_year: Whether to divide every other series by the spread_over series instead of subtracting it (named "<series> / <spread_over>"). | |
| basket | No | Also analyse the tickers as one company, 'Total': its statements are the sums of theirs and its ratios are calculated on those sums (per-share figures stay empty). | |
| 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'; for get_factor_analysis the output of a metric with several, e.g. 'Signal Line'. 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; left empty, today (or the indicator's own window). | |
| 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 |
| to_month | No | The month the window ends, 1 to 12. | |
| 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. | |
| from_month | No | The month the window starts, 1 (January) to 12 (December). | |
| 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; left empty, five years before today (or the indicator's own window). | |
| n_bootstrap | No | The number of bootstrap resamples used for coefficient standard errors, overriding `statsmodels`' default analytic (kernel density-based) standard errors. | |
| spread_over | No | For get_level_significance: The name of a series to subtract from every other series, so the spreads over it are measured instead (named "<series> - <spread_over>"), e.g. producer price inflation over consumer price inflation. The spread exists on the dates both series have, so with period="daily" a weekly series minus a... For get_streaks: The name of a series to subtract from every other series, so the streaks of the spreads over it are measured instead (named "<series> - <spread_over>"), e.g. producer price inflation over consumer price inflation. The spread exists on the dates both series have, so with period="daily" a weekly... For get_window_change_by_year: The name of a series to subtract from every other series, so the spreads over it are measured instead. | |
| 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. | |
| deflate_with | No | With series: the country whose consumer price index the indicators that take deflate_with are deflated with, e.g. 'United States' for 'macroeconomics:get_commodity_prices:Gold' in real terms. | |
| 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'; 'None' for no benchmark. | 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 the benchmark of a Toolkit. | |
| 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 | The independent (predictor) asset(s). | |
| 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 |