backtest              package:backtest              R Documentation

_C_r_e_a_t_i_n_g _a_n _O_b_j_e_c_t _o_f _C_l_a_s_s _B_a_c_k_t_e_s_t

_D_e_s_c_r_i_p_t_i_o_n:

     Conducts a backtest and returns the results as an object of class
     'backtest'.

_U_s_a_g_e:

     backtest(x,
              in.var,
              ret.var,
              universe,
              by.var    = NULL,
              date.var  = NULL,
              id.var    = NULL,
              buckets   = 5,
              natural   = FALSE,
              do.spread = TRUE,
              by.period = TRUE,
              overlaps  = 1)

_A_r_g_u_m_e_n_t_s:

       x: A data frame containing the data to be analysed in the
          backtest.  The details of what this data frame must contain
          are given below.

  in.var: A character vector which indicates the name of the column or
          columns in 'x' to be used as input variables.

 ret.var: A character vector which indicates the name of the column or
          columns in 'x' to be used as return variables.

  by.var: An optional character value, specifying a second variable in
          'x' to be used for categorising the data.  The details of how
          categories are created are given below.

  id.var: An optional character value which indicates the name of the
          column in 'x' containing a unique identifier for each
          observation.  'id.var' must be specified if 'natural' is
          TRUE.

date.var: An optional character vector which indicates the name of the
          column in 'x' to be used as a date for each observation.
          'date.var' must be specified if 'natural' is TRUE.  In order
          to call 'plot', the contents of 'date.var' must be of class
          'Date' or be coercible to an object of class 'Date' via
          'as.Date'.

 buckets: An optional numeric vector which specifies how many quantiles
          to create according to 'in.var' and 'by.var'.

universe: An optional expression for selecting a subset of 'x'. The
          details of how this expression may be constructed are given
          below. 

 natural: An optional logical value.  If TRUE, the 'summary' method
          returns additional information and the backtest object may be
          plotted.  The details of how a natural backtest differs from
          a pooled backtest are given below. 

do.spread: An optional logical value. If TRUE the 'summary' method
          displays information about the spread between the extreme
          quantiles.  If FALSE this information is suppressed. 
          Defaults to TRUE. 

by.period: An optional logical value. If TRUE the quantiles are
          recalculated within each date period.  If FALSE the quantiles
          are calculated all at once.  Defaults to TRUE. 

overlaps: An optional integer which specifies how many periods to
          combine portfolios of in order to weight a current period. 
          If 'overlaps' is the default of 1, backtest behaves as normal
          and only uses a periods own data to determine the portfolio. 
          If 'overlaps' is set to n > 1, a period's portfolio is
          calculated by giving 1/n weight to the previous n periods. 

_D_e_t_a_i_l_s:

     Data frames for 'backtest' must, at a minimum, contain a column of
     class numeric to be referenced by the 'in.var' and 'ret.var'
     arguments.  

     The 'in.var' is the primary variable by which the backtest
     categorises observations.  It must reference a numeric column in
     'x'.  Using the values in 'x', 'backtest' breaks the values into
     equal sized quantiles, or 'buckets'.

     The 'by.var' is the secondary variable by which the backtest
     categorises observations.  When specifying both 'in.var' and
     'by.var', 'backtest' organises the observations into a 'n' by 'j'
     matrix where 'n' is the number of quantiles or categories created
     for the 'by.var' and 'j' is the number of quantiles created for
     the 'in.var'.  By default, 'backtest' creates 5 quantiles.

     If 'natural' is TRUE, the data and arguments must meet certain
     requirements.  First, the frequency of the observations and
     'ret.var' must be the same.  Second, an 'id.var' and 'date.var'
     are required.  Third, a 'by.var' is not allowed.  Note that the
     code does not verify that the backtest is truly natural;
     'backtest' accepts the value passed by the user as valid.

_V_a_l_u_e:

     Returns an object of class 'backtest'.

     The functions 'show' and 'summary' are used to obtain and print a
     short description and longer summary of the results of the
     'backtest'.  The accessor functions 'counts', 'marginals', 'mean',
     'naCounts', and 'turnover' extract different parts of the value
     returned by 'backtest'.

_A_u_t_h_o_r(_s):

     Kyle Campbell kyle.w.campbell@williams.edu and Jeff Enos
     jeff@kanecap.com

_S_e_e _A_l_s_o:

     'backtest-class'

_E_x_a_m_p_l_e_s:

     data(starmine)

     ## Backtest with 1 'in.var' and 1 'ret.var'

     bt <- backtest(starmine, in.var = "smi", ret.var = "fwd.ret.1m", by.period = FALSE)
     summary(bt)

     ## Backtest with 2 'in.var' values, 1 'ret.var', and a 'by.var'

     bt <- backtest(starmine, in.var = c("smi", "cap.usd"),
                    ret.var = "fwd.ret.1m", by.var = "sector", by.period = FALSE)
     summary(bt)

     ## Backtest with 1 'in.var', 1 'by.var', and 1 'ret.var'.  Number of
     ## buckets changed from default of 5 to 4.  Change in number of buckets
     ## only affects the 'in.var' because the 'by.var' column in 'starmine'
     ## contains character data. For each value in this column there is a
     ## unique category.

     bt <- backtest(starmine, in.var = "smi", by.var = "sector",
                    ret.var = "fwd.ret.1m", buckets = 4, by.period = FALSE)
     summary(bt)

     ## Backtest with 1 'in.var', multiple 'ret.var', and a
     ## universe restriction

     bt <- backtest(starmine, in.var = "smi",
                    ret.var = c("fwd.ret.1m", "fwd.ret.6m"),
                    universe = sector == "HiTec", by.period = FALSE)
     summary(bt)

     ## Running a natural backtest with 2 'in.vars', 1 'ret.var'
     ## 10 buckets

     bt <- backtest(starmine, in.var = c("smi","cap.usd"),
                    ret.var = "fwd.ret.1m", date.var = "date",
                    id.var = "id", buckets = 10,
                    natural = TRUE, by.period = FALSE)
     summary(bt)

     ## The same backtest, but calculating quantiles within periods.

     bt <- backtest(starmine, in.var = c("smi","cap.usd"),
                    ret.var = "fwd.ret.1m", date.var = "date",
                    id.var = "id", buckets = 10,
                    natural = TRUE, by.period = TRUE)
     summary(bt)

     plot(bt, type = "turnover")
     plot(bt, type = "return")
     plot(bt, type = "cumreturn")
     plot(bt, type = "cumreturn.split")

