Strategies API

Functions that are called (with the strategy as argument) right after strategy construction.

Symbol representation of the strategy (name of the module).

The base type for all strategies.

SortedDict of holding buy orders

Ordering for buy orders (highest price first)

Cross margin strategy.

BuyOrder by ExchangeID

InstrumentInstance by ExchangeID

Order by ExchangeID

SellOrder by ExchangeID

Isolated margin strategy.

Live trading strategy.

call!(s::Strategy, ::LoadStrategy)

Strategy with isolated or cross margin.

Strategy with no margin at all.

Paper trading strategy.

PriceTime named tuple

Real time strategy (Paper, Live).

call!(s::Strategy, ::ResetStrategy)

SortedDict of holding sell orders

Ordering for sell orders (lowest price first)

Simulation strategy.

call!(s::Strategy, ::StartStrategy)

call!(s::Strategy, ::StopStrategy)

The strategy is the core type of the framework.

• self: The strategy module

• config: The Config the strategy was instantiated with

• timeframe: The smallest timeframe the strategy uses

• cash: The quote currency used for trades

• cash_committed: Cash kept busy by pending orders

• buyorders: Active buy orders

• sellorders: Active sell orders

• holdings: Assets with non zero balance

• universe: All the assets that the strategy knows about

• lock: A lock for thread safety

The strategy type is concrete according to:

• Name (Symbol)
• Exchange (ExchangeID), read from config
• Quote cash (Symbol), read from config
• Margin mode (MarginMode), read from config
• Execution mode (ExecMode), read from config

Conventions for strategy defined attributes:

• S: the strategy type.
• SC: the strategy type (exchange generic).
• TF: the smallest timeframe that the strategy uses
• DESCRIPTION: Name or short description for the strategy could be different from module name

Initializes a new Strategy object

Strategy(
    self::Module,
    mode::PlanarCore.Misc.ExecMode,
    margin::MarginMode,
    timeframe::TimeFrames.TimeFrame,
    exc::PlanarCore.ExchangeTypes.Exchange,
    uni::PlanarCore.Collections.InstrumentCollection;
    config
)

This function takes a module, execution mode, margin mode, timeframe, exchange, and asset collection to create a new Strategy object. It also accepts a config object to set specific parameters. The function validates the universe of assets and the strategy's cash, sets the exchange, and initializes orders and holdings.

call!(s::Strategy, ::StrategyMarkets)

call!(s::Strategy, ::WarmupPeriod)

Counts the number of orders for a given order side in a strategy.

count(
    s::PlanarCore.Strategies.Strategy,
    side::Type{<:PlanarCore.OrderTypes.OrderSide}
) -> Int64

This function iterates over the orders of a given side (Buy or Sell) in a strategy. It increments a counter by the length of the orders. The function returns the total count of orders.

Fills the strategy with the specified timeframes.

fill!(s::PlanarCore.Strategies.Strategy; kwargs...)

This function fills the strategy with the specified timeframes. It first creates a set of timeframes and adds the strategy's timeframe, the timeframes from the strategy's configuration, and the timeframe attribute of the strategy. It then fills the universe of the strategy with these timeframes.

Retrieves a property of a strategy using a string key.

getproperty(
    s::PlanarCore.Strategies.Strategy,
    sym::String
) -> Any

This function first gets the universe of the strategy and then retrieves the property using the string key.

Retrieves a property of a strategy.

getproperty(
    s::PlanarCore.Strategies.Strategy,
    sym::Symbol
) -> Any

This function checks if the property is directly on the strategy or the strategy's configuration. If the property is not found, it checks the configuration's attributes.

The name of the strategy module.

The name of the strategy module.

Creates a similar strategy with optional changes.

similar(
    s::PlanarCore.Strategies.Strategy;
    mode,
    timeframe,
    exc
) -> Union{PlanarCore.Strategies.Strategy{var"#s179", _A, _B, <:MarginMode{H}} where H<:PlanarCore.Misc.HedgedMode, PlanarCore.Strategies.Strategy{var"#s179", _A, _B, M} where {H<:PlanarCore.Misc.HedgedMode, M<:MarginMode{H}}} where {var"#s179"<:PlanarCore.Misc.ExecMode, _A, _B<:ExchangeID}

The similar function creates a new strategy that is similar to the given one. It allows for optional changes to the mode, timeframe, and exchange. The new strategy is created with the same self, margin mode, and universe as the original, but with a copy of the original's configuration.

Checks if the strategy's cash matches its universe.

iscashable(s::PlanarCore.Strategies.Strategy) -> Bool

The iscashable function checks if the cash of the strategy is cashable within the universe of the strategy. It returns true if the cash is cashable, and false otherwise.

Get the candle for the asset at date with timeframe tf.

Strategy exchange.

Retrieves the market identifiers for a given strategy type.

marketsid(
    s::Type{<:S<:PlanarCore.Strategies.Strategy}
) -> Any

The marketsid function invokes the call! function with the strategy type and StrategyMarkets() as arguments. This function is used to fetch the market identifiers associated with a specific strategy type.

Cash that is not committed, and therefore free to use for new orders.

The strategy Config attributes.

Called on each timestep iteration, possible multiple times. Receives:

• current_time: the current timestamp to evaluate (the current candle would be current_time - timeframe).
• ctx: The context of the executor.

call!(
    _::PlanarCore.Strategies.Strategy,
    current_time::Dates.DateTime,
    ctx
)

When an order is canceled the strategy is pinged with an order error.

call!(
    s::PlanarCore.Strategies.Strategy,
    ::PlanarCore.OrderTypes.Order,
    err::PlanarCore.OrderTypes.OrderError,
    ::PlanarCore.Instances.InstrumentInstance;
    kwargs...
) -> Any

Called at the end of the reset! function applied to a strategy.

call!(
    _::PlanarCore.Strategies.Strategy,
    _::PlanarCore.Strategies.ResetStrategy
)

Called before the strategy is started.

call!(
    _::PlanarCore.Strategies.Strategy,
    _::PlanarCore.Strategies.StartStrategy
)

Called after the strategy is stopped.

call!(
    _::PlanarCore.Strategies.Strategy,
    _::PlanarCore.Strategies.StopStrategy
)

How much lookback data the strategy needs.

call!(
    s::PlanarCore.Strategies.Strategy,
    _::PlanarCore.Strategies.WarmupPeriod
) -> Dates.Day

Called to construct the strategy, should return the strategy instance.

call!(
    _::Type{<:PlanarCore.Strategies.Strategy},
    cfg,
    _::PlanarCore.Strategies.LoadStrategy
) -> Union{PlanarCore.Strategies.Strategy{var"#s179", _A, _B, <:MarginMode{H}} where H<:PlanarCore.Misc.HedgedMode, PlanarCore.Strategies.Strategy{var"#s179", _A, _B, M} where {H<:PlanarCore.Misc.HedgedMode, M<:MarginMode{H}}} where {var"#s179"<:PlanarCore.Misc.ExecMode, _A, _B<:ExchangeID}

Market symbols that populate the strategy universe

Returns the strategy execution mode.

Get the strategy margin mode.

Resets the state of a strategy.

reset!(s::PlanarCore.Strategies.Strategy)
reset!(s::PlanarCore.Strategies.Strategy, config)

The reset! function is used to reset the state of a given strategy. It empties the buy and sell orders, resets the holdings and assets, and optionally re-applies the strategy configuration defaults. If the strategy is currently running, the reset operation is aborted with a warning.

Calculates the asset value for both long and short positions.

_assetval(
    ii::PlanarCore.Instances.InstrumentInstance{<:PlanarCore.Instruments.AbstractInstrument, <:ExchangeID, M} where M<:PlanarCore.Misc.WithMargin,
    n_holdings,
    min_hold,
    max_hold;
    price
)

This function iterates over both long and short positions. If the asset instance for a position is not zero, it increments the number of holdings and calculates the value of the asset for the position at the current price. It then updates the minimum and maximum holdings using the _mmh function. The function returns the updated number of holdings, minimum holdings, and maximum holdings.

Calculates the asset value for a NoMarginInstance.

_assetval(
    ii::PlanarCore.Instances.InstrumentInstance{<:PlanarCore.Instruments.AbstractInstrument, <:ExchangeID, NoMargin},
    n_holdings,
    min_hold,
    max_hold;
    price
)

This function checks if the cash of the NoMarginInstance is not zero. If it's not, it increments the number of holdings and calculates the value of the asset at the current price. It then updates the minimum and maximum holdings using the _mmh function. The function returns the updated number of holdings, minimum holdings, and maximum holdings.

Determines the margin mode of a module.

_defined_marginmode(mod) -> Any

This function attempts to determine the margin mode of a given module. It first tries to access the S property of the module to get the margin mode. If this fails, it then tries to access the SC property of the module.

Determines the file path for a strategy source.

_file(src, cfg, is_project) -> Any

This function determines the file path for a strategy source based on whether it is a project or not. If it is a project, it constructs the file path relative to the configuration path. If it is not a project, it retrieves the source file from the strategy's configuration or defaults to a predefined path. In case the file path is not found, it throws an ArgumentError with a detailed message.

Retrieves the source file for a strategy without a project.

The _include_projectless function retrieves the source file for a strategy that does not have a project. It checks the sources attribute of the strategy's configuration.

Updates the minimum and maximum holdings based on the provided value.

_mmh(ii, val, min_hold, max_hold) -> Tuple{Any, Any}

Given an asset instance, a value, and the current minimum and maximum holdings, this function updates the minimum and maximum holdings if the provided value is less than the current minimum or greater than the current maximum. It returns the updated minimum and maximum holdings.

Checks for inverse contracts in an exchange.

_no_inv_contracts(
    exc::PlanarCore.ExchangeTypes.Exchange,
    uni
)

This function checks for the presence of inverse contracts in a given exchange. If any inverse contracts are found, it asserts an error.

Performs checks on a loaded strategy.

_strat_load_checks(
    s::PlanarCore.Strategies.Strategy,
    config::PlanarCore.Misc.Config
) -> PlanarCore.Strategies.Strategy

This function performs checks on a loaded strategy. It asserts that the margin mode and execution mode of the strategy match the configuration. It also sets the verbose property of the strategy to false.

Determines the configuration for a strategy.

_strategy_config(src, path; load, config_args...)

This function determines the configuration for a strategy based on the source and path. If the strategy is to be loaded, it attempts to load the strategy cache. If the cache does not exist or is not a valid configuration, it creates a new configuration.

Determines the strategy type of a module.

_strategy_type(mod, cfg) -> Any

This function determines the strategy type of a given module. It first tries to access the S property of the module to get the strategy type. If this fails, it then tries to access the SC property of the module. The function also checks if the exchange is specified in the strategy or in the configuration.

Retrieves an asset instance by symbol.

asset_bysym(s::PlanarCore.Strategies.Strategy, sym) -> Any
asset_bysym(
    s::PlanarCore.Strategies.Strategy,
    sym,
    dict_bysim
) -> Any

This function retrieves an asset instance by symbol sym from a strategy s. It first checks if the asset instance is already cached in the strategy's attributes. If not, it retrieves the asset instance from the strategy's universe. If the asset instance is not found, it returns nothing.

Assets loaded by the strategy.

Loads a strategy without default settings.

bare_load(
    mod::Module,
    t::Type,
    config::PlanarCore.Misc.Config
) -> Union{PlanarCore.Strategies.Strategy{var"#s179", _A, _B, <:MarginMode{H}} where H<:PlanarCore.Misc.HedgedMode, PlanarCore.Strategies.Strategy{var"#s179", _A, _B, M} where {H<:PlanarCore.Misc.HedgedMode, M<:MarginMode{H}}} where {var"#s179"<:PlanarCore.Misc.ExecMode, _A, _B<:ExchangeID}

This function loads a strategy without default settings. It invokes the call! function of the module with the strategy type and StrategyMarkets(). It then creates a new Strategy instance with the module, assets, and configuration. The sandbox property is set based on the mode of the configuration. Finally, it performs checks on the loaded strategy.

Calculates the total value of a MarginStrategy with Paper.

current_total(
    s::PlanarCore.Strategies.Strategy{PlanarCore.Misc.Paper, N, <:ExchangeID, <:PlanarCore.Misc.WithMargin, C} where {N, C};
    ...
) -> Any
current_total(
    s::PlanarCore.Strategies.Strategy{PlanarCore.Misc.Paper, N, <:ExchangeID, <:PlanarCore.Misc.WithMargin, C} where {N, C},
    price_func;
    kwargs...
) -> Any

This function calculates the total value of a MarginStrategy{Paper} by summing up the value of all holdings and cash. The value of each holding is calculated using a provided price function. The default price function used is lasttrade_price_func, which returns the closing price of the last trade.

Calculates the total value of a MarginStrategy.

current_total(
    s::PlanarCore.Strategies.SimStrategy{N, <:ExchangeID, <:PlanarCore.Misc.WithMargin, C} where {N, C};
    price_func,
    kwargs...
) -> Any

This function calculates the total value of a MarginStrategy by summing up the value of all holdings and cash. The value of each holding is calculated using a provided price function. The default price function used is lasttrade_price_func, which returns the closing price of the last trade.

Calculates the total value of a NoMarginStrategy.

current_total(
    s::PlanarCore.Strategies.SimStrategy{N, <:ExchangeID, NoMargin, C} where {N, C};
    price_func,
    kwargs...
) -> Any

This function calculates the total value of a NoMarginStrategy by summing up the value of all holdings and cash. The value of each holding is calculated using a provided price function. The default price function used is lasttrade_price_func, which returns the closing price of the last trade.

Calculates the total value of a NoMarginStrategy with Paper.

current_total(
    s::PlanarCore.Strategies.Strategy{PlanarCore.Misc.Paper, N, <:ExchangeID, NoMargin, C} where {N, C};
    price_func,
    kwargs...
) -> Any

This function calculates the total value of a NoMarginStrategy{Paper} by summing up the value of all holdings and cash. The value of each holding is calculated using a provided price function. The default price function used is lasttrade_price_func, which returns the closing price of the last trade.

Set strategy defaults.

Loads a strategy with default settings.

default_load(
    mod::Module,
    t::Type,
    config::PlanarCore.Misc.Config
) -> Union{PlanarCore.Strategies.Strategy{var"#s179", _A, _B, <:MarginMode{H}} where H<:PlanarCore.Misc.HedgedMode, PlanarCore.Strategies.Strategy{var"#s179", _A, _B, M} where {H<:PlanarCore.Misc.HedgedMode, M<:MarginMode{H}}} where {var"#s179"<:PlanarCore.Misc.ExecMode, _A, _B<:ExchangeID}

This function loads a strategy with default settings. It invokes the call! function of the module with the strategy type and StrategyMarkets(). It then creates a new Strategy instance with the module, assets, and configuration. The sandbox property is set based on the mode of the configuration. Finally, it performs checks on the loaded strategy.

Finds the path of a given file.

find_path(file, cfg) -> Any

The find_path function checks various locations to find the path of a given file. It checks the current working directory, user directory, configuration directory, and project directory. If the file is not found, it raises an error.

Returns a unique identifier for a strategy instance, concatenating the strategy name, exchange id, and account.

Strategy assets instance.

Returns the date of the last trade for an asset instance.

lasttrade_date(ii) -> Any
lasttrade_date(ii, def) -> Any

This function returns the date of the last trade for an InstrumentInstance. If the history of the asset instance is empty, it returns the timestamp of the last candle.

Returns a function for the last trade date of a strategy.

lasttrade_func(s) -> Union{typeof(last), Returns}

This function returns a function that, when called, gives the date of the last trade for a Strategy. If there is no last trade, it returns the last function.

The asset close price of the candle where the last trade was performed.

Generates the path for strategy logs.

logpath(
    s::PlanarCore.Strategies.Strategy;
    name,
    path_nodes...
) -> String

The logpath function generates a path for storing strategy logs. It takes the strategy and optional parameters for the name of the log file and additional path nodes. The function checks if the directory for the logs exists and creates it if necessary. It then returns the full path to the log file.

Retrieves the logs for a strategy.

logs(s::PlanarCore.Strategies.Strategy) -> Vector{Any}

The logs function collects and returns all the logs associated with a given strategy. It fetches the logs from the directory specified in the strategy's path.

Calculates the minimum and maximum holdings for a strategy.

minmax_holdings(
    s::PlanarCore.Strategies.Strategy
) -> NamedTuple{(:min, :max, :count), <:Tuple{Tuple{Any, Any}, Tuple{Any, Any}, Int64}}

This function iterates over the holdings of a strategy. For each holding, it calculates the current price and updates the number of holdings, minimum holdings, and maximum holdings using the _assetval function. The function returns the minimum holdings, maximum holdings, and the count of holdings.

Called on each tick in tick-mode backtesting. Receives:

• ctx: The tick context of the executor.
• tick: The current market trade.

ping!(_::PlanarCore.Strategies.Strategy, ctx, tick)

Reloads OHLCV data for assets in the strategy universe.

reload!(s::PlanarCore.Strategies.Strategy)

The reload! function empties the data for each asset instance in the strategy's universe and then loads new data. This is useful for refreshing the strategy's knowledge of the market state.

Saves the state of a strategy.

save_strategy(s)

This function saves the state of a given strategy. It determines the cache path and saves the strategy state to this path.

Keeps track of max allocated containers size for strategy and asset instances in the universe.

sizehint!(s::PlanarCore.Strategies.Strategy)

This function keeps track of the maximum allocated containers size for strategy and asset instances in the universe. It updates the sizes of various containers based on the current state of the strategy.

Loads a strategy from a source, module, or string.

strategy(src::Union{Module, String, Symbol}; ...) -> Any
strategy(
    src::Union{Module, String, Symbol},
    path::String;
    load,
    config_args...
) -> Any

This function loads a strategy from a given source, module, or string. It first determines the configuration for the strategy based on the source and path. If the strategy is to be loaded, it attempts to load the strategy cache. Finally, it returns the loaded strategy.

Loads a strategy from a module.

strategy!(mod::Module, cfg::PlanarCore.Misc.Config) -> Any

This function loads a strategy from a given module. It first checks and sets the mode and margin of the configuration if they are not set. It then determines the strategy type of the module and checks if the exchange is specified in the strategy or in the configuration. Finally, it tries to load the strategy with default settings, if it fails, it loads the strategy without default settings.

Loads a strategy from a symbol source.

strategy!(src::Symbol, cfg::PlanarCore.Misc.Config) -> Any

This function loads a strategy from a given symbol source. It first determines the file path for the strategy source and checks if it is a project. If it is a project, it activates and instantiates the project. The function then includes the source file and uses it. If the source file is not defined in the parent module, it is evaluated and tracked for changes. Finally, the function returns the loaded strategy.

Returns a strategy by name, defaulting to parent_module=Planar for non-BareStrat strategies.

Returns the default strategy (BareStrat).

Returns the path to the strategy cache.

strategy_cache_path() -> String

This function returns the path to the strategy cache. It checks if the path exists and creates it if it doesn't.

The throttle attribute determines the strategy polling interval.

Counts all trades recorded in the strategy universe.

trades_count(
    s::PlanarCore.Strategies.Strategy,
    _::Val{:liquidations}
) -> NamedTuple{(:trades, :liquidations), <:Tuple{Any, Any}}

This function iterates over the universe of a strategy. For each asset instance in the universe, it increments a counter by the length of the asset instance's history. The function returns the total count of trades.

Counts the number of long, short, and liquidation trades in the strategy universe.

trades_count(
    s::PlanarCore.Strategies.Strategy,
    _::Val{:positions}
) -> NamedTuple{(:long, :short, :liquidations), <:Tuple{Any, Any, Any}}

This function iterates over the universe of a strategy. For each asset instance in the universe, it counts the number of long trades, short trades, and liquidation trades. The function returns the total count of long trades, short trades, and liquidation trades.

All trades recorded in the strategy universe (includes liquidations).

Returns the first and last trade of any asset in the strategy universe.

tradesedge(
    s::PlanarCore.Strategies.Strategy
) -> Tuple{Any, Any}

This function returns the first and last trade of any asset in the strategy universe for a given Strategy. If there are no trades, it returns nothing.

Returns the dates of the first and last trade present in the strategy.

tradesedge(
    _::Type{Dates.DateTime},
    s::PlanarCore.Strategies.Strategy
) -> Tuple{Any, Any}

This function returns the dates of the first and last trade of any asset in the strategy universe for a given Strategy.

Returns the recorded trading period from the trades history present in the strategy.

tradesperiod(s::PlanarCore.Strategies.Strategy) -> Any

This function returns the recorded trading period from the trades history present in the strategy. It calculates the period by subtracting the start date from the stop date.

Returns a DateRange spanning the historical time period of the trades recorded by the strategy.

tradesrange(
    s::PlanarCore.Strategies.Strategy;
    ...
) -> PlanarCore.TimeTicks.DateRange
tradesrange(
    s::PlanarCore.Strategies.Strategy,
    tf;
    start_pad,
    stop_pad
) -> PlanarCore.TimeTicks.DateRange

This function returns a DateRange that spans the historical time period of the trades recorded by the strategy. It calculates the range by adding the start and stop pads to the edges of the trades.

The strategy InstrumentCollection.

Defines a set of functions for a given candle function.

This macro generates two functions for each candle function passed to it. The first function is for getting the candle data from an InstrumentInstance at a specific date. The second function is for getting the candle data from a Strategy at a specific date with a specified timeframe. The timeframe defaults to the strategy's timeframe if not provided.

Provides a common interface for strategy execution.

The interface macro imports the call! function from the Strategies module, the assets and exchange functions, and the call! function from the Executors module. This macro is used to provide a common interface for strategy execution.

Raises an error when a strategy is not found at a given path.