Skip to content

Finalytics 1.0.0-rc.1

Pre-release
Pre-release

Choose a tag to compare

@Nnamdi-sys Nnamdi-sys released this 03 Nov 10:01
· 129 commits to main since this release

Added

  • Backtests: assets.compare(methods) tests several optimisation methods side by side under the
    same limits and settings, and assets.backtest(method) or assets.backtest(weights) tests one
    allocation, optionally against a benchmark (finalytics::backtest). Each returns its report and
    every return and trade behind it (BacktestResults); Assets::compare_with and
    Assets::backtest_with run the same backtests from BacktestOptions, as JSON gives them.
    Optimisation methods are refitted through time, or fixed weights held, rebalanced monthly,
    quarterly, yearly, when a weight drifts beyond a band, or never, net of trading costs in basis
    points of the value traded. Strategies are validated in sample, on a holdout from a date, or
    walk-forward, refitting at each calendar rebalance on a rolling or expanding window of years or
    periods; for walk-forward validation the in-sample results use the same periods, so the two
    compare directly. A refit that finds no weights keeps the weights held and is recorded, and cash,
    held before a first fit, earns the risk-free return. A benchmark is fixed weights held alike or an
    index's prices. The limits on weights apply to the methods that take them, and the results note
    where they did not. Every return, trade, turnover and cost is checked against an independent
    simulation (scripts/reference/backtest.py). A walk-forward comparison of seven methods on the
    S&P 500 dataset is a new performance budget: under 5 seconds natively.
  • Three reports on assets: the optimisation report of optimise, the comparison report of compare
    and the backtest report of backtest. The optimisation report explains the weights: what they are
    expected to deliver, each asset's weight against its share of the risk, the diversification ratio
    and the number of assets in effect, the correlations, where the weights sit against each asset and
    equal weight, how they and equal weight would have done on the returns they were fitted to, and
    how they were found. It draws the efficient frontier under the same limits when asked
    (.with_frontier() in Rust, frontier=True in Python, frontier: true in JavaScript); this is
    off by default, since the frontier takes 30 more optimisations, and the page says how to turn it
    on. The comparison report scores each method on the periods it was tested on: return, volatility,
    Sharpe and Sortino ratios, drawdown, CVaR and turnover side by side; growth, calendar-year
    returns, drawdowns and the Sharpe ratio over three years; in sample against out of sample; the
    weights at the last refit and at each refit; and how the methods were tested, including refits
    that found no weights. The backtest report shows the allocation, its statistics in and out of
    sample against the benchmark (with tracking error, information ratio and beta), growth and
    drawdown over the whole history with a holdout shaded apart, the weights held as they drift
    between rebalances, turnover and trading costs, and returns by year and month. All three are data
    (OptimisationReport, ComparisonReport, BacktestReport), print as text 80 columns wide, lay
    out as one HTML page with show(), and export as tables. Daily returns are charted month by
    month, and the S&P 500's 55 stocks are summarised as the largest holdings and the rest.
  • One shape for every result: optimise, compare and backtest on assets, and rebalance
    on a portfolio, each return the report and the raw results (Optimisation, Comparison,
    Backtest and Rebalancing), as result.report and result.results. Printing a result
    prints its report as text, and result.show() shows it as a page; the raw results print as a
    table too (OptimisationResult, BacktestResults, RebalanceResults). An optimisation's
    weights are result.results.weights, and portfolio.rebalance takes the whole result in
    Rust, Python and JavaScript; an optimisation that found no weights is a validation error at
    targets rather than a target of all cash. portfolio.with_rebalance takes the rebalancing
    or its raw results. Assets::optimise_with runs an optimisation from OptimiseOptions, as
    JSON gives them.
  • The rebalance report, built by portfolio.rebalance: each holding's weight before, at the
    target and after; the volatility and expected return before and after, with the estimates the
    optimisation of the portfolio's assets uses; each account's trades and currency conversions;
    the fees, the realised gains split into long-term and short-term, and the estimated tax by
    account; and what to check before trading. It is data (RebalanceReport), prints 80 columns
    wide, shows as a page and exports as tables, and names the method and limits of the
    optimisation the targets came from. Fees and tax rates are plain numbers in every language:
    fee_bps, fee_per_trade and minimum_fee, the last two in the instrument's currency, and
    tax as the rates on short-term and long-term gains, with long_term_after_days (365 unless
    given); each is checked when the rebalancing is built, with the other inputs. The Rust builder
    is RebalanceBuilder, with as_of, minimum_trade and name too; Python and JavaScript take
    name.
  • Accounts that are not taxable: taxable: false in an account's record (a taxable column in
    an accounts file), for a retirement or other tax-deferred or tax-exempt account. Tax-aware
    rebalancing estimates no tax on its sales, which close lots by the lot method. The portfolio
    dataset's retirement account is not taxable. With tax rates, each proposed sale also reports
    the part of its gain from lots held long-term (long_term_gain_base).
  • Baseline methods: equal weight and inverse volatility (Objective::EqualWeight,
    Objective::InverseVolatility, method="equal_weight" and "inverse_volatility"), solved
    by formula, and risk parity by name (Method::RiskParity, method="risk_parity"), risk
    budgeting with equal budgets. Method::label names each method in words, and SolveStatus
    displays as it is written in JSON.
  • The READMEs show each front door in each language as a program that builds its result and
    shows it: a comparison, a backtest and an optimisation of the asset-class dataset, then the
    portfolio dataset's report and its rebalancing with fees and tax rates. Each program is followed
    by a screenshot of its page, in light and dark, which links to the full sample report. The Rust
    programs are the crate's examples (cargo run --example compare, and likewise backtest,
    optimise, report and rebalance), and the tests run every README program in each language.
  • Sample reports: scripts/sample-reports.py builds the five reports the READMEs show from the
    bundled datasets, with an index page and the screenshots, and the "Sample reports" workflow
    publishes them to GitHub Pages on each version tag.
  • Builders for every front door in Rust, each ending in build(): Assets::builder(),
    assets.optimise(Method::MaximumSharpe).max_weight(0.4), assets.compare([...]),
    assets.backtest(...), Portfolio::builder(), portfolio.report().benchmark("BENCH") and
    portfolio.rebalance(&result).whole_units(). They take plain text and numbers, with units in
    their names (max_weight, trading_cost_bps, Years(5)), and check everything once, at
    build(), reporting every problem together. The option types stay for JSON and for
    optimise_with, report_with and rebalance_with, and finalytics::prelude imports what
    the builders need. Identifiers implement FromStr, OptimisationResult::holdings gives an
    optimisation's weights by holding, and a trade's Side displays as buy or sell.
  • Reports show themselves: report.show() opens the report's HTML page in the default browser, or
    with the command in the BROWSER environment variable; in Python it shows inline in a Jupyter
    notebook, and in JavaScript in a frame inside a page's element (report.show(element)), with
    report.toHtml() and report.toText(). This holds for the portfolio report and for the results
    of optimise, compare and backtest. A report carries a name (.name(...) in Rust, name= in
    Python, name in JavaScript), shown as or under its title. In Rust, show, save_html and
    reading files by path (Portfolio::builder(), AssetsBuilder::prices_file) are behind the
    default io feature, which the WebAssembly build leaves out, and report Error::Io when they
    fail.
  • A data guide (docs/data.md): every input, column by column, with the dataset files as
    examples and advice on bringing data from brokers and data providers; its examples run as
    tests.
  • A guide to migrating from 0.9 (docs/migrating-from-0.9.md): what changed, what replaces
    each part of 0.9, and a 0.9 optimisation worked through in 1.0, run as a test.
  • Reporting periods are read from their labels by the engine (Period implements FromStr and
    Display in Rust), so Python and JavaScript accept the same labels, now including
    since 2026-01-31.
  • Two front doors to the library. Assets takes the prices or returns of things one might hold
    (a pandas DataFrame, CSV or a PriceTable), detects their frequency, annualises them, and
    gives each asset's statistics, the covariance and correlation, and optimisation by method
    name with a largest weight, bounds, per-asset bounds and group limits given by name, such as
    assets.optimise(method="maximum_sharpe", max_weight=0.4); one asset, such as T-bills,
    may serve as the risk-free asset. Portfolio holds a portfolio's records, its market data and
    the books kept from them, and gives its valuation, weights, performance, rebalancing (with
    with_rebalance to make the trades), all six reports in one call (report) and the
    instruments it holds as Assets. Rust has builders, Python keyword arguments, and JavaScript
    options objects, in which an unknown option is an error.
  • Datasets (finalytics::datasets, fl.datasets, datasets in JavaScript): daily prices
    from 2005 to October 2026 of 55 S&P 500 companies (the five largest in each sector), with
    3-month T-bills, the S&P 500 total return index and each company's sector (sp500,
    sp500_index, sp500_companies); a three-year, two-account household holding five real funds
    at their real prices, in US dollars and euros, with illustrative transactions and the options
    of its full report; and 30 years of synthetic month-end levels of six asset-class indices.
    The market data comes from Yahoo Finance (scripts/fetch-market-data.py). Each file is also
    available as text, as an example of the layout Finalytics reads. The S&P 500 prices are behind
    the default sp500 feature in Rust and are read on first use in JavaScript, outside the
    WebAssembly module.
  • A portfolio can be read from its transactions alone: date may stand for trade_date, id
    and account may be left out (t1, t2 and so on, and main), the instruments file may be
    left out (each instrument takes the currency given with it in the transactions, or the base
    currency), and the base currency may be left out (that of the first deposit).
  • formats::market_from_csv builds market data from price and FX files, and
    formats::price_columns_from_csv reads prices in the order of the file.
  • The reports print: every report implements Display in Rust as text 80 columns wide, with
    tables, bars and sparklines (print(report) in Python, reportText(report) in JavaScript), and
    the full report lays out as one self-contained HTML page with the Finalytics logo and an
    optional portfolio name: inline SVG charts with hover details, no scripts or external
    resources, light and dark themes, and print layout (PortfolioReport::to_html, Python
    to_html and save_html, JavaScript reportHtml). Portfolio::report returns a
    PortfolioReport, now in the reports module with portfolio_report.
  • In Node.js the npm package is ready on import: its node entry point loads the WebAssembly
    file, so init is needed only in browsers.
  • Rust constructors for inputs that gained #[non_exhaustive]: TaxRates::new,
    BlackLitterman::new, Resampling::new, Turnover::new, HistoricalWindow::new,
    FactorShocks::new, ScenarioRiskModel::from_covariance and from_factor_model;
    TradeLimits implements Default.

Changed

  • The optimiser solves to a tolerance of 1e-10 rather than the solver's default of 1e-8, so that
    a weight that belongs at a bound ends within a few millionths of it rather than up to 1e-4
    away; this matters when weights are refitted and traded repeatedly. Optimised weights change
    by less than 1e-7 in the shared test scenario.
  • JavaScript: Assets.optimise gives the weights in the order of the assets, as Python does,
    rather than in the order of their names.
  • Rust: the result types, the option types and the enumerations that may grow are
    #[non_exhaustive], so that 1.x releases can add fields and variants without breaking code.
    Options start from Default::default() and have their fields set; match on an enumeration
    needs a wildcard arm. Transaction::new builds a transaction as Instrument::new,
    Account::new and PortfolioData::new already do for theirs; SchemeRisk::new builds a
    scheme's risk. Python and JavaScript are unchanged.
  • The descriptions of the shared data types no longer name Rust methods or None; they read the
    same in the JSON Schema, the Python types and the TypeScript declarations.
  • The holdings report counts a lot or a gain as long-term when it has been held for more than
    long_term_after_days days, as tax-aware rebalancing does. A lot held for exactly that many
    days was long-term in the report and short-term for rebalancing.
  • Rust documentation examples use the paths of the finalytics crate.
  • A holding is written as text in data: an instrument's identifier, such as "SPY", or a
    currency followed by cash, such as "USD cash". It was an object such as
    {"holding": "instrument", "id": "SPY"}. In Python a holding is a str (fl.cash("USD") gives
    "USD cash"; fl.holding and finalytics.pandas.label are gone); in TypeScript a string.
    An instrument's identifier may not take the cash form.
  • Values keyed by an instrument, a currency, a factor, a year or a holding are maps, such as
    {"SPY": 0.6, "USD cash": 0.4}, rather than lists of pairs: weights before and after a
    rebalance, shocks, proxies, factor returns, currency exposures, expected returns and benchmark
    weights for reports, and realised gains and income by year, instrument or holding. Rebalancing
    targets are maps in JavaScript too, and holding_weights returns a map in Rust. Validation
    paths into these maps end in the key, such as shocks.instruments.SPY.
  • Every tagged union is tagged by type, such as {"type": "maximum_sharpe"}, in place of
    tags named after each union (objective, method, prior and others). Transactions already
    used type, so portfolio documents keep their shape.
  • Renamed for consistency: in scenario results, local_return and total_return of a holding
    are return_local and return_base, and the money values at risk are value_at_risk_base
    and value_at_risk_after_base; a proposed trade's fees are fees_local; Rust
    opt::Method is SolveMethod, and Problem::new is Problem::from_covariance.
  • Rust: Problem, TaxRates, BlackLitterman, Resampling, Turnover, TradeLimits,
    ScenarioRiskModel, HistoricalWindow and FactorShocks are #[non_exhaustive]. A new
    parameter of an enumeration's variant will arrive as a new variant.
  • The input records of a portfolio (base currency, accounts, instruments and transactions) are
    named PortfolioData, in Rust, Python, TypeScript and the JSON Schema, so that Portfolio can
    name the portfolio itself. The portfolio document's portfolio member is unchanged.
  • Python: Portfolio replaces Books (fl.Portfolio(data, market) or
    fl.Portfolio.from_csv(transactions=..., prices=...)), and the reports are its methods
    (portfolio.performance_report(...)) rather than functions of fl.reports; rebalance takes
    the targets and, optionally, the accounts (every account by default), and returns one
    proposal for all of them. valuation and weights default to the last price date.
  • JavaScript: the Portfolio class replaces Books, with Portfolio.fromCsv(files) in place of
    portfolioFromCsv; rebalance(targets, { accounts }) replaces rebalance and
    rebalanceAccounts, and dates() replaces defaultDates(). The worker client's books is
    portfolio.
  • Cash in the base currency is riskless in the reports: it is left out of the holdings'
    covariance estimate, so that Ledoit–Wolf shrinkage no longer lends it part of the average
    variance, and its variance and covariances are zero. The overview's efficient frontier is that
    of the invested holdings, so its least risky point is no longer nearly all cash; each point's
    weights still follow the holdings, with none in base-currency cash.
  • Fees and taxes charged to an account rather than to a holding are expenses: a new allocation,
    expense, records them, holding lines carry expenses_local and expenses_base, and they are
    no longer a loss on the cash that paid them. Their share of the return is their own line:
    Performance::expenses (performance.expenses() in Python and JavaScript), the performance
    report's expenses, and a "Fees and taxes" row in its contribution table. With the holdings'
    contributions they add up to the time-weighted return. Attribution segments' returns are
    before them.
  • formats::portfolio_from_csv takes the base currency and the instruments file as options.
  • Rebalancing one account through rebalance_accounts gives exactly rebalance's proposal.
  • Rebalancing leaves room for fees. When the trades and their fees would need more
    base-currency cash than an account has, as when the targets leave no cash, the purchases are
    sized again so that they fit, and a shortfall that rounding leaves comes from the largest
    purchase; before, the proposal took the cash below zero with a warning. Rebalancing the
    portfolio dataset to its least risky mix, 5% to 40% each, in whole units and without fees, now
    buys one unit fewer of EXSA in the brokerage account and of BND and EXSA in the retirement
    account, where whole units had overspent.
  • CombinedRebalance is RebalanceResults, and records the base currency;
    Portfolio::rebalance_with and rebalance_accounts_with return the rebalancing with its
    report. In Python and JavaScript, portfolio.rebalance returns the rebalancing, with each
    account's proposal in result.results.accounts.
  • Rust: the performance types and functions are in finalytics::performance rather than at the
    crate's root, and finalytics::numeric is no longer public. Semantic versioning covers the
    finalytics crate; the crates it is built from say that their own API may change in any
    release.
  • JavaScript: writeDocument accepts the MarketData that readDocument returns, and
    impliedRiskAversion takes its options as an object, as statistics does.
  • A solution, and a resampled one, compare equal to another when everything but the time taken
    is equal.

Fixed

  • JavaScript: the valuation dates of a Performance are its dates property; they were
    published as parse_dates.
  • Python: finalytics.performance is listed in the package's __all__, and lists its own
    public names.