fincanva

Build, backtest and analyse Fincanva strategies from Python, with your own Fincanva account.

pip install "fincanva[all]"     # with pandas and matplotlib; plain `fincanva` works without them

import matplotlib.pyplot as plt
import fincanva as fc

fc.connect()            # reads FINCANVA_API_KEY; never writes the key anywhere
fc.connect("fk_...")    # or the key itself
fc.connect(key_file="~/fincanva-api-key.txt")   # or a text file that holds the key alone

sim = fc.simulate("66f1c0a2b3d4e5f60718293b", start=2008)   # a saved strategy of yours, or a public one
print(sim.headline.strategy.cagr, sim.headline.strategy.sharpe)

ax = sim.equity().plot(title=sim.strategy_name)   # growth since the start: strategy beside benchmark
sim.regimes().shade(ax)                           # the risk-off periods in grey
plt.show()

sim.monthly_returns().loc["2020"]                 # one row per month
sim.metrics().to_frame()                          # every metric, strategy beside benchmark
sim.stress(volatility_multiplier=2.0).to_frame()  # the risk under a harsher view
sim.cone(horizon_days=1260)                       # a Monte Carlo cone, five years ahead
sim.trust().intervals()                           # bootstrap intervals of return, Sharpe, drawdown
sim.positions()                                   # what it holds today

assets = ["SPY", "TLT", "GLD"]
w = fc.allocation.weights(fc.allocation.RiskParity(), assets)    # today's weights by a method of the catalogue
w.weights, w.as_of                                                # by permaTicker, and the date they are for
fc.allocation.efficient_frontier(assets, allow_short=False).plot()
fc.allocation.walk_forward(fc.allocation.InverseVolatility(), assets, start=2015, rebalance_months=3).metrics.sharpe
fc.estimators.estimate(assets, fc.estimators.correlation.SpearmanOnReturns).matrix
r = fc.risk.regime(fc.risk.presets.Trend200)                     # risk-on or risk-off now, and since when
r.state, r.since, r.history

fc.raw                  # every API operation as a typed function, one to one
fc.allocation           # the allocation methods, one class each
fc.risk.presets         # the risk condition presets
fc.filters              # the screening filters, grouped as in the app
fc.estimators           # the covariance and correlation estimators

try:
    fc.allocation.walk_forward("risk_parity", assets, start=1990)
except fc.LicenceRefused as refused:   # raised only when a request reaches the protected long-run history
    refused.first_allowed_dates         # by permaTicker: the first date to ask again from (None: leave it out)

fc.connect() calls Fincanva at https://app.fincanva.com. To call another address, pass it as fc.connect(base_url="https://...") or set FINCANVA_BASE_URL: the origin alone, or the origin followed by /api/v1/research. The address must use https (plain http is accepted for localhost only), so the key never travels unencrypted.

Python 3.10 or later. Without pandas, the typed results (sim.headline, sim.metrics(), sim.trust(), sim.stress(), sim.regimes()) work as they are, and a method that returns a DataFrame raises fc.MissingDependency, naming the extra to install, before it spends anything. The research results (w.weights, r.history, ...) answer a dict or a list instead of a pandas object.

The designed surface

Built on fc.raw alone: every method calls one API operation through it, never a transport of its own. Every number is the API's own; a DataFrame reshapes an answer and never computes a figure.

Every read is made on the simulation's own variant, so one object's results agree, and is kept on the object: asking again spends nothing. Positions are always the base variant's, as the API reports them.

The allocation methods and the risk-on/off rules, called from the catalogue each choice is made from:

method is an entry of fc.allocation with its settings (fc.allocation.MeanVariance(objective="minimum_volatility")), the entry alone, or its id; its settings are checked against the level the call uses (inside a strategy, or a Combined's) before anything is sent. An estimator of fc.estimators.covariance or fc.estimators.correlation carries its own settings (ExponentiallyWeighted(decay_factor=0.97)) and chooses the matrix. rule is a preset of fc.risk.presets, a preset's id, or a rule of a type as create_strategy takes a risk condition. Each result keeps the operation's typed result as .result, beside .summary and .assumed.

Your library and your real holdings (K), batches, pipelines and long runs (P), strategy discovery (S), explanations (X), your own series (U) and Fin Research (L), each its own module:

Market research, one module per family: valuation, fundamentals, the universe of instruments, screener runs and options. Each function calls one API operation, a method or a mode of it, and each result keeps the operation's typed result as .result (every field the API answered) with named views, as the research results above do; a family's result classes are named on its module (fc.valuation.ReverseDcf). An argument left out is not sent: the API applies its default.

backtest, improve and suggest are long runs, waited for like a simulation (a screener run is never cancelled); improve and suggest save what they find as a new screener and are refused to an app set to read-only (ToolsetDisabled). A figure that does not apply is None with its reason, never 0: a valuation that does not apply (.reason), reverse_dcf's peer figures while the peers are not read (peer_group_too_small), an implied volatility no price gives (no_volatility_reprices_it).

The analysis families, one module each over one API operation that takes the method as method (each function sends one method; the API operation and method are named in its documentation):

Every figure is an instrument's one-instrument backtest, a window of prices, a macro series or the numbers you give, as the engine answers it. A method that computes backtests (analyze, drawdowns, return_distribution, seasonality, event_study, factor_exposure, factor_regression, regime_behaviour, the regression form of macro.sensitivity, every scenario, every sweep) is a long run: it waits up to timeout seconds, then raises RunStillRunning, whose run_id the family's collect(run_id) or fc.Job(run_id) turns into the same typed result later. compare, performance_history, rolling and calendar_returns read backtests analyze computed, with the same instruments, start, benchmark and variant, and are refused NotFoundError before. variant is a fc.Variant. Each result keeps the method's typed result as .result; its views answer pandas objects when pandas is installed and plain Python otherwise, and to_frame() always needs pandas.

Every long run is one fc.Job. A call that may be a long run (a simulation, health_check, a search, a what-if, a batch or a pipeline the request cannot finish, a screener's backtest or search, a method computed from backtests) waits for it by default, up to timeout seconds; where it takes wait=False, it returns a fc.Job at once instead (job.wait(), job.cancel()), already done when the API answered at once. A wait that runs out raises RunStillRunning: the run goes on, and fc.Job(error.run_id).wait() picks it up and finishes as the same designed result, whichever family started it. Following and cancelling a run are free; job.cancel() stops a batch, a discovery, a walk-forward, a sweep or a method computed from backtests, and refuses the rest. A batch item that is itself a long run holds its own Job. A Fin Research session is not a run: when session.wait() runs out, the RunStillRunning it raises has no run_id, and fc.fin_research.ResearchSession(session_id) reads the session again.

The errors the API answers each have a class under fc.FincanvaError: AuthenticationError, ValidationError, PlanLimitError (the plan, an allowance or the per-minute cap), ToolsetDisabled (the user's settings for a connected app: .family, .read_only), LicenceRefused (data that may not leave Fincanva: for the protected long-run history, .first_allowed_dates by permaTicker; otherwise .dataset, .licence_class, .surface), NotFoundError, SavedStrategyChanged, RunFailed, RunStillRunning, ServiceUnavailable.

Design notes

• Install extras. fincanva[pandas] (the DataFrames), fincanva[plot] (matplotlib, for Regimes.shade() without an axes), fincanva[all]. The core needs httpx and pydantic only. import fincanva never imports pandas, matplotlib or the generated models, and neither does importing a catalogue.
• Typed results are the generated models. fincanva.results subclasses the generated result model of each simulation answer and adds views, so the fields, names and documentation are fc.raw's, and a field the API adds appears in both at once. A research result keeps that model as .result instead, because its named views (.weights, .matrix, .history) answer a pandas object or plain Python where the model has a list.
• No instrument as a benchmark yet. benchmark= takes "strategy", "none" or a strategy id, as the API does; fc.simulate(..., benchmark="ACWI") is refused before anything is sent.
• No "excluded" list. compute_weights answers no entry for an instrument with no price on the date and states no list of what it left out; Weights shows what the API answered and never infers the rest.
• Every other operation: through fc.raw. The designed surface above covers every family of the API but three groups, which are in fc.raw only, one typed function each, with the operation's own arguments and typed result: building and saving strategies (create_strategy, edit_strategy, replace_strategy, validate_strategy, explain_strategy, describe_strategy_model; a designed fc.Strategy is not in this version), building and saving screeners (create_screener, edit_screener, replace_screener, validate_screener, explain_screener, describe_screen_filter), and more reads on simulations (compare_simulations, get_contribution_analysis, get_simulation_trade_history, get_start_date_sensitivity, get_strategies_analytics, get_strategies_returns, get_rotation_dates, get_todays_rotations). The four listings (list_allocation_methods, list_covariance_estimators, list_risk_rule_presets, list_screen_filters) are what the catalogues fc.allocation, fc.estimators, fc.risk.presets and fc.filters were recorded from; fc.raw asks them live.