[Blotter-commits] r737 - pkg/quantstrat/R
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Aug 24 23:07:11 CEST 2011
Author: cyrforge
Date: 2011-08-24 23:07:11 +0200 (Wed, 24 Aug 2011)
New Revision: 737
Modified:
pkg/quantstrat/R/parameters.R
Log:
Added/ changed more roxygen documentation comments.
Modified: pkg/quantstrat/R/parameters.R
===================================================================
--- pkg/quantstrat/R/parameters.R 2011-08-24 04:22:02 UTC (rev 736)
+++ pkg/quantstrat/R/parameters.R 2011-08-24 21:07:11 UTC (rev 737)
@@ -125,21 +125,21 @@
#' Extract the parameter structure from a strategy object.
#'
-#' This function is not required for user to specify the distribution of parameters,
#' Users can use this function to extract the parameters used in a strategy, and as a reminder/ cheatsheet
-#' when they create the parameter distribution.
+#' when they create the parameter distribution. But it's not required to be used to specify the distribution of parameters.
#'
-#' Example:
+#' @examples
#' When strategy object stratMACD has already been created by macd.R demo:
#' following line will return the parameter information to object paramStructure:
#'
#' x<-getParameterTable(stratMACD)
#'
-#' In the returned list x:
+#' @return
+#' In the returned list of object:
#'
-#' x$paramNameList is the list of parameters used in the strategy, easy for print and view as a table.
-#' x$strategyName is the name of the strategy itself.
-#' x$structure is the detailed paramter structure in the input strategy, can be used when user wants to look into more details of the parameter structure.
+#' paramNameList is the list of parameters used in the strategy, easy for print and view as a table.
+#' strategyName is the name of the strategy itself.
+#' structure is the detailed paramter structure in the input strategy, can be used when user wants to look into more details of the parameter structure.
#'
#' @param strategy The strategy object.
#' @returnType A list of objects that contains the parameter structure information, see detail.
@@ -246,10 +246,13 @@
#' The parameter of the function 'distribution' is a list contains vector of values named WITH THE NAME OF THE PARAMETER, the values can be any type (integer, characters, etc) matches with the leagal value of that parameter.
#' For example: distribution=list(nFast=(10:30)) or distribution=list(relationship=c('gt','gte'))
#'
-#' Example: (For complete demo see parameterTestMACD.R)
+#' @examples
+#' \dontrun{
+#' #(For complete demo see parameterTestMACD.R)
#' tPD2<-setParameterDistribution(tPD2,'indicator',indexnum=1,distribution=list(nFast=(10:30)),label='nFast')
#' tPD2<-setParameterDistribution(tPD2,'indicator',indexnum=1,distribution=list(nSlow=(20:40)),label='nSlow')
#' tPD2<-setParameterDistribution(tPD2,'signal',indexnum=1,distribution=list(relationship=c('gt','gte')),label='sig1.gtgte')
+#' }
#'
#' @param paramDist The object that store the parameter list, if this parameter is missing, or object does not exist, the function will create a new object.
#' @param type A character string that specifies the type of the parameter, it takes the value of one of 'indicator', 'signal', 'enter', 'exit', 'order'.
@@ -257,8 +260,7 @@
#' @param distribution Distribution of the parameter, can be any function that return a vector of value. See detail. (A numerical example: 1:10 or sample(1:20,6)
#' @param weight The weight of each value in the distribution, default value will be all equally weighted.
#' @param psindex specify the index within the parameter distribution object, it is used to make change/ repalce a parameter distribution in the object.
-#' @returnType The returned object is a structure contains the distribution of parameters, is of the same type as the input parameter paramDist (if provided), the function update the input paramDist object and return the updated one. Usually the returned value is pass to the same object as parameter. See details.
-#' @return .
+#' @return The returned object is a structure contains the distribution of parameters, is of the same type as the input parameter paramDist (if provided), the function update the input paramDist object and return the updated one. Usually the returned value is pass to the same object as parameter. See details.
#' @author Yu Chen
#' @export
setParameterDistribution<-function(paramDist=NULL,type=NULL,indexnum=0,distribution=NULL,weight,label,psindex=NULL){#All is needed, set to illegal values
@@ -296,25 +298,21 @@
return(paramDist)
}
-#' Generate parameter sets based on specified distribution and constrains, apply the parameters to the specified strategy and return the results package.
+#' Generate parameter sets for a specific strategy, test the strategy on each set of parameters, output result package.
#'
-#' Given a parameter distribution object generated by setParameterDistribution function,
-#' generate parameter sets and test each set on the specified strategy.
+#' Generate parameter sets based on specified distribution (a defined parameter distribution object generated by setParameterDistribution function) and constraints (A defined parameter constraint object generated by setParameterConstraint function),
+#' apply the generated parameter sets to the specified strategy and return the results package, put the generated portfolio objects and account objects in .blotter environment.
#'
-#' The function support parallel execution, user only need to initial the parallel package and wrap up afterwards.
-#' The function will automaticly use the number of registered parallel sessions to run testing.
-#'
-#'
-#' Other than returned value, the function puts portfolio and account objects in the .blotter environment.
+#' Other than the returned result pack, the function puts the generated portfolio and account objects in the .blotter environment.
#' The names of those objects will be extension of the names created by initial strategy/portfolios are created.
-#' For example, in macd.R demo, account.macd and portfolio.macd are created in .blotter environment. After calling the function and did the
-#' parameter test, series of similar objects are created with names
+#' For example, in macd.R demo, account.macd and portfolio.macd are created in .blotter environment. After calling the applyParameter function and did the
+#' parameter test, series of similar objects are created with names account.macd.p.1, account.macd.p.2 ... and portfolio.macd.p.1, portfolio.macd.p.2 ...
#'
-#' account.macd.p.1, account.macd.p.2 ... and
-#' portfolio.macd.p.1, portfolio.macd.p.2 ...
-#'
+#' The function supports parallel execution, user only need to initial the parallel package and wrap up afterwards.
+#' The function will automaticly use the number of registered parallel sessions to run testing, See example.
+#'
#' @return
-#' In the returned Object:
+#' In the returned result pack as a list of object:
#'
#' \describe{
#' \item{statsTable}{is the summary table show stats from all the runs}
@@ -322,7 +320,7 @@
#' \item{paramTable}{is parameter samples used, in a table for print}
#' \item{paramConstrainTable}{is the constraints apply to the parameters, in a table for print}
#' \item{parameterDistribution}{is the parameter distribution passed in as argument}
-#' \item{parameterConstrains}{is the constraints apply to the parameters, passed in as argument}
+#' \item{parameterConstraints}{is the constraints apply to the parameters, passed in as argument}
#' }
#' @examples
#' \dontrun{
@@ -332,25 +330,29 @@
#' registerDoSMP(workers)
#'
#' #PUT ALL CODE RELATED TO QUANTSTRAT HERE
-#' #Example to call the function: (For complete demo see parameterTestMACD.R)
-#' x<-applyParameter(strategy=stratMACD,portfolios=portfolio.st,parameterPool=tPD2,
-#' method='random',sampleSize=20,parameterConstrains=pConstraint2)
-#' #or
-#' x<-applyParameter(strategy=stratMACD,portfolios=portfolio.st,parameterPool=tPD2,
-#' method='expand',parameterConstrains=pConstraint2)
+#' #Example to call the function: (For complete demo see parameterTestMACD.R)
+#' x<-applyParameter(strategy=stratMACD,portfolios=portfolio.st,parameterPool=tPD2,
+#' method='random',sampleSize=20,parameterConstraints=pConstraint2)
+#' #or
+#' x<-applyParameter(strategy=stratMACD,portfolios=portfolio.st,parameterPool=tPD2,
+#' method='expand',parameterConstraints=pConstraint2)
#'
#' stopWorkers(workers)
#' rmSessions(all=TRUE)
#' }
+#'
#' @param strategy The strategy to test paramters to.
#' @param portfolios The character name of the portfolios to apply to.
#' @param parameterPool The object that created by setParameterDistribution function, which includes all the parameter legal values and distribution/weights.
-#' @param parameterConstrains The object created by setParameterConstraint function that specifies the constrains between each parameters,
+#' @param parameterConstraints The object created by setParameterConstraint function that specifies the constrains between each parameters,
#' @param method Takes string 'expand' or 'random', specify how to generate samples of parameters. 'expand' will do all possible combinations of the parameter sets,
#' @param sampleSize Used when method=='random', specify how many parameter sets to generate and run test of.
+#'
+#' @seealso \code{\link{setParameterDistribution}}, \code{\link{setParameterConstraint}}
+#'
#' @author Yu Chen
#' @export
-applyParameter<-function(strategy,portfolios,parameterPool,parameterConstrains,method,sampleSize){
+applyParameter<-function(strategy,portfolios,parameterPool,parameterConstraints,method,sampleSize){
#need to create combination of distribution values in each slot of the parameterPool
initialPortf<-getPortfolio(portfolios)
@@ -435,12 +437,12 @@
names(tparamTable)<-names(paramdist)
# put constraint test on tparamTable, before rbind
- for (k in 1:length(parameterConstrains))
+ for (k in 1:length(parameterConstraints))
{
- constrintfill<-paramConstraint(label=parameterConstrains[[k]]$constraintLabel,
+ constrintfill<-paramConstraint(label=parameterConstraints[[k]]$constraintLabel,
data=tparamTable,
- columns=merge(paramLabel,data.frame(parameterConstrains[[k]]$paramList),by="label")$varName, #has to keep the order.
- relationship=parameterConstrains[[k]]$relationship)
+ columns=merge(paramLabel,data.frame(parameterConstraints[[k]]$paramList),by="label")$varName, #has to keep the order.
+ relationship=parameterConstraints[[k]]$relationship)
#only keep the samples fulfill the constraints.
@@ -684,10 +686,10 @@
testPackListPRLStructure$eachRun<-testPackListPRL
testPackListPRLStructure$paramTable<-paramTable
- testPackListPRLStructure$paramConstrainTable<-data.frame(parameterConstrains)
+ testPackListPRLStructure$paramConstrainTable<-data.frame(parameterConstraints)
testPackListPRLStructure$parameterDistribution<-parameterPool
- testPackListPRLStructure$parameterConstrains<-parameterConstrains
+ testPackListPRLStructure$parameterConstraints<-parameterConstraints
return(testPackListPRLStructure)
@@ -698,7 +700,7 @@
#}
-#' Basicly is the same as sigComparison function in signal.R written by Brian, with miner change.
+#' Internal function used in applyParameter function for process constraints on relationship between two parameter values. Basicly is the same as sigComparison function in signal.R written by Brian, with miner change.
#'
#' Currently, this function compares two columns.
#' Patches to compare an arbitrary number of columns would be gladly accepted.
@@ -754,13 +756,13 @@
#' Function to construct parameter constraint object.
#'
-#'
-#' Example: (For complete demo see parameterTestMACD.R)
-#' In a MACD strategy, we want to fast macd calcuated from less time periods (days) than slow macd signal:
+#' @examples
+#' (For complete demo see parameterTestMACD.R)
+#' #In a MACD strategy, we want to fast macd calcuated from less time periods (days) than slow macd signal:
#'
#' pConstraint2<-setParameterConstraint(constraintLabel='macdPC',paramList=c('nFast','nSlow'),relationship='lt')
#'
-#' The object pConstraint2 then can be used in applyParameter function to specify the constrains between parameters.
+#' #The object pConstraint2 then can be used in applyParameter function to specify the constrains between parameters.
#'
#' @param paramConstraintObj the ParameterConstraint object to be updated on, if missing, funtion will create a new one.
#' @param constrainlabel User can give a character label to the constraint.
More information about the Blotter-commits
mailing list