Skip to content

Finalytics 1.0.0-rc.2

Pre-release
Pre-release

Choose a tag to compare

@Nnamdi-sys Nnamdi-sys released this 04 Nov 07:38
· 117 commits to main since this release

Added

  • Statistics adds 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). RelativeStatistics adds downside and upside betas and capture
    ratios. The reports show them, and scripts/reference/downside.py checks 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, with group_contributions for 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.fitted and StrategyReport.fitted say 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_var flags 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.
  • CovarianceMethod reads 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 optimise takes:
    uncertainty, budget, linkage, expected_return and risk_free_rate; Python's
    compare and backtest take risk_free_rate.
  • name on optimise in Rust (.name(..)) and JavaScript ({ name }), as in Python.
  • saveHtml(path, name?) on reports and results in Node.js, as save_html in Python;
    JavaScript results' toText and toHtml take 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_points and benchmark_weight.
  • compare takes 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; methods may be left out when weights are given.
  • benchmark_name names the benchmark of a comparison or backtest in every language:
    Benchmark by default, or the column's name for an index's prices.
  • Assets::frontier returns FrontierPortfolios, 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=...) and fl.risk.covariance. scripts/reference/estimators.py checks
    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 and mean_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_semivariance and minimum_cdar optimise 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). With target, they and minimum_cvar keep
    an annual expected return of at least target. In the optimiser they are
    Objective::MinimumSemivariance and Objective::MinimumCdar, with
    Constraints.min_return for the floor.
  • min_effective_assets holds 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_assets in the optimiser). Bounds that leave room for fewer are
    reported before solving. scripts/reference/downside_objectives.py checks the new objectives
    and limits against CVXPY.
  • optimise(resample=200) averages the optimal weights for 200 histories simulated from the
    assets' estimates (Michaud, 1998), in optimise, compare and backtest; the result's
    resampled holds each weight's standard deviation across them, and the report says how many
    were solved. Resampling.periods_per_year simulates 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" on to_html, save_html and show in
    Python, the last argument of toHtml, saveHtml and show in 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 than r / 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_of in Python and JavaScript, as in Rust and every report
    (portfolio.rebalance(targets, as_of="2026-06-30")); it was date.
  • Python's datasets.price_table() is datasets.asset_class_table(), beside sp500_table().
  • Rust takes plain inputs throughout: PortfolioCsv::base_currency("USD") takes the code, and
    Portfolio::valuation() and weights() value the portfolio on the last price date, with
    valuation_on("2026-06-30") and weights_on(..) for another, in place of Option<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.disposable library themselves, so that
    they check without it in a project's settings. JavaScript meanReturns lists 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_method is optional, and Python's
    lot_method defaults to None.
  • 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 as confidence with
    maximum Sharpe, or limits with equal weight, is an error; compare applies each to the methods
    that take it, as before. Paths name the options (options.max_weight), not the optimiser's
    internals (constraints.bounds).
  • Assets settings are checked together: periods_per_year above zero, a finite
    risk_free_rate above -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 at covariance or mean_returns then.
  • The optimisation report's context names the estimator of the expected returns,
    mean_returns, in place of historical_means; it is absent when expected returns were given.
  • An interior-point solution that stops short of the tolerance of 1e-10 is optimal when
    its duality gap is within the solver's default tolerance of 1e-8 and its weights meet
    every constraint to 1e-9; it was nearly_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.
  • Resampling no longer implements Eq, 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 (a max_weight of NaN meant no limit); Python reports them at their
    paths rather than as a JSON error. frontier checks its option names, as optimise does.
  • 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.