Repository navigation
Finalytics 1.0.0-rc.2
Pre-release
Pre-release
Added
Statisticsadds the conditional drawdown at risk at 95% (the mean of the worst 5% of the
drawdowns, as a negative return like the maximum drawdown) and the Ulcer index (the root mean
square of the drawdowns).RelativeStatisticsadds downside and upside betas and capture
ratios. The reports show them, andscripts/reference/downside.pychecks them against a
linear programme, pandas, least squares and empyrical's definitions.shortfall_decomposition(fl.risk.shortfall_decomposition,shortfallDecomposition)
splits a portfolio's historical expected shortfall into each asset's contribution, adding up
to it exactly, withgroup_contributionsfor groups. The minimum-CVaR optimisation report
shows the expected shortfall the weights reach, at its confidence, and gives each asset's
share of it rather than of the variance.- With limits on groups of assets, the optimisation report shows each group's weight against
its limits and its share of the risk (OptimisationReport.groups). StrategyResult.fittedandStrategyReport.fittedsay whether a method fitted the weights to
returns. Fixed weights have no run in sample in the reports, and are described as fixed
weights, not fitted to the returns they are scored on.TailRisk.shortfall_at_varflags a Cornish–Fisher expected shortfall raised to the value at
risk, as the expansion can need when the excess kurtosis is large; the risk report marks it.ScenarioSummary.stress: the scenarios report names the stress of the covariance behind a
scenario's risk after.- A cash balance below zero is a warning in the valuation and the reports that use it
(cash.<account>.<currency>), as when a purchase is recorded without the deposit that paid for
it. It is not an error, so that margin and late deposits can still be recorded. CovarianceMethodreads from its name alone ("ledoit_wolf") as well as from an object, and an
exponentially weighted covariance without a decay has 0.94, in every option that takes one.SolveStatus::reason: why an optimisation found no weights, in words.- The Rust comparison and backtest builders take every option
optimisetakes:
uncertainty,budget,linkage,expected_returnandrisk_free_rate; Python's
compareandbacktesttakerisk_free_rate. nameonoptimisein Rust (.name(..)) and JavaScript ({ name }), as in Python.saveHtml(path, name?)on reports and results in Node.js, assave_htmlin Python;
JavaScript results'toTextandtoHtmltake the report's name, and TypeScript declares
them.- The Rust report builder has a setter for every report option:
periods_per_year,
covariance,confidences,rolling_window,histogram_bins,top,
long_term_after_days,expected_return,frontier_pointsandbenchmark_weight. comparetakes fixed weights beside methods:.weights("60/40", [..])in Rust (repeatable),
weights={"60/40": {..}}in Python and{ weights: { "60/40": {..} } }in JavaScript. They
are held and rebalanced as the methods are and scored on the same periods, and described as
fixed weights;methodsmay be left out when weights are given.benchmark_namenames the benchmark of a comparison or backtest in every language:
Benchmarkby default, or the column's name for an index's prices.Assets::frontierreturnsFrontierPortfolios, with their weights by asset (in the assets'
order in JavaScript), rather than unlabelled lists.- A methods page for backtests and comparisons (
docs/methods/backtests.md): how weights are
held, rebalanced and charged for, the three kinds of validation, and what the reports show. - Four covariance estimators: shrinkage towards constant correlation (
constant_correlation),
a statistical factor model of the first principal components ({"type": "statistical", "factors": 3}), the sample correlation denoised by the Marchenko–Pastur edge (denoised),
and the analytical nonlinear shrinkage of Ledoit and Wolf (2020) (nonlinear_shrinkage), in
Assets(covariance=...)andfl.risk.covariance.scripts/reference/estimators.pychecks
them against translations of the authors' code and NumPy. - Estimators of mean returns:
Assets(mean_returns="james_stein")shrinks the means towards
their average with the Efron–Morris intensity, and"ewma"weights recent returns more
(MeanMethod,finalytics::risk::mean_returns). Optimisation, the efficient frontier,
backtests andmean_returns()use them, and the reports name them. The historical mean is the
default; the risk-free asset's rate stays its historical mean. minimum_semivarianceandminimum_cdaroptimise the downside of the periods' returns: the
mean square of the returns below zero, and the conditional drawdown at risk of the summed
returns (Chekhlov, Uryasev and Zabarankin, 2005). Withtarget, they andminimum_cvarkeep
an annual expected return of at leasttarget. In the optimiser they are
Objective::MinimumSemivarianceandObjective::MinimumCdar, with
Constraints.min_returnfor the floor.min_effective_assetsholds the effective number of assets,1 / sum w^2, at or above a
floor, the norm constraint of DeMiguel, Garlappi, Nogales and Uppal (2009)
(Constraints.min_effective_assetsin the optimiser). Bounds that leave room for fewer are
reported before solving.scripts/reference/downside_objectives.pychecks the new objectives
and limits against CVXPY.optimise(resample=200)averages the optimal weights for 200 histories simulated from the
assets' estimates (Michaud, 1998), inoptimise,compareandbacktest; the result's
resampledholds each weight's standard deviation across them, and the report says how many
were solved.Resampling.periods_per_yearsimulates annualised estimates period by period, so
that they are as uncertain as estimates from that many periods of returns.- Rebalancing every so many periods,
Rebalance::Every { periods }(fl.Every(periods=21),
{ every: { periods: 21 } }), counted from the first period of each run; walk-forward
validation refits on it as on a calendar schedule. - A theme for report pages:
theme="light"or"dark"onto_html,save_htmlandshowin
Python, the last argument oftoHtml,saveHtmlandshowin JavaScript, and
report.with_theme(Theme::Dark)in Rust. The default,"auto", follows the reader's setting
as before. Assets::origin(): the date of the prices the first returns are measured from. Backtest and
optimisation reports start the growth of 100 at 100, and the drawdown at 0, on the date a run
enters: that date, or the end of the period before a test.
Changed
- Turnover is one-way everywhere: half the sum of the absolute weight changes, the share of the
portfolio bought (or, equally, sold). Backtests already measured it so; the turnover limit of an
optimisation (Turnover.limit) and the turnover of a rebalance proposal now do too, so a limit of
0.2 allows 20% of the portfolio to be bought, where it allowed 10% before, and a proposal's
turnover is half what rc.1 reported. The reports say which convention they use. - The Sortino ratio is measured against the risk-free rate, as the Sharpe ratio is, in the
portfolio, comparison and backtest reports, which state the rate. It was measured against zero. - Cash at a risk-free rate earns the rate compounded to each period,
(1 + r)^(1 / P) - 1, as the
statistics convert it, rather thanr / P. - Money-weighted returns over periods shorter than a year (MTD, QTD, YTD) are shown over the
period, as the time-weighted returns beside them are, rather than annualised. - The date of a rebalance is
as_ofin Python and JavaScript, as in Rust and every report
(portfolio.rebalance(targets, as_of="2026-06-30")); it wasdate. - Python's
datasets.price_table()isdatasets.asset_class_table(), besidesp500_table(). - Rust takes plain inputs throughout:
PortfolioCsv::base_currency("USD")takes the code, and
Portfolio::valuation()andweights()value the portfolio on the last price date, with
valuation_on("2026-06-30")andweights_on(..)for another, in place ofOption<Date>. - Python's
show()returns the path of the page it opens outside a notebook, as Rust and
JavaScript do, and shows the page in a notebook as raw HTML, without IPython's warning about
frames.Holdout(start="2016-11-01")passes type checking, and holds a date. - The JavaScript types refer to TypeScript's
esnext.disposablelibrary themselves, so that
they check without it in a project's settings. JavaScriptmeanReturnslists the assets in
their order. - Rebalancing sells lots by each account's own lot method by default, as documented, rather
than first in, first out;RebalanceOptions.lot_methodis optional, and Python's
lot_methoddefaults toNone. - Optimisation options are checked before solving, with every problem reported together at the
option's name: numbers that are not finite, weights outside 0 to 1, limits no fully invested
portfolio can meet (six assets at most 10% each), the parameters a method needs, unknown
assets, and, with the settings of a backtest, its validation and rebalancing. When one method
is asked for (optimise,backtest), a parameter it does not use, such asconfidencewith
maximum Sharpe, or limits with equal weight, is an error;compareapplies each to the methods
that take it, as before. Paths name the options (options.max_weight), not the optimiser's
internals (constraints.bounds). Assetssettings are checked together:periods_per_yearabove zero, a finite
risk_free_rateabove -1 (in Python, a rate of 0 with a risk-free asset is now an error too),
and an exponentially weighted decay between 0 and 1. The covariance and mean estimators chosen
are tried on the risky assets' returns when the assets are built, so that a choice the returns
cannot support is reported atcovarianceormean_returnsthen.- The optimisation report's context names the estimator of the expected returns,
mean_returns, in place ofhistorical_means; it is absent when expected returns were given. - An interior-point solution that stops short of the tolerance of 1e-10 is
optimalwhen
its duality gap is within the solver's default tolerance of 1e-8 and its weights meet
every constraint to 1e-9; it wasnearly_optimal. Constraints that bind on the boundary of
a second-order cone often end so. - Limits in a sentence start in lower case after the first ("at most 40% in any asset; at least 4
effective assets"). - Report pages are easier to read: muted text has a contrast of at least 4.5:1 in light mode, and
labels on coloured bars are black or white, whichever reads better on that colour; charts keep
a legible width on narrow screens and scroll, and wide tables and charts show a shadow at an
edge with more to see; long tile values keep to one line; growth charts and the portfolio's
efficient frontier have axis titles. On risk-and-return charts, labels avoid points and each
other and stay inside the chart, the optimised weights are drawn in the ink rather than an
asset's colour, and the legend shows the colours of the assets held. - Text reports wrap long headings rather than cutting them short, number the columns of
correlation matrices as the rows are, name accounts in the lots table as the accounts table
does, and say what the HTML says about the in-sample history (rebalanced quarterly, without
trading costs) and what in sample covers in a comparison. Resamplingno longer implementsEq, as it holds a number of periods a year.- The migration guide describes 1.0 as it is: reports print and show as pages, files are read and
written where asked, and backtests simulate schedules and holdouts. CONTRIBUTING lists every
check CI runs and the Python test dependencies, and the Python package is classified as beta. - Portfolio documents reject unknown fields, such as a misspelt
quantty, at their path. - A report grouped by a scheme no instrument is classified by is an error at
options.group_by[i], naming the schemes there are, rather than a single "unclassified" group. - Errors raised in Python before the engine is called are
ValidationErrors with paths (still
ValueErrors), and messages are clearer: a backtest without a method or weights,methods
given as one name, an account the portfolio does not have, a walk-forward window too long for
the data, and an optimisation that found no weights now say what is wrong.
Fixed
- The Sharpe ratio over three years in the comparison and backtest reports measures each window
against the risk-free return over that window, not over the whole test. - The rebalance report's value after each trade, and the combined weights after a rebalance of
several accounts, allow for the fees paid. - Rebalancing several accounts checks the target weights as given, at
targets.<holding>; it
checked them only after spreading them across the accounts, which hid weights above one or
below zero. - JavaScript reports NaN and infinite numbers in options at their paths, where JSON had turned
them into absent options (amax_weightofNaNmeant no limit); Python reports them at their
paths rather than as a JSON error.frontierchecks its option names, asoptimisedoes. - Differences shown beside rounded figures (excess returns, changes in the Sharpe ratio, the total
of fees and tax) are the differences of the figures as shown, so that they add up. - The portfolio report's correlation columns are headed with the holdings' full names, as the
rows are ("EUR cash", not "EUR"). - A method that never found weights is marked as holding cash in the comparison tables, is left
out of the summary's best figures, and its note says that it held only cash, rather than that
it kept the weights it held. Failures of the fit to the whole history, for the run in sample,
are reported apart from the refits. - Concentration in the holdings report is measured on one basis: every share, like the
Herfindahl index, is of the value invested in instruments, cash aside. - A held weight too small to show is shown as "<0.1%" (or "<1%"), not as "–" or "not held".
The text optimisation report lists every held asset, the smaller ones together when there are
many, and no longer pads its table with assets not held. - The holdout year that runs across the split is marked in the backtest report's calendar
years; a portfolio bought and held is described without rebalances; the minimum-variance risk
note no longer contrasts a weight with an equal share of risk; the covariance estimator is
named once ("the sample covariance"), and the shading of weights is described without
reference to the colour scheme.