Simulation: Simulation class
In strand: A Framework for Investment Strategy Simulation
Description
Class for running a simulation and getting results.
Details
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.
Methods
Public methods
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
Method new()
Create a new Simulation object.
Usage
Simulation$new(
config = NULL,
raw_input_data = NULL,
input_dates = NULL,
raw_pricing_data = NULL,
security_reference_data = NULL,
delisting_data = NULL
)
Arguments
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 be
used if the configuration option simulator/input_data/type is
set to object. Defaults to NULL.
input_datesVector of class Date that specifies when input
data should be updated. If data is being supplied using the
raw_input_data parameter, then input_dates defaults to
set of dates present in this data.
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_dataA data frame that contains delisting dates and
associated returns. It must contain three columns: id (character),
delisting_date (Date), and delisting_return (numeric). The date in the
delisting_date column means the day on which a stock will be removed
from the simulation portfolio. It is typically the day after the last
day of trading. The delisting_return column reflects what, if any, P&L
should be recorded on the delisting date. A delisting_return of -1
means that the shares were deemed worthless. The delisting return is
multiplied by the starting net market value of the position to
determine P&L for the delisted position on the delisting date. Note
that the portfolio optimization does not include stocks that are being
removed 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.
Returns
A new Simulation object.
Method setVerbose()
Set the verbose flag to control info output.
Usage
Simulation$setVerbose(verbose)
Arguments
verboseLogical flag indicating whether to be verbose or not.
Returns
No return value, called for side effects.
Method setShinyCallback()
Set the callback function for updating progress when running
a simulation in shiny.
Usage
Simulation$setShinyCallback(callback)
Arguments
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.
Returns
No return value, called for side effects.
Method getSecurityReference()
Get security reference information.
Usage
Simulation$getSecurityReference()
Returns
An object of class data.frame that contains the security
reference data for the simulation.
Method run()
Run the simulation.
Usage
Simulation$run()
Returns
No return value, called for side effects.
Method getSimDates()
Get a list of all date for the simulation.
Usage
Simulation$getSimDates()
Returns
A vector of class Date over which the simulation currently iterates: all
weekdays between the 'from' and 'to' dates in the simulation's config.
Method getSimSummary()
Get summary information.
Usage
Simulation$getSimSummary(strategy_name = NULL)
Arguments
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.
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date of the summary data.
- market_fill_nmv
Total net market value of fills that do not
net down across strategies.
- transfer_fill_nmv
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.
- market_order_gmv
Total gross market value of orders that do not
net down across strategies.
- market_fill_gmv
Total gross market value of fills that do not
net down across strategies.
- transfer_fill_gmv
Total gross market value of fills that
represent "internal transfers", i.e., fills in one strategy that net
down with fills in another.
- start_nmv
Total net market value of all positions at the start
of the period.
- start_lmv
Total net market value of all long positions at the
start of the period.
- start_smv
Total net market value of all short positions at the
start of the period.
- end_nmv
Total net market value of all positions at the end of
the period.
- end_gmv
Total gross market value of all positions at the end
of the period.
- end_lmv
Total net market value of all long positions at the
end of the period.
- end_smv
Total net market value of all short positions at the
end of the period.
- end_num
Total number of positions at the end of the period.
- end_num_long
Total number of long positions at the end of the
period.
- end_num_short
Total number of short positions at the end of
the period.
- position_pnl
The total difference between the end and start
market value of positions.
- trading_pnl
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.
- gross_pnl
Total P&L gross of costs, calculated as position_pnl
+ trading_pnl.
- trade_costs
Total trade costs (slippage).
- financing_costs
Total financing/borrow costs.
- net_pnl
Total P&L net of costs, calculated as gross_pnl -
trade_costs - financing_costs.
- fill_rate_pct
Total fill rate across all market orders,
calculated as 100 * market_fill_gmv / market_order_gmv.
- num_investable
Number of investable securities (size of universe).
Method getSimDetail()
Get detail information.
Usage
Simulation$getSimDetail(
sim_date = NULL,
strategy_name = NULL,
security_id = NULL,
columns = NULL
)
Arguments
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.
columnsVector of class character specifying the columns to
return. This parameter can be useful when dealing with very large
detail datasets.
Returns
An object of class data.frame that contains security-level
detail data for the simulation for the desired strategies, securities,
dates, and columns. Available columns include:
- id
Security identifier.
- strategy
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date to which the data pertains.
- shares
Shares at the start of the period.
- int_shares
Shares at the start of the period that net down
with positions in other strategies.
- ext_shares
Shares at the start of the period that do not net
down with positions in other strategies.
- order_shares
Order, in shares.
- market_order_shares
Order that does not net down with orders
in other strategies, in shares.
- transfer_order_shares
Order that nets down with orders in
other strategies, in shares.
- fill_shares
Fill, in shares.
- market_fill_shares
Fill that does not net down with fills in
other strategies, in shares.
- transfer_fill_shares
Fill that nets down with fills in other
strategies, in shares.
- end_shares
Shares at the end of the period.
- end_int_shares
Shares at the end of the period that net down
with positions in other strategies.
- end_ext_shares
Shares at the end of the period that do not net
down with positions in other strategies.
- start_price
Price for the security at the beginning of the
period.
- end_price
Price for the security at the end of the period.
- dividend
Dividend for the security, if any, for the
period.
- distribution
Distribution (e.g., spin-off) for the security, if
any, for the period.
- investable
Logical indicating whether the security is part of
the investable universe. The value of the flag is set to TRUE if the
security has not been delisted and satisfies the universe criterion
provided (if any) in the simulator/universe configuration
option.
- delisting
Logical indicating whether a position in the
security was removed due to delisting. If delisting is set to TRUE,
the gross_pnl and net_pnl columns will contain the P&L
due to delisting, if any. P&L due to delisting is calculated as the
delisting return times the start_nmv of the position.
- position_pnl
Position P&L, calculated as shares * (end_price +
dividend + distribution - start_price)
- trading_pnl
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
Trade costs, calculated as a fixed percentage (set
in the simulation configuration) of the notional of the market trade
(valued at the close).
- financing_costs
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_pnl
Gross P&L, calculated as position_pnl + trading_pnl.
- net_pnl
Net P&L, calculated as gross_pnl - trade_costs -
financing_costs.
- market_order_nmv
Net market value of the order that does not
net down with orders in other strategies.
- market_fill_gmv
Gross market value of the order that does not
net down with orders in other strategies.
- market_fill_nmv
Net market value of the fill that does not net
down with orders in other strategies.
- market_fill_gmv
Gross market value of the fill that does not
net down with orders in other strategies.
- transfer_fill_nmv
Net market value of the fill that nets down
with fills in other strategies.
- transfer_fill_gmv
Gross market value of the fill that nets down
with fills in other strategies.
- start_nmv
Net market value of the position at the start of the
period.
- end_nmv
Net market value of the position at the end of the
period.
- end_gmv
Gross market value of the position at the end of the
period.
Method 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.
Usage
Simulation$getPositionSummary(strategy_name = NULL)
Arguments
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.
Returns
An object of class data.frame that contains summary
information aggregated by security. The data frame contains the
following columns:
- id
Security identifier.
- strategy
Strategy name, or 'joint' for the aggregate
strategy.
- gross_pnl
Gross P&L for the position over the entire
simulation.
- gross_pnl
Net P&L for the position over the entire
simulation.
- average_market_value
Average net market value of the
position over days in the simulation where the position was not
flat.
- total_trading
Total gross market value of trades for the
security.
- trade_costs
Total cost of trades for the security over the
entire simulation.
- trade_costs
Total cost of financing for the position over the
entire simulation.
- days_in_portfolio
Total number of days there was a position in
the security in the portfolio over the entire simulation.
Method getInputStats()
Get input statistics.
Usage
Simulation$getInputStats()
Returns
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
Period to which statistics pertain.
- input_rows
Total number of rows of input data, including
rows carried forward from the previous period.
- cf_rows
Total number of rows carried forward from the previous
period.
- num_na_column
Number of NA values in column. This
measure appears for each element of track_metadata.
- cor_column
Period-over-period correlation for column.
This measure appears for each element of track_metadata.
Method getLooseningInfo()
Get loosening information.
Usage
Simulation$getLooseningInfo()
Returns
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
Date for which the constraint was loosened.
- constraint_name
Name of the constraint that was loosened.
- pct_loosened
Percentage by which the constraint was loosened,
where 100 means loosened fully (i.e., the constraint is effectively
removed).
Method getOptimizationSummary()
Get optimization summary information.
Usage
Simulation$getOptimizationSummary()
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date to which the data pertains.
- order_gmv
Total gross market value of orders generated by the
optimization.
- start_smv
Total net market value of short positions at the
start of the optimization.
- start_lmv
Total net market value of long positions at the
start of the optimization.
- end_smv
Total net market value of short positions at the end
of the optimization.
- end_lmv
Total net market value of long positions at the end of
the optimization.
- start_factor
Total net exposure to factor at the
start of the optimization, for each factor constraint.
- end_factor
Total net exposure to factor at the
start of the optimization, for each factor constraint.
Method getExposures()
Get end-of-period exposure information.
Usage
Simulation$getExposures(type = "net")
Arguments
typeVector of length 1 that may be one of "net",
"long", "short", and "gross".
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date of the exposure data.
- category_level
Exposure to level
within category, for all levels of all category constraints, at the end
of the period.
- factor
Exposure to factor, for all factor
constraints, at the end of the period.
Method getDelistings()
Get information on positions removed due to delisting.
Usage
Simulation$getDelistings()
Returns
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.
Method getSingleStrategySummaryDf()
Get summary information for a single strategy suitable for
plotting input.
Usage
Simulation$getSingleStrategySummaryDf(
strategy_name = "joint",
include_zero_row = TRUE
)
Arguments
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.
Returns
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.
Method plotPerformance()
Draw a plot of cumulative gross and net return by date.
Usage
Simulation$plotPerformance(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotContribution()
Draw a plot of contribution to net return on GMV for levels
of a specified category.
Usage
Simulation$plotContribution(category_var, strategy_name = "joint")
Arguments
category_varPlot performance contribution for the levels of
category_var. category_var must be present in the
simulation's security reference, and detail data must be present in the
object's result data.
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotMarketValue()
Draw a plot of total gross, long, short, and net market
value by date.
Usage
Simulation$plotMarketValue(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotCategoryExposure()
Draw a plot of exposure to all levels in a category by date.
Usage
Simulation$plotCategoryExposure(in_var, strategy_name = "joint")
Arguments
in_varCategory for which exposures are plotted. In order to plot
exposures for category in_var, we must have run the simulation
with in_var in the config setting
simulator/calculate_exposures/category_vars.
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotFactorExposure()
Draw a plot of exposure to factors by date.
Usage
Simulation$plotFactorExposure(in_var, strategy_name = "joint")
Arguments
in_varFactors for which exposures are plotted.
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotNumPositions()
Draw a plot of number of long and short positions by date.
Usage
Simulation$plotNumPositions(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotTurnover()
Draw a plot of number of long and short positions by date.
Usage
Simulation$plotTurnover(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method plotUniverseSize()
Draw a plot of the universe size, or number of investable
stocks, over time.
Usage
Simulation$plotUniverseSize(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to joint.
Method plotNonInvestablePct()
Draw a plot of the percentage of portfolio GMV held in
non-investable stocks (e.g., stocks that do not satisfy universe criteria)
for a given strategy. Note that this plot requires detail data.
Usage
Simulation$plotNonInvestablePct(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy
for the plot. Defaults to "joint".
Method overallStatsDf()
Calculate overall simulation summary statistics, such as
total P&L, Sharpe, average market values and counts, etc.
Usage
Simulation$overallStatsDf()
Returns
A data frame that contains summary statistics, suitable for
reporting.
Method overallReturnsByMonthDf()
Calculate return for each month and summary statistics for
each year, such as total return and annualized Sharpe. Return in data
frame format suitable for reporting.
Usage
Simulation$overallReturnsByMonthDf()
Returns
The data frame contains one row for each calendar year in the
simulation, and up to seventeen columns: one column for year, one
column for each calendar month, and columns for the year's total
return, annualized return, annualized volatility, and annualized
Sharpe. Total return is the sum of daily net returns. Annualized return
is the mean net return times 252. Annualized volatility is the standard
deviation of net return times the square root of 252. Annualized Sharpe
is the ratio of annualized return to annualized volatility. All returns
are in percent.
Method print()
Print overall simulation statistics.
Usage
Simulation$print()
Method writeFeather()
Write the data in the object to feather files.
Usage
Simulation$writeFeather(out_loc)
Arguments
out_locDirectory in which output files should be created.
Returns
No return value, called for side effects.
Method 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.
Usage
Simulation$readFeather(in_loc)
Arguments
in_locDirectory that contains files to be loaded.
Returns
No return value, called for side effects.
Method getConfig()
Get the object's configuration information.
Usage
Simulation$getConfig()
Returns
Object of class list that contains the simulation's
configuration information.
Method writeReport()
Write an html document of simulation results.
Usage
Simulation$writeReport(
out_dir,
out_file,
out_fmt = "html",
contrib_vars = NULL
)
Arguments
out_dirDirectory in which output files should be created
out_fileFile name for output
out_fmtFormat in which output files should be created. The
default is html and that is currently the only option.
contrib_varsSecurity reference variables for which to plot return
contribution.
resThe object of class 'Simulation' which we want to write the
report about.
Method clone()
The objects of this class are cloneable with this method.
Usage
Simulation$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
strand documentation built on Nov. 20, 2020, 1:08 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Description
Class for running a simulation and getting results.
Details
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.
Methods
Public methods
Method new()
Create a new Simulation object.
Usage
Simulation$new( config = NULL, raw_input_data = NULL, input_dates = NULL, raw_pricing_data = NULL, security_reference_data = NULL, delisting_data = NULL )
Arguments
configAn object of class
listorcharacter, orNULL. 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 callingyaml.load_fileon the configuration file). If the value passed isNULL, then there will be no configuration information associated with the simulation and it will not possible to call therunmethod. Settingconfig = NULLis useful when creating simulation objects into which results will be loaded withreadFeather.raw_input_dataA data frame that contains all of the input data (for all periods) for the simulation. The data frame must have a
datecolumn. Data supplied using this parameter will be used if the configuration optionsimulator/input_data/typeis set toobject. Defaults toNULL.input_datesVector of class
Datethat specifies when input data should be updated. If data is being supplied using theraw_input_dataparameter, theninput_datesdefaults to set of dates present in this data.raw_pricing_dataA data frame that contains all of the input data (for all periods) for the simulation. The data frame must have a
datecolumn. Data supplied using this parameter will only be used if the configuration optionsimulator/pricing_data/typeis set toobject. Defaults toNULL.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/typeis set toobject. Defaults toNULL.delisting_dataA data frame that contains delisting dates and associated returns. It must contain three columns: id (character), delisting_date (Date), and delisting_return (numeric). The date in the delisting_date column means the day on which a stock will be removed from the simulation portfolio. It is typically the day after the last day of trading. The delisting_return column reflects what, if any, P&L should be recorded on the delisting date. A delisting_return of -1 means that the shares were deemed worthless. The delisting return is multiplied by the starting net market value of the position to determine P&L for the delisted position on the delisting date. Note that the portfolio optimization does not include stocks that are being removed due to delisting. Data supplied using this parameter will only be used if the configuration option
simulator/delisting_data/typeis set toobject. Defaults toNULL.
Returns
A new Simulation object.
Method setVerbose()
Set the verbose flag to control info output.
Usage
Simulation$setVerbose(verbose)
Arguments
verboseLogical flag indicating whether to be verbose or not.
Returns
No return value, called for side effects.
Method setShinyCallback()
Set the callback function for updating progress when running a simulation in shiny.
Usage
Simulation$setShinyCallback(callback)
Arguments
callbackA function suitable for updating a shiny Progress object. It must have two parameters:
value, indicating the progress amount, and detail, anddetail, a text string for display on the progress bar.
Returns
No return value, called for side effects.
Method getSecurityReference()
Get security reference information.
Usage
Simulation$getSecurityReference()
Returns
An object of class data.frame that contains the security
reference data for the simulation.
Method run()
Run the simulation.
Usage
Simulation$run()
Returns
No return value, called for side effects.
Method getSimDates()
Get a list of all date for the simulation.
Usage
Simulation$getSimDates()
Returns
A vector of class Date over which the simulation currently iterates: all
weekdays between the 'from' and 'to' dates in the simulation's config.
Method getSimSummary()
Get summary information.
Usage
Simulation$getSimSummary(strategy_name = NULL)
Arguments
strategy_nameCharacter vector of length 1 that specifies the strategy for which to get detail data. If
NULLdata for all strategies is returned. Defaults toNULL.
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date of the summary data.
- market_fill_nmv
Total net market value of fills that do not net down across strategies.
- transfer_fill_nmv
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.
- market_order_gmv
Total gross market value of orders that do not net down across strategies.
- market_fill_gmv
Total gross market value of fills that do not net down across strategies.
- transfer_fill_gmv
Total gross market value of fills that represent "internal transfers", i.e., fills in one strategy that net down with fills in another.
- start_nmv
Total net market value of all positions at the start of the period.
- start_lmv
Total net market value of all long positions at the start of the period.
- start_smv
Total net market value of all short positions at the start of the period.
- end_nmv
Total net market value of all positions at the end of the period.
- end_gmv
Total gross market value of all positions at the end of the period.
- end_lmv
Total net market value of all long positions at the end of the period.
- end_smv
Total net market value of all short positions at the end of the period.
- end_num
Total number of positions at the end of the period.
- end_num_long
Total number of long positions at the end of the period.
- end_num_short
Total number of short positions at the end of the period.
- position_pnl
The total difference between the end and start market value of positions.
- trading_pnl
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.
- gross_pnl
Total P&L gross of costs, calculated as position_pnl + trading_pnl.
- trade_costs
Total trade costs (slippage).
- financing_costs
Total financing/borrow costs.
- net_pnl
Total P&L net of costs, calculated as gross_pnl - trade_costs - financing_costs.
- fill_rate_pct
Total fill rate across all market orders, calculated as 100 * market_fill_gmv / market_order_gmv.
- num_investable
Number of investable securities (size of universe).
Method getSimDetail()
Get detail information.
Usage
Simulation$getSimDetail( sim_date = NULL, strategy_name = NULL, security_id = NULL, columns = NULL )
Arguments
sim_dateVector of length 1 of class Date or character that specifies the period for which to get detail information. If
NULLthen data from all periods is returned. Defaults toNULL.strategy_nameCharacter vector of length 1 that specifies the strategy for which to get detail data. If
NULLdata for all strategies is returned. Defaults toNULL.security_idCharacter vector of length 1 that specifies the security for which to get detail data. If
NULLdata for all securities is returned. Defaults toNULL.columnsVector of class character specifying the columns to return. This parameter can be useful when dealing with very large detail datasets.
Returns
An object of class data.frame that contains security-level
detail data for the simulation for the desired strategies, securities,
dates, and columns. Available columns include:
- id
Security identifier.
- strategy
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date to which the data pertains.
- shares
Shares at the start of the period.
- int_shares
Shares at the start of the period that net down with positions in other strategies.
- ext_shares
Shares at the start of the period that do not net down with positions in other strategies.
- order_shares
Order, in shares.
- market_order_shares
Order that does not net down with orders in other strategies, in shares.
- transfer_order_shares
Order that nets down with orders in other strategies, in shares.
- fill_shares
Fill, in shares.
- market_fill_shares
Fill that does not net down with fills in other strategies, in shares.
- transfer_fill_shares
Fill that nets down with fills in other strategies, in shares.
- end_shares
Shares at the end of the period.
- end_int_shares
Shares at the end of the period that net down with positions in other strategies.
- end_ext_shares
Shares at the end of the period that do not net down with positions in other strategies.
- start_price
Price for the security at the beginning of the period.
- end_price
Price for the security at the end of the period.
- dividend
Dividend for the security, if any, for the period.
- distribution
Distribution (e.g., spin-off) for the security, if any, for the period.
- investable
Logical indicating whether the security is part of the investable universe. The value of the flag is set to TRUE if the security has not been delisted and satisfies the universe criterion provided (if any) in the
simulator/universeconfiguration option.- delisting
Logical indicating whether a position in the security was removed due to delisting. If delisting is set to TRUE, the gross_pnl and net_pnl columns will contain the P&L due to delisting, if any. P&L due to delisting is calculated as the delisting return times the
start_nmvof the position.- position_pnl
Position P&L, calculated as shares * (end_price + dividend + distribution - start_price)
- trading_pnl
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
Trade costs, calculated as a fixed percentage (set in the simulation configuration) of the notional of the market trade (valued at the close).
- financing_costs
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_pnl
Gross P&L, calculated as position_pnl + trading_pnl.
- net_pnl
Net P&L, calculated as gross_pnl - trade_costs - financing_costs.
- market_order_nmv
Net market value of the order that does not net down with orders in other strategies.
- market_fill_gmv
Gross market value of the order that does not net down with orders in other strategies.
- market_fill_nmv
Net market value of the fill that does not net down with orders in other strategies.
- market_fill_gmv
Gross market value of the fill that does not net down with orders in other strategies.
- transfer_fill_nmv
Net market value of the fill that nets down with fills in other strategies.
- transfer_fill_gmv
Gross market value of the fill that nets down with fills in other strategies.
- start_nmv
Net market value of the position at the start of the period.
- end_nmv
Net market value of the position at the end of the period.
- end_gmv
Gross market value of the position at the end of the period.
Method 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.
Usage
Simulation$getPositionSummary(strategy_name = NULL)
Arguments
strategy_nameCharacter vector of length 1 that specifies the strategy for which to get detail data. If
NULLdata for all strategies is returned. Defaults toNULL.
Returns
An object of class data.frame that contains summary
information aggregated by security. The data frame contains the
following columns:
- id
Security identifier.
- strategy
Strategy name, or 'joint' for the aggregate strategy.
- gross_pnl
Gross P&L for the position over the entire simulation.
- gross_pnl
Net P&L for the position over the entire simulation.
- average_market_value
Average net market value of the position over days in the simulation where the position was not flat.
- total_trading
Total gross market value of trades for the security.
- trade_costs
Total cost of trades for the security over the entire simulation.
- trade_costs
Total cost of financing for the position over the entire simulation.
- days_in_portfolio
Total number of days there was a position in the security in the portfolio over the entire simulation.
Method getInputStats()
Get input statistics.
Usage
Simulation$getInputStats()
Returns
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
Period to which statistics pertain.
- input_rows
Total number of rows of input data, including rows carried forward from the previous period.
- cf_rows
Total number of rows carried forward from the previous period.
- num_na_column
Number of NA values in column. This measure appears for each element of
track_metadata.- cor_column
Period-over-period correlation for column. This measure appears for each element of
track_metadata.
Method getLooseningInfo()
Get loosening information.
Usage
Simulation$getLooseningInfo()
Returns
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
Date for which the constraint was loosened.
- constraint_name
Name of the constraint that was loosened.
- pct_loosened
Percentage by which the constraint was loosened, where 100 means loosened fully (i.e., the constraint is effectively removed).
Method getOptimizationSummary()
Get optimization summary information.
Usage
Simulation$getOptimizationSummary()
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date to which the data pertains.
- order_gmv
Total gross market value of orders generated by the optimization.
- start_smv
Total net market value of short positions at the start of the optimization.
- start_lmv
Total net market value of long positions at the start of the optimization.
- end_smv
Total net market value of short positions at the end of the optimization.
- end_lmv
Total net market value of long positions at the end of the optimization.
- start_factor
Total net exposure to factor at the start of the optimization, for each factor constraint.
- end_factor
Total net exposure to factor at the start of the optimization, for each factor constraint.
Method getExposures()
Get end-of-period exposure information.
Usage
Simulation$getExposures(type = "net")
Arguments
typeVector of length 1 that may be one of
"net","long","short", and"gross".
Returns
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
Strategy name, or 'joint' for the aggregate strategy.
- sim_date
Date of the exposure data.
- category_level
Exposure to level within category, for all levels of all category constraints, at the end of the period.
- factor
Exposure to factor, for all factor constraints, at the end of the period.
Method getDelistings()
Get information on positions removed due to delisting.
Usage
Simulation$getDelistings()
Returns
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.
Method getSingleStrategySummaryDf()
Get summary information for a single strategy suitable for plotting input.
Usage
Simulation$getSingleStrategySummaryDf( strategy_name = "joint", include_zero_row = TRUE )
Arguments
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.
Returns
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.
Method plotPerformance()
Draw a plot of cumulative gross and net return by date.
Usage
Simulation$plotPerformance(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotContribution()
Draw a plot of contribution to net return on GMV for levels of a specified category.
Usage
Simulation$plotContribution(category_var, strategy_name = "joint")
Arguments
category_varPlot performance contribution for the levels of
category_var.category_varmust be present in the simulation's security reference, and detail data must be present in the object's result data.strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotMarketValue()
Draw a plot of total gross, long, short, and net market value by date.
Usage
Simulation$plotMarketValue(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotCategoryExposure()
Draw a plot of exposure to all levels in a category by date.
Usage
Simulation$plotCategoryExposure(in_var, strategy_name = "joint")
Arguments
in_varCategory for which exposures are plotted. In order to plot exposures for category
in_var, we must have run the simulation within_varin the config settingsimulator/calculate_exposures/category_vars.strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotFactorExposure()
Draw a plot of exposure to factors by date.
Usage
Simulation$plotFactorExposure(in_var, strategy_name = "joint")
Arguments
in_varFactors for which exposures are plotted.
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotNumPositions()
Draw a plot of number of long and short positions by date.
Usage
Simulation$plotNumPositions(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotTurnover()
Draw a plot of number of long and short positions by date.
Usage
Simulation$plotTurnover(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method plotUniverseSize()
Draw a plot of the universe size, or number of investable stocks, over time.
Usage
Simulation$plotUniverseSize(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
joint.
Method plotNonInvestablePct()
Draw a plot of the percentage of portfolio GMV held in non-investable stocks (e.g., stocks that do not satisfy universe criteria) for a given strategy. Note that this plot requires detail data.
Usage
Simulation$plotNonInvestablePct(strategy_name = "joint")
Arguments
strategy_nameCharacter vector of length 1 specifying the strategy for the plot. Defaults to
"joint".
Method overallStatsDf()
Calculate overall simulation summary statistics, such as total P&L, Sharpe, average market values and counts, etc.
Usage
Simulation$overallStatsDf()
Returns
A data frame that contains summary statistics, suitable for reporting.
Method overallReturnsByMonthDf()
Calculate return for each month and summary statistics for each year, such as total return and annualized Sharpe. Return in data frame format suitable for reporting.
Usage
Simulation$overallReturnsByMonthDf()
Returns
The data frame contains one row for each calendar year in the simulation, and up to seventeen columns: one column for year, one column for each calendar month, and columns for the year's total return, annualized return, annualized volatility, and annualized Sharpe. Total return is the sum of daily net returns. Annualized return is the mean net return times 252. Annualized volatility is the standard deviation of net return times the square root of 252. Annualized Sharpe is the ratio of annualized return to annualized volatility. All returns are in percent.
Method print()
Print overall simulation statistics.
Usage
Simulation$print()
Method writeFeather()
Write the data in the object to feather files.
Usage
Simulation$writeFeather(out_loc)
Arguments
out_locDirectory in which output files should be created.
Returns
No return value, called for side effects.
Method 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.
Usage
Simulation$readFeather(in_loc)
Arguments
in_locDirectory that contains files to be loaded.
Returns
No return value, called for side effects.
Method getConfig()
Get the object's configuration information.
Usage
Simulation$getConfig()
Returns
Object of class list that contains the simulation's
configuration information.
Method writeReport()
Write an html document of simulation results.
Usage
Simulation$writeReport( out_dir, out_file, out_fmt = "html", contrib_vars = NULL )
Arguments
out_dirDirectory in which output files should be created
out_fileFile name for output
out_fmtFormat in which output files should be created. The default is html and that is currently the only option.
contrib_varsSecurity reference variables for which to plot return contribution.
resThe object of class 'Simulation' which we want to write the report about.
Method clone()
The objects of this class are cloneable with this method.
Usage
Simulation$clone(deep = FALSE)
Arguments
deepWhether to make a deep clone.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.