Skip to content

Finalytics 1.0.0-rc.5

Pre-release
Pre-release

Choose a tag to compare

@Nnamdi-sys Nnamdi-sys released this 09 Nov 05:35
· 52 commits to main since this release

Added

  • Formula fields in screening: formulas={"risk_adjusted": "return_1y / volatility"} (Python
    and JavaScript, .formula(name, formula) in Rust) adds numeric fields computed for each
    security from its measures, numeric fields and earlier formulas, which the rules, the sort,
    the results, the tables and both forms of the report take by name. The formulas are a small
    language that is evaluated, never run: numbers, names, + - * /, parentheses, and abs,
    sqrt, log, min and max. A missing input or a result that is not finite gives no value,
    counted in the report's data. Problems name the token and its place.

  • Goals kept with a portfolio: portfolio.goals and with_goals(goals), each goal a plan with
    its name, saved in the portfolio's document (goals, absent when there are none, so existing
    documents and their digests are unchanged) and read from a goals file in the style of the
    transactions file (goals= in Python and JavaScript, PortfolioCsv::goals in Rust).
    assets.plan(goal) plans a stored goal as it is (assets.plan_with(goal) in Rust), so a
    saved portfolio and the same history reproduce the plan.

  • Reports on some accounts: accounts=["brokerage"] (.accounts(["brokerage"]) in Rust)
    reports on those accounts alone, from the books kept from their transactions. Transfers with
    the accounts left out count as money in and out, and every report says which accounts it
    covers and how many such transfers there are. Books::for_accounts keeps such books in Rust.

  • The holdings report counts realised gains and income within its period as well as to date
    (period, from the report's start to its date, as the performance report's flows count
    them), so that a report starting this year, such as start="2026-01-01", gives this year's
    realised gains and income for tax. The text and page show the period beside the totals when
    they differ, and the tables of realised gains and income by year gain a column for the
    period.

  • Assets.evaluate(weights) values given weights on the estimates optimisation uses: the
    expected return, volatility, Sharpe ratio and shares of risk in results, and the optimisation
    report's page and text for them, titled "Given weights", in report, with the efficient
    frontier under limits when asked (frontier=True). The weights may hold cash, so a portfolio's
    own weights on Portfolio.assets() give the overview report's current point. Python
    assets.evaluate(weights, ...), JavaScript assets.evaluate({ weights, ... }), Rust
    assets.evaluate(weights).build().

  • Cash in optimisation: cash limits (.cash(0.0, 0.2) in Rust, cash=(0, 0.2) in Python,
    cash: { min: 0, max: 0.2 } in JavaScript) let optimise, compare and backtest hold cash
    beside the risky assets, riskless, in the risk-free asset or, for assets without one, in Cash
    at the risk-free rate; the frontier then includes it. Without them, the weights are fully
    invested in the risky assets, as before. risky_assets and cash_assets list which assets
    optimisation chooses among and which are cash. The overview report adds
    current_without_base_cash, the current mix with base-currency cash set aside, on the axes of
    its frontier; cash in other currencies counts as a holding there, as its value moves with the
    exchange rate.

  • Group limits by classification: a group may name a classification rather than list its assets,
    such as at most 60% in the assets classed Equity under asset_class (Rust
    .class_limit("asset_class", "Equity", 0.0, 0.6), Python groups={"Equity": ("asset_class", 0, 0.6)}, JavaScript groups: { Equity: { classification: "asset_class", max: 0.6 } }). Assets
    carry classes: a portfolio's assets take its instruments', and others take classes.

  • Rebalancing can keep cash as it is, for every currency or those named (keep_cash=True or
    keep_cash=["USD"] in Python and JavaScript, .keep_all_cash() or .keep_cash(["USD"]) in
    Rust): the targets are then shares of the rest of the value, so the trades neither invest that
    cash nor add to it. The results and the report say what was kept. By default the targets are
    still shares of the whole value, cash included.

  • Blended benchmarks: the reports' benchmark may be weights by holding, such as
    {"VTI": 0.55, "BND": 0.35, "GLD": 0.1} (.benchmark_blend(...) in Rust), held at those
    weights in the base currency and rebalanced monthly. From a blend, the attribution report
    derives the benchmark's segments in each month by the portfolio's classification, given only
    the scheme (attribution="asset_class", .attribution_by("asset_class")), so Brinson–Fachler
    attribution works for any portfolio rather than only with segments given by hand.

  • Trade and tracking-error limits in Assets.optimise, with plain inputs in every language:
    current_weights (the weights held now, with any cash on the risk-free asset),
    max_turnover, min_trade, max_trades, benchmark_weights and max_tracking_error. They
    were available only through the low-level solve(problem, objective). Every problem with them
    is reported together; the frontier is drawn under the same limits; and the optimisation report
    lists the trades from the current weights with the turnover (a trades table too) and gives the
    tracking error against the benchmark weights. In compare and backtest, the tracking-error
    limit applies at every fit and the turnover and trade limits at each walk-forward refit, from
    the weights held then.

  • methods() (finalytics::methods() in Rust, fl.methods() in Python, methods() in
    JavaScript) and Method::info() describe every optimisation method: its parameters, with
    whether it needs each, its default and the values allowed, the limits on weights it takes, and
    whether it resamples or is measured on the periods' returns. The checks on the options follow
    the same descriptions, so that a form built from them offers only what the method uses.

  • PortfolioReport::tables() in Rust, and reportTables of the six reports of
    Portfolio.report in JavaScript, give the tables of each report in turn, as tables() does in
    Python.

Changed

  • Portfolio.assets() includes the portfolio's cash: base-currency cash, such as USD cash, as
    the risk-free asset, riskless and earning nothing, and cash in other currencies, such as
    EUR cash, estimated with the instruments as it moves with its exchange rate. The estimates are
    the overview report's, so the portfolio's own weights valued on them give the overview's
    current point, and the rebalance report's figures for an optimisation's target are the
    optimisation's. Optimisation still chooses among the instruments alone, but its estimates now
    include the foreign cash, so its weights can differ slightly from rc.4's; labels lists the
    cash after the instruments. Assets.covariance() gives a risk-free asset whose return is the
    same in every period, such as idle cash, no variance, rather than the share a shrinkage
    estimator lent it.

  • Rust: AssetGroup has a classification field, and its min and max default to 0 and 1
    in JSON.

  • Rust: ReportOptions::benchmark is a ReportBenchmark, an instrument or a blend; an
    instrument converts with .into(), as in options.benchmark = Some(id.into()). The JSON form
    of an instrument, its identifier, is unchanged.

  • The sample portfolio's instruments list BENCH, its benchmark, in USD.

  • The npm package's WebAssembly engine is smaller, about 1.7 MB gzipped with this release's
    additions rather than 2.0 MB, and no slower: the build leaves out the functions' names, which
    only debugging uses, and optimises the module with Binaryen's wasm-opt. Errors are
    unchanged; only the stack trace of an internal failure shows function numbers rather than
    names. Building the package from source needs wasm-opt from Binaryen version 123, which
    scripts/install-binaryen.sh installs and checks against its pinned checksum.

  • One rule for an option a method does not use, in every verb. optimise and a single
    backtest refuse it, as before. compare applies each option to the methods that take it and
    notes in the report each method it does not apply to (such as "Maximum Sharpe: the confidence
    does not apply"). Two cases that used to pass now raise a validation error, so code that relied
    on them needs the option removed:

    • compare given an option that none of its methods takes, such as a target for minimum
      variance and maximum Sharpe, which it used to ignore, now refuses it, naming them all
      ("minimum variance and maximum Sharpe do not use target");
    • limits or parameters given to compare with fixed weights alone, or to a Rust backtest of
      fixed weights, which were dropped, are now refused ("fixed weights take no limits or
      parameters"), as Python and JavaScript already refused them for backtest.
  • A risk aversion must be above zero, as the solver requires: zero was let through the checks
    and refused by the solver.

Fixed

  • A benchmark is converted to the base currency: its levels are in its own currency, as the
    instruments list it, converted at the market data's rates, so a report in EUR no longer
    compares with a dollar benchmark's levels. When the data has no rate for it, or the
    instruments do not list it, each report's header says so, as it says how the benchmark is
    measured in every case.

  • compare keeps the strategies in the order they are given, in the results, the tables, the
    legends and both forms of the report: it listed the methods first and, in JavaScript, the fixed
    weights by name. Fixed weights may now come among the methods: in Rust compare takes
    strategies, such as [Strategy::weights("60/40", [...]), Method::MinimumVariance.into()], and
    .method() adds one in turn; in Python methods takes ("60/40", {...}) pairs, and in
    JavaScript { name, weights } objects.

  • JavaScript: typed arrays, such as Float64Array, are read wherever an input holds arrays of
    numbers: Assets.fromReturns took them by its types but refused them ("invalid type: map,
    expected a sequence"), and so did returns tables, matrices and the other structured inputs. A
    number that is not finite in one is reported at its index.

  • Every report table's title is a valid Excel sheet name (at most 31 characters, none of
    [ ] : * ? / \, and unique within the report), so that the tables of a report export to one
    workbook: "Holdings: return and risk" is now "Return and risk by holding", "Value at risk and
    expected shortfall" is "VaR and expected shortfall", and the planning report's changes are
    "Changes that reach the chance" or "Changes that keep the chance". The tables' names are
    unchanged.