Funds and ETFs

Fund is a fund product: share classes and documents, with one strategy and one vehicle, backtested by fund.backtest(). An exchange-traded fund is a Fund with an exchange-traded vehicle.

fund

Fund products.

Fund is a fund product: a name, a currency, share classes and documents, with one strategy and one vehicle (see beacon.backtest.presets), whose backtest() runs a Backtest of it. An exchange-traded fund is a Fund with an exchange-traded vehicle, such as ucits_etf() or us_etf().

Fund

Fund(
    name: str,
    strategy: AnyIndexDefinition | IndexTracking,
    vehicle: Vehicle,
    currency: str | None = None,
    share_classes: Iterable[ShareClass] = (),
    documents: Mapping[str, str] | None = None,
)

A fund product, with one strategy and one vehicle.

Parameters:

Name	Type	Description	Default
name	str	The fund's name.	required
strategy	AnyIndexDefinition | IndexTracking	What it holds: an index definition, tracked in full, or an IndexTracking holding one through a replication.	required
vehicle	Vehicle	How the money is held, such as a preset from beacon.backtest.presets.	required
currency	str | None	The fund's base currency. None keeps the index's.	None
share_classes	Iterable[ShareClass]	Its share classes. One accumulating class at the vehicle's fee when none are given.	()
documents	Mapping[str, str] | None	Its documents by name (a prospectus, a factsheet), as paths or links. Kept with the record and not read.	None

Raises:

Type	Description
ValueError	If name is empty or two classes share a name.

share_class

share_class(name: str | None = None) -> ShareClass

A share class by name, or the first when name is None.

Raises:

Type	Description
KeyError	If there is no class by that name; the message lists them.

backtest

backtest(
    end: str,
    initial_capital: float | Mapping[str, float],
    start: str | None = None,
    flows: Flows
    | list[Flows]
    | Mapping[str, Flows | list[Flows]]
    | None = None,
    implementation: Implementation | None = None,
    modelling_assumptions: ModellingAssumptions
    | None = None,
    transaction_cost_bps: float = 0.0,
    benchmark: IndexResult | Series | None = None,
    data_provider: DataFetcher | None = None,
    cache: IndexResultCache | Literal[False] | None = None,
    **backtest_settings: Any,
) -> BacktestResult

Backtest the fund, every share class together: a Backtest with the fund's vehicle and classes, run on its strategy.

Parameters:

Name	Type	Description	Default
end	str	The last day, YYYY-MM-DD.	required
initial_capital	float | Mapping[str, float]	Each class's capital at launch, by name, such as {"Acc": 6e7, "Dist": 4e7}; a class left out starts empty. One number for a fund with one class.	required
start	str | None	The first day; the strategy's base date when None.	None
flows	Flows | list[Flows] | Mapping[str, Flows | list[Flows]] | None	Money arriving and leaving, each class's by name; one scenario or a list for a fund with one class.	None
implementation	Implementation | None	Screens, caps, costs and execution.	None
modelling_assumptions	ModellingAssumptions | None	What the run takes as given.	None
transaction_cost_bps	float	The fixed cost of each trade.	0.0
benchmark	IndexResult | Series | None	The benchmark of record.	None
data_provider	DataFetcher | None	The data the run reads; the ambient source when None.	None
cache	IndexResultCache | Literal[False] | None	Where calculated indices are kept; see Backtest.	None
**backtest_settings	Any	Any other Backtest setting, such as modifiers or price_column.	{}

Returns:

Name	Type	Description
BacktestResult	BacktestResult	The fund's run, with each class's book in
	BacktestResult	share_classes.

ShareClass dataclass

ShareClass(
    name: str,
    management_fee_bps: float | None = None,
    distribution: str = ACCUMULATING,
    currency: str | None = None,
    hedged: bool = False,
    hedge_ratio: float = 1.0,
    hedge_band: float | None = 0.03,
    hedge_cost_bps: float = 0.0,
)

One share class of a fund.

Attributes:

Name	Type	Description
name	str	What the class is called, such as "Acc" or "I GBP Dist".
management_fee_bps	float | None	The class's annual management fee in basis points. None uses the vehicle's.
distribution	str	"accumulating" (the default) keeps its income in the fund, "distributing" pays it out.
currency	str | None	The class's currency, such as "EUR". None for the book's.
hedged	bool	Whether it hedges its share of the assets into its currency with a monthly forward.
hedge_ratio	float	The share of its net assets it hedges, 1.0 for all.
hedge_band	float | None	How far the hedge ratio may drift between monthly rolls, such as 0.03 for 97% to 103%, before the forward is resized. None resizes only at the rolls.
hedge_cost_bps	float	What trading its forwards costs, in basis points of the notional each trade deals.

Raises:

Type	Description
ValueError	If the distribution is not one of the two, the fee is negative, the currency is not a three-letter code, a hedge has no currency, or the hedge ratio, band or cost is out of range.

fund

A fund product: what it is called, what it holds and how it is held.

fund = Fund(name="Sample UCITS ETF", strategy=my_index,
            vehicle=ucits_etf(management_fee_bps=12),
            share_classes=[ShareClass("Acc"), ShareClass("Dist", distribution="distributing")])

result = fund.backtest(end="2024-12-31", initial_capital={"Acc": 6e7, "Dist": 4e7},
                       data_provider=fetcher)
result.share_classes["Dist"].nav_per_unit

A Fund is a record of a real product, as a prospectus describes one: a name, a currency, its share classes and documents, with one strategy (what it holds) and one vehicle (how the money is held). It is not what the engine runs: fund.backtest(...) is a Backtest with the fund's vehicle, run on its strategy, so a saved product and a what-if run are the same computation.

Share classes

Each share class has its own management fee and distribution policy, and all of them share one pool of assets: fund.backtest runs the fund once with every class, each with its own capital and flows, and result.share_classes holds each class's book (see beacon.backtest.share_classes).

ShareClass dataclass

ShareClass(
    name: str,
    management_fee_bps: float | None = None,
    distribution: str = ACCUMULATING,
    currency: str | None = None,
    hedged: bool = False,
    hedge_ratio: float = 1.0,
    hedge_band: float | None = 0.03,
    hedge_cost_bps: float = 0.0,
)

One share class of a fund.

Attributes:

Name	Type	Description
name	str	What the class is called, such as "Acc" or "I GBP Dist".
management_fee_bps	float | None	The class's annual management fee in basis points. None uses the vehicle's.
distribution	str	"accumulating" (the default) keeps its income in the fund, "distributing" pays it out.
currency	str | None	The class's currency, such as "EUR". None for the book's.
hedged	bool	Whether it hedges its share of the assets into its currency with a monthly forward.
hedge_ratio	float	The share of its net assets it hedges, 1.0 for all.
hedge_band	float | None	How far the hedge ratio may drift between monthly rolls, such as 0.03 for 97% to 103%, before the forward is resized. None resizes only at the rolls.
hedge_cost_bps	float	What trading its forwards costs, in basis points of the notional each trade deals.

Raises:

Type	Description
ValueError	If the distribution is not one of the two, the fee is negative, the currency is not a three-letter code, a hedge has no currency, or the hedge ratio, band or cost is out of range.

Fund

Fund(
    name: str,
    strategy: AnyIndexDefinition | IndexTracking,
    vehicle: Vehicle,
    currency: str | None = None,
    share_classes: Iterable[ShareClass] = (),
    documents: Mapping[str, str] | None = None,
)

A fund product, with one strategy and one vehicle.

Parameters:

Name	Type	Description	Default
name	str	The fund's name.	required
strategy	AnyIndexDefinition | IndexTracking	What it holds: an index definition, tracked in full, or an IndexTracking holding one through a replication.	required
vehicle	Vehicle	How the money is held, such as a preset from beacon.backtest.presets.	required
currency	str | None	The fund's base currency. None keeps the index's.	None
share_classes	Iterable[ShareClass]	Its share classes. One accumulating class at the vehicle's fee when none are given.	()
documents	Mapping[str, str] | None	Its documents by name (a prospectus, a factsheet), as paths or links. Kept with the record and not read.	None

Raises:

Type	Description
ValueError	If name is empty or two classes share a name.

share_class

share_class(name: str | None = None) -> ShareClass

A share class by name, or the first when name is None.

Raises:

Type	Description
KeyError	If there is no class by that name; the message lists them.

backtest

backtest(
    end: str,
    initial_capital: float | Mapping[str, float],
    start: str | None = None,
    flows: Flows
    | list[Flows]
    | Mapping[str, Flows | list[Flows]]
    | None = None,
    implementation: Implementation | None = None,
    modelling_assumptions: ModellingAssumptions
    | None = None,
    transaction_cost_bps: float = 0.0,
    benchmark: IndexResult | Series | None = None,
    data_provider: DataFetcher | None = None,
    cache: IndexResultCache | Literal[False] | None = None,
    **backtest_settings: Any,
) -> BacktestResult

Backtest the fund, every share class together: a Backtest with the fund's vehicle and classes, run on its strategy.

Parameters:

Name	Type	Description	Default
end	str	The last day, YYYY-MM-DD.	required
initial_capital	float | Mapping[str, float]	Each class's capital at launch, by name, such as {"Acc": 6e7, "Dist": 4e7}; a class left out starts empty. One number for a fund with one class.	required
start	str | None	The first day; the strategy's base date when None.	None
flows	Flows | list[Flows] | Mapping[str, Flows | list[Flows]] | None	Money arriving and leaving, each class's by name; one scenario or a list for a fund with one class.	None
implementation	Implementation | None	Screens, caps, costs and execution.	None
modelling_assumptions	ModellingAssumptions | None	What the run takes as given.	None
transaction_cost_bps	float	The fixed cost of each trade.	0.0
benchmark	IndexResult | Series | None	The benchmark of record.	None
data_provider	DataFetcher | None	The data the run reads; the ambient source when None.	None
cache	IndexResultCache | Literal[False] | None	Where calculated indices are kept; see Backtest.	None
**backtest_settings	Any	Any other Backtest setting, such as modifiers or price_column.	{}

Returns:

Name	Type	Description
BacktestResult	BacktestResult	The fund's run, with each class's book in
	BacktestResult	share_classes.