Class for running a simulation and getting results.
new()Create a new Simulation object.
Simulation$new( config = NULL, raw_input_data = NULL, raw_pricing_data = NULL, security_reference_data = NULL, delisting_dates_data = NULL )
configAn object of class list or character, or
NULL. If the value passed is a character vector, it should be of
length 1 and specify the path to a yaml configuration file that
contains the object's configuration info. If the value passed is of
class list(), the list should contain the object's configuration info
in list form (e.g, the return value of calling yaml.load_file on
the configuration file). If the value passed is NULL, then there
will be no configuration information associated with the simulation and
it will not possible to call the run method. Setting
config = NULL is useful when creating simulation objects into
which results will be loaded with readFeather.
raw_input_dataA data frame that contains all of the input data
(for all periods) for the simulation. The data frame must have a
date column. Data supplied using this parameter will only be
used if the configuration option simulator/input_data/type is
set to object. Defaults to NULL.
raw_pricing_dataA data frame that contains all of the input data
(for all periods) for the simulation. The data frame must have a
date column. Data supplied using this parameter will only be
used if the configuration option simulator/pricing_data/type is
set to object. Defaults to NULL.
security_reference_dataA data frame that contains reference data
on the securities in the simulation, including any categories that are
used in portfolio construction constraints. Note that the simulator
will throw an error if there are input data records for which there is
no entry in the security reference. Data supplied using this parameter
will only be used if the configuration option
simulator/secref_data/type is set to object. Defaults to
NULL.
delisting_dates_dataA data frame that contains the dates on which
securities are delisted. It must contain two columns: id (character)
and delisting_date (Date). The date in the delisting_date column means
the day on which a stock will be removed from the simulation portfolio,
at the beginning of the day, due to delisting. Data supplied using this
parameter will only be used if the configuration option
simulator/delisting_data/type is set to object. Defaults to
NULL.
A new Simulation object.
setVerbose()Set the verbose flag to control info output.
Simulation$setVerbose(verbose)
verboseLogical flag indicating whether to be verbose or not.
No return value, called for side effects.
setShinyCallback()Set the callback function for updating progress when running a simulation in shiny.
Simulation$setShinyCallback(callback)
callbackA function suitable for updating a shiny Progress object.
It must have two parameters: value, indicating the progress
amount, and detail, and detail, a text string for display on the
progress bar.
No return value, called for side effects.
getSecurityReference()Get security reference information.
Simulation$getSecurityReference()
An object of class data.frame that contains the security
reference data for the simulation.
run()Run the simulation.
Simulation$run()
No return value, called for side effects.
getSimDates()Get a list of all date for the simulation.
Simulation$getSimDates()
A vector of class Date over which the simulation currently iterates: all
weekdays between the 'from' and 'to' dates in the simulation's config.
getSimSummary()Get summary information.
Simulation$getSimSummary()
An object of class data.frame that contains summary data
for the simulation, by period, at the joint and strategy level. The data
frame contains the following columns:
Strategy name, or 'joint' for the aggregate strategy.
Date of the summary data.
Total net market value of fills that do not net down across strategies.
Total net market value of fills that represent "internal transfers", i.e., fills in one strategy that net down with fills in another. Note that at the joint level this column by definition is 0.
Total gross market value of orders that do not net down across strategies.
Total gross market value of fills that do not net down across strategies.
Total gross market value of fills that represent "internal transfers", i.e., fills in one strategy that net down with fills in another.
Total net market value of all positions at the start of the period.
Total net market value of all long positions at the start of the period.
Total net market value of all short positions at the start of the period.
Total net market value of all positions at the end of the period.
Total gross market value of all positions at the end of the period.
Total net market value of all long positions at the end of the period.
Total net market value of all short positions at the end of the period.
Total number of positions at the end of the period.
Total number of long positions at the end of the period.
Total number of short positions at the end of the period.
The total difference between the end and start market value of positions.
The total difference between the market value of trades at the benchmark price and at the end price. Note: currently assuming benchmark price is the closing price, so trading P&L is zero.
Total P&L gross of costs, calculated as position_pnl + trading_pnl.
Total trade costs (slippage).
Total financing/borrow costs.
Total P&L net of costs, calculated as gross_pnl - trade_costs - financing_costs.
Total fill rate across all market orders, calculated as 100 * market_fill_gmv / market_order_gmv.
getSimDetail()Get detail information.
Simulation$getSimDetail( sim_date = NULL, strategy_name = NULL, security_id = NULL )
sim_dateVector of length 1 of class Date or character that
specifies the period for which to get detail information. If
NULL then data from all periods is returned. Defaults
to NULL.
strategy_nameCharacter vector of length 1 that specifies the
strategy for which to get detail data. If NULL data for all
strategies is returned. Defaults to NULL.
security_idCharacter vector of length 1 that specifies the
security for which to get detail data. If NULL data for all
securities is returned. Defaults to NULL.
An object of class data.frame that contains detail data
for the simulation at the joint and strategy level. Detail data is at
the security level. The data frame contains the following columns:
Security identifier.
Strategy name, or 'joint' for the aggregate strategy.
Date to which the data pertains.
Shares at the start of the period.
Shares at the start of the period that net down with positions in other strategies.
Shares at the start of the period that do not net down with positions in other strategies.
Order, in shares.
Order that does not net down with orders in other strategies, in shares.
Order that nets down with orders in other strategies, in shares.
Fill, in shares.
Fill that does not net down with fills in other strategies, in shares.
Fill that nets down with fills in other strategies, in shares.
Shares at the end of the period.
Shares at the end of the period that net down with positions in other strategies.
Shares at the end of the period that do not net down with positions in other strategies.
Price for the security at the beginning of the period.
Price for the security at the end of the period.
Dividend for the security, if any, for the period.
Distribution (e.g., spin-off) for the security, if any, for the period.
Position P&L, calculated as shares * (end_price + dividend + distribution - start_price)
The difference between the market value of trades at the benchmark price and at the end price. Note: currently assuming benchmark price is the closing price, so trading P&L is zero.
Trade costs, calculated as a fixed percentage (set in the simulation configuration) of the notional of the market trade (valued at the close).
Financing cost for the position, calculated as a fixed percentage (set in the simulation configuration) of the notional of the starting value of the portfolio's external positions. External positions are positions held on the street and are recorded in the ext_shares column.
Gross P&L, calculated as position_pnl + trading_pnl.
Net P&L, calculated as gross_pnl - trade_costs - financing_costs.
Net market value of the order that does not net down with orders in other strategies.
Gross market value of the order that does not net down with orders in other strategies.
Net market value of the fill that does not net down with orders in other strategies.
Gross market value of the fill that does not net down with orders in other strategies.
Net market value of the fill that nets down with fills in other strategies.
Gross market value of the fill that nets down with fills in other strategies.
Net market value of the position at the start of the period.
Net market value of the position at the end of the period.
Gross market value of the position at the end of the period.
getPositionSummary()Get summary information by security. This method can be used, for example, to calculate the biggest winners and losers over the course of the simulation.
Simulation$getPositionSummary(strategy_name = NULL)
strategy_nameCharacter vector of length 1 that specifies the
strategy for which to get detail data. If NULL data for all
strategies is returned. Defaults to NULL.
An object of class data.frame that contains summary
information aggregated by security. The data frame contains the
following columns:
Security identifier.
Strategy name, or 'joint' for the aggregate strategy.
Gross P&L for the position over the entire simulation.
Net P&L for the position over the entire simulation.
Average net market value of the position over days in the simulation where the position was not flat.
Total gross market value of trades for the security.
Total cost of trades for the security over the entire simulation.
Total cost of financing for the position over the entire simulation.
Total number of days there was a position in the security in the portfolio over the entire simulation.
getInputStats()Get input statistics.
Simulation$getInputStats()
An object of class data.frame that contains statistics on
select columns of input data. Statistics are tracked for the columns
listed in the configuration variable
simulator/input_data/track_metadata. The data frame contains the
following columns:
Period to which statistics pertain.
Total number of rows of input data, including rows carried forward from the previous period.
Total number of rows carried forward from the previous period.
Number of NA values in column. This
measure appears for each element of track_metadata.
Period-over-period correlation for column.
This measure appears for each element of track_metadata.
getLooseningInfo()Get loosening information.
Simulation$getLooseningInfo()
An object of class data.frame that contains, for each
period, which constraints were loosened in order to solve the portfolio
optimization problem, if any. The data frame contains the
following columns:
Date for which the constraint was loosened.
Name of the constraint that was loosened.
Percentage by which the constraint was loosened, where 100 means loosened fully (i.e., the constraint is effectively removed).
getOptimizationSummary()Get optimization summary information.
Simulation$getOptimizationSummary()
An object of class data.frame that contains optimization
summary information, such as starting and ending factor constraint
values, at the strategy and joint level. The data frame contains the
following columns:
Strategy name, or 'joint' for the aggregate strategy.
Date to which the data pertains.
Total gross market value of orders generated by the optimization.
Total net market value of short positions at the start of the optimization.
Total net market value of long positions at the start of the optimization.
Total net market value of short positions at the end of the optimization.
Total net market value of long positions at the end of the optimization.
Total net exposure to factor at the start of the optimization, for each factor constraint.
Total net exposure to factor at the start of the optimization, for each factor constraint.
getExposures()Get end-of-period exposure information.
Simulation$getExposures()
An object of class data.frame that contains end-of-period
exposure information for the simulation portfolio. The units of the
exposures are portfolio weight relative to strategy_captial (i.e., net
market value of exposure divided by strategy capital). The data frame
contains the following columns:
Strategy name, or 'joint' for the aggregate strategy.
Date of the exposure data.
Exposure to level within category, for all levels of all category constraints, at the end of the period.
Exposure to factor, for all factor constraints, at the end of the period.
getDelistings()Get information on positions removed due to delisting.
Simulation$getDelistings()
An object of class data.frame that contains a row for each
position that is removed from the simulation portfolio due to a
delisting. Each row contains the size of the position on the day on
which it was removed from the portfolio.
getSingleStrategySummaryDf()Get summary information for a single strategy suitable for plotting input.
Simulation$getSingleStrategySummaryDf(strategy_name, include_zero_row = TRUE)
strategy_nameStrategy for which to return summary data.
include_zero_rowLogical flag indicatiing whether to prepend a row
to the summary data with starting values at zero. Defaults to TRUE.
A data frame that contains summary information for the desired strategy, as well as columns for cumulative net and gross total return, calculated as pnl divided by ending gross market value.
plotPerformance()Draw a plot of cumulative gross and net return by date.
Simulation$plotPerformance()
plotMarketValue()Draw a plot of total gross, long, short, and net market value by date.
Simulation$plotMarketValue()
plotCategoryExposure()Draw a plot of exposure to all levels in a category by date.
Simulation$plotCategoryExposure(in_var)
in_varCategory for which exposures are plotted.
plotFactorExposure()Draw a plot of exposure to factors by date.
Simulation$plotFactorExposure(in_var)
in_varFactors for which exposures are plotted.
plotNumPositions()Draw a plot of number of long and short positions by date.
Simulation$plotNumPositions()
overallStatsDf()Calculate overall simulation summary statistics, such as total P&L, Sharpe, average market values and counts, etc.
Simulation$overallStatsDf()
A data frame that contains summary statistics, suitable for reporting.
print()Print overall simulation statistics.
Simulation$print()
writeFeather()Write the data in the object to feather files.
Simulation$writeFeather(out_loc)
out_locDirectory in which output files should be created.
No return value, called for side effects.
readFeather()Load files created with writeFeather into the object.
Note that because detail data is not re-split by period, it will not be
possible to use the sim_date parameter when calling
getSimDetail on the populated object.
Simulation$readFeather(in_loc)
in_locDirectory that contains files to be loaded.
No return value, called for side effects.
clone()The objects of this class are cloneable with this method.
Simulation$clone(deep = FALSE)
deepWhether to make a deep clone.
The Simulation class is used to set up and run a daily
simulation over a particular period. Portfolio construction parameters and
other simulator settings can be configured in a yaml file that is passed to
the object's constructor. See vignette("strand") for information on
configuration file setup.