Repository navigation
Finalytics 1.0.0-rc.1
Pre-release
Pre-release
Added
- Backtests:
assets.compare(methods)tests several optimisation methods side by side under the
same limits and settings, andassets.backtest(method)orassets.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_withand
Assets::backtest_withrun the same backtests fromBacktestOptions, 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 ofcompare
and the backtest report ofbacktest. 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=Truein Python,frontier: truein 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 withshow(), 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,compareandbackteston assets, andrebalance
on a portfolio, each return the report and the raw results (Optimisation,Comparison,
BacktestandRebalancing), asresult.reportandresult.results. Printing a result
prints its report as text, andresult.show()shows it as a page; the raw results print as a
table too (OptimisationResult,BacktestResults,RebalanceResults). An optimisation's
weights areresult.results.weights, andportfolio.rebalancetakes the whole result in
Rust, Python and JavaScript; an optimisation that found no weights is a validation error at
targetsrather than a target of all cash.portfolio.with_rebalancetakes the rebalancing
or its raw results.Assets::optimise_withruns an optimisation fromOptimiseOptions, 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_tradeandminimum_fee, the last two in the instrument's currency, and
taxas the rates on short-term and long-term gains, withlong_term_after_days(365 unless
given); each is checked when the rebalancing is built, with the other inputs. The Rust builder
isRebalanceBuilder, withas_of,minimum_tradeandnametoo; Python and JavaScript take
name. - Accounts that are not taxable:
taxable: falsein an account's record (ataxablecolumn 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::labelnames each method in words, andSolveStatus
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 likewisebacktest,
optimise,reportandrebalance), and the tests run every README program in each language. - Sample reports:
scripts/sample-reports.pybuilds 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_withandrebalance_with, andfinalytics::preludeimports what
the builders need. Identifiers implementFromStr,OptimisationResult::holdingsgives an
optimisation's weights by holding, and a trade'sSidedisplays asbuyorsell. - Reports show themselves:
report.show()opens the report's HTML page in the default browser, or
with the command in theBROWSERenvironment 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()andreport.toText(). This holds for the portfolio report and for the results
ofoptimise,compareandbacktest. A report carries a name (.name(...)in Rust,name=in
Python,namein JavaScript), shown as or under its title. In Rust,show,save_htmland
reading files by path (Portfolio::builder(),AssetsBuilder::prices_file) are behind the
defaultiofeature, which the WebAssembly build leaves out, and reportError::Iowhen 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 (
PeriodimplementsFromStrand
Displayin Rust), so Python and JavaScript accept the same labels, now including
since 2026-01-31. - Two front doors to the library.
Assetstakes the prices or returns of things one might hold
(a pandas DataFrame, CSV or aPriceTable), 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.Portfolioholds a portfolio's records, its market data and
the books kept from them, and gives its valuation, weights, performance, rebalancing (with
with_rebalanceto make the trades), all six reports in one call (report) and the
instruments it holds asAssets. Rust has builders, Python keyword arguments, and JavaScript
options objects, in which an unknown option is an error. - Datasets (
finalytics::datasets,fl.datasets,datasetsin 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 defaultsp500feature in Rust and are read on first use in JavaScript, outside the
WebAssembly module. - A portfolio can be read from its transactions alone:
datemay stand fortrade_date,id
andaccountmay be left out (t1,t2and so on, andmain), 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_csvbuilds market data from price and FX files, and
formats::price_columns_from_csvreads prices in the order of the file.- The reports print: every report implements
Displayin 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_htmlandsave_html, JavaScriptreportHtml).Portfolio::reportreturns a
PortfolioReport, now in the reports module withportfolio_report. - In Node.js the npm package is ready on import: its
nodeentry point loads the WebAssembly
file, soinitis 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_covarianceandfrom_factor_model;
TradeLimitsimplementsDefault.
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.optimisegives 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 fromDefault::default()and have their fields set;matchon an enumeration
needs a wildcard arm.Transaction::newbuilds a transaction asInstrument::new,
Account::newandPortfolioData::newalready do for theirs;SchemeRisk::newbuilds 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_daysdays, 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
finalyticscrate. - A holding is written as text in data: an instrument's identifier, such as
"SPY", or a
currency followed bycash, such as"USD cash". It was an object such as
{"holding": "instrument", "id": "SPY"}. In Python a holding is astr(fl.cash("USD")gives
"USD cash";fl.holdingandfinalytics.pandas.labelare gone); in TypeScript astring.
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, andholding_weightsreturns a map in Rust. Validation
paths into these maps end in the key, such asshocks.instruments.SPY. - Every tagged union is tagged by
type, such as{"type": "maximum_sharpe"}, in place of
tags named after each union (objective,method,priorand others). Transactions already
usedtype, so portfolio documents keep their shape. - Renamed for consistency: in scenario results,
local_returnandtotal_returnof a holding
arereturn_localandreturn_base, and the money values at risk arevalue_at_risk_base
andvalue_at_risk_after_base; a proposed trade'sfeesarefees_local; Rust
opt::MethodisSolveMethod, andProblem::newisProblem::from_covariance. - Rust:
Problem,TaxRates,BlackLitterman,Resampling,Turnover,TradeLimits,
ScenarioRiskModel,HistoricalWindowandFactorShocksare#[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
namedPortfolioData, in Rust, Python, TypeScript and the JSON Schema, so thatPortfoliocan
name the portfolio itself. The portfolio document'sportfoliomember is unchanged. - Python:
PortfolioreplacesBooks(fl.Portfolio(data, market)or
fl.Portfolio.from_csv(transactions=..., prices=...)), and the reports are its methods
(portfolio.performance_report(...)) rather than functions offl.reports;rebalancetakes
the targets and, optionally, theaccounts(every account by default), and returns one
proposal for all of them.valuationandweightsdefault to the last price date. - JavaScript: the
Portfolioclass replacesBooks, withPortfolio.fromCsv(files)in place of
portfolioFromCsv;rebalance(targets, { accounts })replacesrebalanceand
rebalanceAccounts, anddates()replacesdefaultDates(). The worker client'sbooksis
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 carryexpenses_localandexpenses_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'sexpenses, 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_csvtakes the base currency and the instruments file as options.- Rebalancing one account through
rebalance_accountsgives exactlyrebalance'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. CombinedRebalanceisRebalanceResults, and records the base currency;
Portfolio::rebalance_withandrebalance_accounts_withreturn the rebalancing with its
report. In Python and JavaScript,portfolio.rebalancereturns the rebalancing, with each
account's proposal inresult.results.accounts.- Rust: the performance types and functions are in
finalytics::performancerather than at the
crate's root, andfinalytics::numericis no longer public. Semantic versioning covers the
finalyticscrate; the crates it is built from say that their own API may change in any
release. - JavaScript:
writeDocumentaccepts theMarketDatathatreadDocumentreturns, and
impliedRiskAversiontakes its options as an object, asstatisticsdoes. - 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
Performanceare itsdatesproperty; they were
published asparse_dates. - Python:
finalytics.performanceis listed in the package's__all__, and lists its own
public names.