Skip to content

arch

The arch pack has 13 rules, and xpd can fix 6 of them.

The arch rules find code that raises on arch 9.0, options and arguments that arch refuses or never reads, returns in units that break the fit, and random draws without a seed. They run on files that import arch, a library for ARCH and GARCH volatility models, unit root and cointegration tests, bootstraps and multiple comparison tests.

Group What its rules report
Removed API API that arch 8.0 and 9.0 removed
Options and arguments a string or a number that arch refuses, and an argument that arch accepts and never reads
The units of the data returns as decimals, and results that are read in rescaled units
Forecasts and fits forecasts that raise or that compute the same rows many times, and fits that print in a loop
Bootstraps, tests and covariance estimators draws without a seed, results read before compute, and a bandwidth that changed its meaning in 9.0

Every number on the arch rule pages was measured on arch 9.0.0 with NumPy 2.5.5, pandas 3.1.1, SciPy 1.18.1 and statsmodels 0.15.0, unless another release is named. The examples assume that the arch names they use are imported, and names such as returns, prices, losses and x stand for values from your program.

xpd skips a rule document about a newer arch than the one in the project's venv. arch 8.0 removed the RandomState paths of the bootstraps and the distributions. arch 9.0 removed arch.__future__ and the type keyword of hedgehog_plot, and it made some attributes read only. It also started to check every argument. A rule document about such a change carries since, and xpd reads the installed version from the venv as it does for pandas.

on(check a file that imports arch)
if the venv has no arch, or there is no venv
run every document
else if the document's since is above the installed version
skip the document # a project on arch 7.2 gets no report about what 8.0 removed
else
run the document

Each rule ties its report to a name that the file binds to arch, because the rules match the shape of the code and do not know the type of a variable. samples/arch/names.py shows each case.

Code Read by the rules
a call by the name of an arch class or function, such as arch_model(...) or IIDBootstrap(...) yes
a short name that another library may have, such as SPA, MCS or Normal only when the file imports it from arch
a method such as fit, forecast or conf_int on a variable only when the file assigns the variable from an arch name and from nothing else
the same variable bound as a parameter, a loop variable, an as target or one name of a tuple assignment no
an option or a value written in the call, such as vol="gjr" yes
a variable in place of the option or the value no

Every rule document has a proof that was run, and the table gives the five kinds of proof.

Proof How it was run What it shows
interpreter The old form ran on arch 9.0.0. A document with since also ran on the release before the one it names. The old form raises and the new form runs. On the release before, the old form ran or only warned.
same result A fit or a test ran with and without the argument. Both gave the same parameters or the same statistic, so arch does not read the argument.
numbers Both forms ran on the daily S&P 500 returns that ship with arch. The two numbers.
speed Both forms were timed as the median of 3 runs. The two times, and whether the two forms return the same values.
rerun The old form ran twice in fresh objects. The two results differ, and the new form gives the same result twice.

A document is error only on an interpreter proof, and its message names the exception. A document that can also match right code, such as rescale=True on data that needs no rescaling, is a warning.

The rules were then run over two sets of real code, and a rule that reported correct code was narrowed or dropped.

Set Files What the files are
arch's own code at the 9.0.0 tag 202 69 library files, 104 test files, the code blocks of 16 documentation pages, 9 notebooks and 4 scripts
public code 1,303 from 861 repositories 795 Python files and 508 notebooks that GitHub code search found for the import lines of arch, of which 1,268 import arch

Every report was read except the 291 reports of arch-unseeded-draws, which a script checked by looking in each file for a later seed call or state assignment on the same variable. The table gives the reports that were left after the rules were narrowed.

Rule Severity Proof Reports on arch's own code Reports on public code Wrong advice Fix
removed-in-arch error interpreter: ModuleNotFoundError, ImportError, TypeError, AttributeError, ValueError 1 34 0 unsafe
arch-unknown-option error interpreter: ValueError 0 13 0 unsafe
arch-ignored-argument warning same result, and rerun for the two seeds 10 21 1 none
arch-rejected-number error interpreter: TypeError, ValueError 1, over 189 files not run 1 unsafe
unscaled-returns warning numbers: mu 4.02 against 0.056, with optimizer code 4 0 21 0 none
rescaled-units warning numbers: a variance forecast 10,000 times the data's 4 14 7 none
analytic-forecast-horizon error interpreter: ValueError 0 0 no reports none
forecast-per-origin warning speed: 0.106 seconds against 0.0005 1 0 0 none
reindex-is-default info same result: equal frames with and without the argument 20 61 0 safe
fit-output-in-loop info numbers: 240 lines for 20 fits against 0 0 15 0 unsafe
arch-unseeded-draws info rerun: the result differs 109 182 1 none
results-before-compute error interpreter: RuntimeError 2 0 2 none
opt-bandwidth-as-bandwidth warning numbers: 0.5245 against 0.5158 0 0 no reports unsafe

Wrong advice counts the reports where following the message would not fix a real problem in that code, and each rule's page says which reports they are. Before the rules were narrowed, the first run made 508 reports.

Code Reports Wrong advice
arch's library source 1 1, a placeholder bootstrap that a base class builds and never draws from
arch's tests, notebooks and documentation 146 7
public code 361 3

arch-rejected-number was added after a review, when the public code was no longer on disk. It ran over the 189 Python files of arch's repository and made one report, in a test that checks the error it reports.

A rule that reported forecast(start=...) on a result whose fit had no last_obs was written and dropped. The parameters of such a fit have seen the rows that are forecast, and the forecasts did change, but most of the reports were on right code.

Measurement on 1,500 S&P 500 returns, forecasts from row 1,000 on Value
mean difference from the forecasts of a fit that stopped at row 1,000 13%
QLIKE loss with the fit on all rows 0.142
QLIKE loss with the fit that stopped at row 1,000 0.181
reports on public code 14, of which 7 start at the last row and forecast the future, and 4 start at row 0 to draw the fitted path
reports on arch's own code 11, all examples and tests that forecast the fitted rows on purpose

Recall was not measured, because no set of real arch code was held back. The table says how often a rule is wrong when it reports, and not how often it misses. A rule that follows a variable is silent when the file binds the same name to something else anywhere, also in another function. For example, a file that uses res for an arch result and for another object gets no report on res.

removed-in-arch reports code that raises on arch 9.0.0. Each form was run on the release before the removal and on the release that made it, both installed from PyPI, because the release notes of 8.0 do not list what 8.0 removed. No fix of a removed form is safe, because the old form raises and its result cannot be compared with the result of the new form.

Rule Severity Fix What it finds
removed-in-arch error unsafe arch 8.0 or 9.0 removed this form, so the import or the call raises.

The rules in the group report an argument that arch 9.0 refuses or never reads. arch 9.0 checks every argument when a function is called, and it still ignores an argument that does not apply to the model that was asked for.

Rule What it reports What happens
arch-unknown-option a string that is not one of the option's values ValueError
arch-ignored-argument an argument that arch accepts and never reads the code runs and estimates another model or test than the one it describes
arch-rejected-number a number that arch refuses TypeError or ValueError
Rule Severity Fix What it finds
arch-unknown-option error unsafe This text is not one of the values the option takes, so arch raises ValueError.
arch-ignored-argument warning none arch accepts this argument and never reads it for the model or test you asked for, so it has no effect.
arch-rejected-number error unsafe arch refuses this number, such as a float where it counts something, so the call raises.

Give arch returns in percent, and divide a result by scale when you let arch rescale. arch estimates by maximum likelihood, and the optimizer works badly when the variance of the data is far from 1. arch warns DataScaleWarning when the variance is outside the range it accepts, and its message asks for a value between 1 and 1000. Daily returns as decimals have a variance near 0.0001, and the 5,030 daily S&P 500 returns in arch.data.sp500 have 0.000145.

Rule Severity Fix What it finds
unscaled-returns warning none Returns given as decimals make the arch optimizer struggle, so it warns and can stop with poor estimates.
rescaled-units warning none rescale=True lets arch multiply the data, so the volatility, forecasts and parameters come back in rescaled units.

The rules in the group report forecasts that raise or repeat work, and fits that print. The table gives the defaults of the two calls.

Call Default Effect
forecast method="analytic", horizon=1, reindex=False forecasts from the last row unless start names an earlier one
fit disp="final", update_freq=1 prints the steps of the optimizer unless disp="off"
Rule Severity Fix What it finds
analytic-forecast-horizon error none This model has no analytic forecast beyond one step, so forecast with a longer horizon raises ValueError.
forecast-per-origin warning none Calling forecast once for each origin in a loop makes one call where one would do.
reindex-is-default info safe reindex=False has been the default of forecast since arch 6.2, so the argument does nothing.
fit-output-in-loop info unsafe fit prints every iteration and a summary on each call, so a loop of fits floods the output.

Bootstraps, tests and covariance estimators

Section titled “Bootstraps, tests and covariance estimators”

The rules in the group report random draws without a seed, test results read before compute, and a bandwidth whose meaning changed in arch 9.0.

Rule Severity Fix What it finds
arch-unseeded-draws info none This call draws random numbers from a new seed on every run, and np.random.seed does not reach it, so results change from run to run.
results-before-compute error none These results of SPA, StepM, MCS and RealityCheck exist only after compute, so reading them first raises RuntimeError.
opt-bandwidth-as-bandwidth warning unsafe Since arch 9.0, these estimators use opt_bandwidth minus 1 as their bandwidth, so passing opt_bandwidth back gives another estimate.

The pack has no rule for the habits in the table, and the last column gives the reason for each.

Habit What was measured Why there is no rule
SPA, StepM and RealityCheck studentize the losses since arch 9.0 when studentize=True, the default, which did nothing before On the same seeded losses the p-values of SPA were 0.6733, 0.91 and 0.96 on 8.0.0 and 0.67, 0.8967 and 0.9533 on 9.0.0, and the lowest critical value moved from 0.1353 to 1.5984. studentize=False on 9.0.0 gave the numbers of 8.0.0. A rule would report nearly every call, because few calls say studentize
nested=True on the same tests runs a bootstrap inside every replication since 9.0 With 300 replications SPA took 1.14 seconds, against 0.0105 without it and 0.0109 on 8.0.0 The option asks for the extra work
forecast(start=...) on a fit without last_obs forecasts rows that the fit has seen The numbers are under "The proof each rule needs" The rule reported more right code than wrong and was dropped
starting_values from the last window of a rolling fit 40 windows took 0.209 seconds without them and 0.200 with them The fit was not faster
an IIDBootstrap on a series that is correlated in time, where arch's documentation gives the block bootstraps and optimal_block_length CircularBlockBootstrap and MovingBlockBootstrap raise TypeError since 9.0 on a block size that is not a whole number, such as the 55.04 that optimal_block_length returned for one series. StationaryBootstrap takes it. A pattern cannot see whether a series is correlated, and the block size is a variable in such code
a unit root test on the wrong series, or a p-value read against the wrong null hypothesis On 1,000 log prices of the S&P 500, ADF gave a p-value of 0.648 and KPSS gave 0.0001, because the null of ADF is a unit root and the null of KPSS is no unit root A pattern sees neither the series nor the reading
a block_size given as a float It was a variable in every file that was read arch-rejected-number reads only a number written in the call