trade.optimizer {PortfolioProbe} | R Documentation

## Select an Optimal Trade for a Portfolio

### Description

Finds an approximately optimal portfolio trade. The required inputs are the prices, and a sufficient indication of the monetary size of the portfolio or the turnover. Typically a variance matrix and possibly a vector of expected returns are given as well. Almost always only integer values are traded, thus round lotting is automatically done if the prices are given for lots. Other constraints include the number of assets traded, and the number of assets in the optimal portfolio.

### Usage

    trade.optimizer(prices, variance=NULL, expected.return=NULL,
    	existing=NULL, gross.value=NULL, net.value=NULL, long.value=NULL,
    	short.value=NULL, turnover=NULL, long.only=FALSE, max.weight=1,
    	min.weight.thresh=NULL, universe.trade=NULL, lower.trade=NULL,
    	upper.trade=NULL, risk.fraction=NULL, rf.style="fraction",
    	rf.loc=NULL, ntrade=NULL, port.size=NULL, threshold=NULL,
    	forced.trade=NULL, positions=NULL, tol.positions=0,
    	lin.constraints=NULL, lin.bounds=NULL, lin.trade=FALSE,
    	lin.abs=TRUE, lin.style="weight", lin.direction=0,
            lin.rfloc=NULL, alpha.constraint=NULL, var.constraint=NULL,
    	bench.constraint=NULL, dist.center=NULL, dist.style="weight",
    	dist.bounds=NULL, dist.trade=FALSE, dist.utility=FALSE,
    	dist.prices=NULL, sum.weight=NULL, limit.cost=NULL, close.number=NULL,
            utility=NULL, risk.aversion=1, benchmark=NULL, bench.trade=FALSE,
    	bench.weights=NULL, long.buy.cost=NULL,
    	long.sell.cost=long.buy.cost, short.buy.cost=long.buy.cost,
    	short.sell.cost=long.buy.cost, cost.par=NULL, ucost=1,
    	scale.cost="gross", start.sol=NULL, allowance=.9999, do.warn=NULL,
            penalty.constraint=1000, quantile=0.5, dest.wt=NULL,
    	utable=NULL, atable=NULL, vtable=NULL, dumpfile="", ...,
            seed=.standard.seed.BurSt, control=trade.optimizer.control,
    	identity=NULL)

### Arguments

`prices` | required. Named vector of prices of the assets. This vector determines the assets to be used in the problem – other inputs such as `variance` and `expected.return` may contain information on assets in addition to the ones in `prices`. If there is one or more benchmarks, then these assets do not need to be in `prices`. (But if benchmark trading is allowed, the benchmarks do need to be in `prices`.)
`variance` | numeric matrix or three-dimensional array. This may have assets in addition to those named in `prices` – such assets will be ignored (except for benchmarks). If a three-dimensional array, then each variance matrix is in a different slice of the third dimension. Benchmarks do not need to be given in the variance when their weights (of assets in the variance) are given in `bench.weights`. Alternatively, compact forms of variances may be given via a list with special components (see the User's Manual) – this is very seldom useful.
`expected.return` | numeric vector or matrix of expected returns of the assets. If a matrix, then each vector of expected returns is in a different column. This need not have (row) names, but it is generally advised. If it does have asset names, then it can contain information for assets in addition to those in `prices`.
`existing` | named vector of units (shares or lots) of the existing portfolio. The `prices` vector must contain all of the assets in `existing`. If this is the result of a call to `trade.optimizer` – that is, an object of mode `portfolBurSt` – then the `new.portfolio` component is used as the vector. A random portfolio object containing a single portfolio is also allowed. If not given, then it is presumed there is no existing portfolio (only cash). `start.sol` (suggested trade for the optimizer) is sometimes confused with `existing` (initial portfolio). Don't confuse them.
`gross.value` | numeric vector of length one or two giving the desired gross value of the optimal portfolio. If of length two, this is a range of values that are allowed. If of length one, then the lower bound is created by multiplying by `allowance`. There is more on this argument in the Details section.
`net.value` | numeric vector of length two (or possibly one) giving the range that the net value may have. There is more on this argument in the Details section.
`long.value` | numeric vector of length one or two giving the desired sum of the values of the long positions of the optimal portfolio. If of length two, this is a range of values that are allowed. If of length one, then the lower bound is created by multiplying by `allowance`. There is more on this argument in the Details section.
`short.value` | numeric vector of length one or two giving the desired sum of the value of the short positions of the optimal portfolio. If of length two, this is a range of values that are allowed. If of length one, then the lower bound is created by multiplying by `allowance`. (This is meant to be positive numbers, but negative numbers work as well.) There is more on this argument in the Details section.
`turnover` | numeric vector of length one or two giving the desired sum of the absolute value of all the trades. If of length one, then the maximum turnover; otherwise the range of allowable trade values. There is more on this argument in the Details section.
`long.only` | logical value stating if the optimal portfolio is restricted to be long-only (no negative numbers of units of assets).
`max.weight` | a numeric vector containing numbers between zero and one giving the maximum weight allowed in the gross value for the assets. If this is an unnamed vector, then it is replicated to have length equal to the number of assets. If named, then it bounds those specified assets. `NULL` is (grudgingly) allowed to mean no maximum weight constraints.
`min.weight.thresh` | a single numeric value giving the minimum weight for any asset in a long-only portfolio. This is ignored for long-short portfolios – you need to use `threshold` or `positions` instead.
`universe.trade` | character vector giving the names of all the assets that are allowed to be traded. Assets not named here will be disallowed from trading. If `NULL`, then this does not impose a limit on the assets that are allowed to trade.
`lower.trade` | numeric vector of the desired lower bound on the units to trade in the assets. If this is an unnamed vector, then it is replicated to have length equal to the number of assets. If named, then it bounds just those specified assets. Bounds may automatically be placed on the assets from other information about the problem. See also the `max.weight` argument and the `positions` argument. There is more on this argument in the Details section.
`upper.trade` | numeric vector of the desired upper bound on the units to trade in the assets. If this is an unnamed vector, then it is replicated to have length equal to the number of assets. If named, then it bounds just those specified assets. Bounds may automatically be placed on the assets from other information about the problem. See also the `max.weight` argument and the `positions` argument. There is more on this argument in the Details section.
`risk.fraction` | a number, a vector, a two-column matrix, a three-dimensional array with two columns, a list, or `NULL`. This specifies constraints on some measure of the variance attributable to each asset. The `rf.style` argument controls what is being constrained. The maximum allowed is constrained for all assets by a single number, or for named assets in a vector. If a matrix is given, then the first column is the minimum allowed and the second column is the maximum allowed – the rows should be named with asset ids (not all assets need be constrained). If there are multiple combinations of variances and benchmarks or multiple risk fraction styles are used, then a three-dimensional array can be used to specify constraints for as many of the situations as desired. An alternative to giving a three-dimensional array is to give a list with length equal to the number of variance-benchmark-style combinations. The big advantage of a list is that simple values, such as a single number, can be given in some or all of the components. See the `rf.loc` argument.
`rf.style` | character vector giving the style of each risk fraction constraint. That is, it might say that some are value constraints rather than fraction constraints. The length of this should either be 1 or the number of risk fraction constraints. The allowable values are (abbreviations of): `"fraction"`, `"value"`, `"marginalbench"`, `"valmargbench"`, `"corport"`, `"abscorport"`, `"incorport"`, `"absincorport"`. `"fraction"` constrains the fraction of variance attributed to each of the assets. `"value"` constrains the variance attributed to each of the assets. `"marginalbench"` constrains the fraction of variance relative to the marginal impact of the benchmark. `"valmargbench"` constrains the variance relative to the marginal impact of the benchmark. `"corport"` constrains the correlation of assets to the portfolio. `"abscorport"` constrains the absolute correlation of assets to the portfolio. `"incorport"` and `"absincorport"` are like `"corport"` and `"abscorport"`, respectively, except that the constraints only apply to assets that are in the portfolio.
`rf.loc` | numeric vector giving the zero-based columns in `vtable` that each risk fraction constraint refers to. This should be `NULL` (interpreted as 0), a single number, or of length equal to the number of risk fraction constraints.
`ntrade` | an integer vector of length one or two. If length one, an integer giving the maximum number of assets to trade. If length two, then the minimum and maximum number of assets to trade. if `NULL`, then there is no constraint on the number of assets traded.
`port.size` | an integer or a vector of two integers. If a single integer, the upper bound on the desired number of assets in the optimal portfolio. If two integers, then the allowed range of the number of assets in the optimal portfolio.
`threshold` | a vector (with names); or a matrix with 1, 2, 3 or 4 columns, and row names. The first two columns give the minimum amount to be traded for (some of) the assets if the asset is traded at all. If a vector or one-column matrix, then the constraint is considered to be symmetric for buying and selling. If a two-column matrix, then the minimum of the two numbers for each asset can not be positive, and the maximum of the two numbers can not be negative. The third and fourth columns give the minimum number of units (shares or lots) allowed in the portfolio if the asset is in the portfolio at all. A three-column matrix can only be given for long-only portfolios, in which case the third column is the minimum number of units for the assets if the asset is in the portfolio. Otherwise, the third column should be non-positive. There is no requirement for row names if all of the rows are the same.
`forced.trade` | a named numeric vector giving a minimum amount to trade for specific assets (which are identified by the names of the vector). If you want to trade an exact amount, you need to also use `upper.trade` or `lower.trade`.
`positions` | a numeric matrix with 2, 4 or 8 columns giving the monetary value of positions that are allowed for each asset (rows). The first two columns give the minimum and maximum amount of money allowed in the portfolio for each of the assets. The third and fourth columns give the minimum and maximum amount of money that can be traded. Forced trades can be implied. If there is at least one `NA` in the first 4 columns in a row, then that asset is not allowed to trade (and other values in that row are ignored). Columns 5 through 8 are for threshold constraints: columns 5 and 6 give the minimum money amounts to trade the assets, and columns 7 and 8 give the minimum money amounts allowed in the portfolio. The matrix must have row names. The assets need not match the assets in `prices` – if there is a difference, then there is a warning unless the `positions.names` element of `do.warn` is set to `FALSE`.
`tol.positions` | a number giving a monetary value of the tolerance for existing positions to break the portfolio constraints given in the `positions` argument. For example if the value for an asset in the second column of `positions` is 2000 and the value of the existing position in that asset is 2010, then a sell will be forced if `tol.positions` is less than 10 but not if it is more than 10.
`lin.constraints` | a matrix or data frame describing the linear (and/or count) constraints to be placed on the portfolio and/or trade. Factors or characters (which are coerced to factors) represent as many constraints as there are levels in the factor. It is often easiest if this and `lin.bounds` are the result of a call to `build.constraints`. This may correspond to assets in addition to those in the current problem, but must contain information for all of the assets that are in the current problem.
`lin.bounds` | a two-column matrix with rows that correspond to the constraints represented by `lin.constraints` (not necessarily in the same order). The values of the bounds are in terms that are controlled by `lin.style`. If `lin.constraints` is given, then this argument must also be given. It is easiest to initialize this with a call to `build.constraints`. There must be rows for all of the given constraints, but additional rows may also be present.
`lin.trade` | a logical vector (replicated to have length equal to the number of columns in `lin.constraints`) which determines if the constraint is to be applied to the trade (`TRUE`), or the resulting portfolio (`FALSE`). Thus the same constraint can be in the constraint matrix more than once, but they need to have different names.
`lin.abs` | a logical vector (replicated to have length equal to the number of columns in `lin.constraints`). For those elements that are `TRUE`, the corresponding constraint uses the absolute value (of the weight or variance or the amount of money) for each asset (in the portfolio or trade). WARNING: the default for this changed – it is now `TRUE`. Previous to version 1.04 the default was `FALSE`.
`lin.style` | a character vector (replicated to have length equal to the number of columns in `lin.constraints`). Elements must be (an abbreviation of) one of: `"weight"`, `"value"`, `"count"`, `"varfraction"`, `"varvalue"`, `"varmbfraction"`, `"varmbvalue"`. For "weight" constraints, the bounds are expressed in weights (position value divided by gross value of the portfolio). For "value" constraints, the bounds are expressed in monetary units. For "count" constraints, the bounds are expressed in the number of assets; count constraints must be categorical, not numeric. For "varfraction" and "varmbfraction", the bounds are in fractions of the variance; the latter being the variance relative to the marginal impact of the benchmark. For "varvalue" and "varmbvalue", the bounds are in variance.
`lin.direction` | a numeric vector (replicated to have length equal to the number of columns in `lin.constraints`). Allowable values are 0, 1 and -1. If 0, all assets are counted. If 1, only long assets are counted. If -1, only short assets are counted.
`lin.rfloc` | a numeric vector or `NULL` (which is interpreted as 0). This gives the zero-based columns of `vtable` for the linear constraints that are of the risk fraction type. This is replicated to the number of linear constraints (number of columns in `lin.constraints`).
`alpha.constraint` | a numeric vector giving lower bounds for the alphas (expected returns), or a two-column matrix giving lower and upper bounds. If this has names, then they should coerce to integers that are one less than the column number of the desired column in the input or default `atable`. Without names, the first column (or columns) are assumed.
`var.constraint` | a numeric vector giving upper bounds for the variances, or a two-column matrix giving lower and upper bounds. If this has (row) names, then they should coerce to integers giving indices of the variance-benchmark combinations starting from zero (that is, it is one less than the column number of the combination in the input or default `vtable`). Without names, the first column (or columns) are assumed.
`bench.constraint` | a named vector giving upper bounds for variances relative to the named benchmarks, or a two-column matrix giving lower and upper bounds. The names need to be asset names represented in the `variance` argument or the `bench.weight` argument.
`dist.center` | either a named numeric vector, or a list with one or more components that are named numeric vectors. The names need to be asset ids like those of `prices`. If this is a numeric vector, then it is changed to be a length one list with that vector as its component (hence making it length one for the purposes of the descriptions of the other distance arguments). The components of this list are the target portfolios from which distances are measured.
`dist.style` | a character vector that is replicated to have length equal to the length of `dist.center` (after possibly being coerced to a list). The elements must be (abbreviations of) strings: `"weight"`, `"value"`, `"shares"`, `"sumsqwi"`, `"customweight"`, `"customvalue"`, `"customshares"`, `"customsumsqwi"`. The "weight" style means that a vector of weights should be given in `dist.center` that sum to one. The "value" style means that the monetary values of the portfolio should be given. The "shares" style means that the number of shares (or lots or whatever) should be given. These last two mean that the distances are in terms of value rather than weight. The "sumsqwi" style means that the distance is the weighted sum of squared differences in weights where the weights are the inverse of the weight in the target portfolio (assets not in the target are ignored). The styles that start with "custom" all use a price vector from `dist.prices` rather than `prices` to calculate the distance.
`dist.bounds` | a numeric vector, numeric one-column matrix, or numeric two-column matrix. A numeric vector is coerced into a one-column matrix, and a one-column matrix is coerced into a two-column matrix with the first column consisting of all zeros. The number of rows in this matrix may either be the number of components in the `dist.center` list, or that number minus the number of distances that are used in the utility (see `dist.utility`). The first column states the lower bound for the distance, and the second column states the upper bound. The numbers in each row need to correspond to the style for that distance.
`dist.trade` | a logical vector that is replicated to be the length of `dist.center`. Values that are `TRUE` indicate that the distance should be on the trade rather than on the portfolio.
`dist.utility` | a logical vector that is replicated to be the length of `dist.center`. Values that are `TRUE` indicate that the distance is used in the utility rather than constrained.
`dist.prices` | either a named numeric vector or a list with components that are named numeric vectors. If a list, it can either have length one, length equal to the number of "custom" styles, or length equal to the length of `dist.center`. This gives the prices used to calculate the custom style distances.
`sum.weight` | a numeric vector with names that correspond to integers, or a two-column matrix with row names. This constrains the sum of the largest absolute weights relative to the gross value. The name of an element (or row) gives the number of the largest weights to be summed, and the value gives the maximum (minimum and maximum in the case of a matrix) for the sum of that number of weights. For example, to limit the sum of the 5 largest weights to be no more than 40 percent, the appropriate `sum.weight` argument would be: `c("5"=.4)` Note the quotes around the 5.
`limit.cost` | either `NULL` or a length 2 numeric vector giving the lower and upper bounds on the cost. This is useful for random portfolios, but is unlikely to be of interest for optimization.
`close.number` | if given, a numeric vector of length 1 or 2. This is the lower and upper bounds for the number of positions to close in the existing portfolio. If of length 1, then exactly that number of positions are to be closed.
`utility` | character string; the possibilities are (the start of): `"information ratio"`, `"mean-variance"`, `"exocost information ratio"`, `"minimum variance"`, `"maximum return"`, `"mean-volatility"`, `"distance"`. The information ratio is the expected return of the portfolio divided by the square root of the variance of the portfolio. The default is the information ratio if both `variance` and `expected.return` are given and `dist.utility` is not `TRUE`. Otherwise, it infers what the default must be. This argument is ignored if `utable` is given.
`risk.aversion` | number giving the risk aversion for the mean-variance or mean-volatility utility. The utility is the risk aversion times the variance (or volatility) of the portfolio minus the expected return of the portfolio. Many other formulations use one-half the variance, so the risk aversion is different by a factor of two. If you want infinite risk aversion, you should set the objective to `"minimum variance"`. This argument is ignored except in the two cases where risk aversion appears in the utility.
`benchmark` | vector of one or more character strings naming the benchmark(s). These must appear in the variance but need not appear as names in `prices` unless `bench.trade` is `TRUE`.
`bench.trade` | logical value. If `TRUE`, then assets identified as benchmarks (in argument `benchmark` and `bench.constraint`) can be traded (and hence need to have a valid price). This is effectively set to `FALSE` if `universe.trade` is given.
`bench.weights` | a list where the name of each component is the name of a benchmark. Each component should be a named numeric vector that sums to 1 (or 100). All of the names on the weights need to be in `variance`. Benchmarks in this argument are added to `variance` if they are not included in it. Otherwise the variance is checked to see if the values in the variance are implied by the weights; if not, then the variance values are retained but a warning is issued unless `do.warn` item `variance.benchmark` is `FALSE`. The same is true for `expected.returns` except the `do.warn` item is `alpha.benchmark`.
`long.buy.cost` | a vector or matrix of the cost to buy assets if they are long. The meaning depends on whether or not `cost.par` has length. If `cost.par` is `NULL`: If a vector (or single column matrix), the costs are linear; that is, the cost in the objective for an asset is the number bought times the corresponding element in `buy.cost`. If this is a matrix with more than one column and `cost.par` has zero length, then it represents a polynomial of order one less than the number of columns. The first column is the intercept, the second column corresponds to number of units traded (to the first power), the third column corresponds to number of units squared, etc. If `cost.par` has positive length: Then this must have as many columns as the length of `cost.par`. Each column is the coeficient of units to the power given by the corresponding element of `cost.par`. If this has names (row names in the case of a matrix), then it may contain information for assets that are not in the current problem. However, it must have information on all of the tradable assets that are in the current problem.
`long.sell.cost` | a vector or matrix of the cost to sell long assets. See `long.buy.cost` for a full description. The default value of this is the value of `long.buy.cost`.
`short.buy.cost` | a vector or matrix of the cost to buy short assets. See `long.buy.cost` for a full description. The default value of this is the value of `long.buy.cost`.
`short.sell.cost` | a vector or matrix of the cost to sell short assets. See `long.buy.cost` for a full description. The default value of this is the value of `long.buy.cost`.
`cost.par` | `NULL` or a vector or matrix of exponents to the number of units for trading costs. If this is given, then all four of the arguments giving cost values must have the same number of columns as the length of `cost.par` (if it is a vector) or the number of columns of `cost.par` (if it is a matrix). Not giving this argument is equivalent to giving a sequence of integers (that starts at zero if there is more than one column in the costs). If this is a matrix, then it should have row names that identify the assets. This form allows each asset to have its own individual exponents in the cost function.
`ucost` | a number that scales the trading costs in the utility. For example, when maximizing returns, what is really maximized is the portfolio return minus `ucost` times the transaction costs.
`scale.cost` | a character string indicating what scaling should be done on the costs. This must partially match one of: `"gross"` (the most likely choice and the default), `"trade"`, `"none"`.
`start.sol` | there are three possibilities (apart from `NULL`): (1) an object resulting from `trade.optimizer`; (2) a named numeric vector (such as the `trade` component of the output of a previous optimization); (3) a list of such vectors. The starting solutions, which need not have length equal to `ntrade`, are used as suggestions for the optimizer. If a single starting solution is given and `funeval.max` is set to 0 or 1, then the result will be for the starting solution as the trade – no actual optimization is performed.
`allowance` | number less than one (but generally close to one) which provides the allowable range of `gross.value`, `net.value`, `long.value` and `short.value` if only a single number is given for the argument.
`do.warn` | logical vector. The most likely use is to give a vector of all `FALSE` values with names. The names need to partially match: `"cost.intercept.nonzero"`, `"converged"`, `"value.range"`, `"extraneous.assets"`, `"no.asset.names"`, `"benchmark.long.short"`, `"variance.list"`, `"turnover.max"`, `"max.weight.restrictive"`, `"neg.dest.wt"`, `"penalty.size"`, `"noninteger.forced"`, `"ignore.max.weight"`, `"bounds.missing"`, `"positions.names"`, `"start.noexist"`, `"random.start"`, `"novariance.optim"`, `"nonzero.penalty"`, `"neg.risk.aversion"`, `"zero.iterations"`, `"infinite.bounds"`, `"notrade"`, `"randport.failure"`, `"utility.switch"`, `"thresh.notrade"`, `"dist.prices"`, `"dist.style"`, `"dist.zero"`, `zero.variance`, `alpha.benchmark`, `variance.benchmark`, `var.eps`, `back.compat`, `index.zero`, `riskfrac.part`, `exit.obj`, `superfluous.constraint`. Warning messages will be suppressed when their type is set to `FALSE`. The default values are all `TRUE` except for `"converged"`. Some warnings are never suppressed.
`penalty.constraint` | a numeric vector giving the multiplier for each penalty. This is replicated to have length equal to the number of columns in `constraint.matrix` plus the number of variance constraints, etc.
`quantile` | a number between zero and one (inclusive) giving the quantile from the utilities when there is more than one utility destination. In general, it only makes sense to use numbers that are one-half or greater. When `quantile` is one, then this is a min-max solution; that is, for each portfolio we look at the worst (minimum) utility over the specified combinations of expected returns, variances and benchmarks, then we select the portfolio that maximizes the worst utility. With `quantile` set to one-half, we are getting the median utility over the combinations of expected returns, variances and benchmarks.
`dest.wt` | numeric vector giving strictly positive weights to the destinations of the combinations of expected returns and variances. When this is given, then the `quantile` argument refers to a weighted quantile.
`utable` | a numeric matrix which controls the combinations of expected returns, variances and benchmarks, and their placement into the destinations. Providing this is only necessary if there are multiple expected returns, variances or benchmarks, and the default treatment of them is not what is desired. The matrix has 6 rows: "alpha.spot" is the (zero-based) index of the columns of `atable`; "variance.spot" is the zero-based index of columns of `vtable`; "destination" is the zero-based index of the destination; "opt.objective" is 0 for a mean-variance utility, 1 for an information ratio utility, 2 for exocost information ratio, 3 for minimum variance, 4 for maximum return, 5 for mean-volatility, 6 for distance; "risk.aversion" is the risk aversion; and "wt.in.destination" is the weight of this combination inside the destination for this combination.
`atable` | numeric matrix with two rows describing the combinations of expected returns and benchmarks. The first row is the zero-based index of the expected returns (that is, one less than the column index of `expected.return`). The second row is the index within the assets of the benchmark (this starts numbering from zero); a negative number indicates no benchmark. However if given, then the second row is ignored and is created by the `benchmarks` attribute that is required. This attribute needs to be a character vector as long as the number of columns in `atable`; the elements are either asset names or the empty string (meaning no benchmark).
`vtable` | numeric matrix with three rows describing the combinations of variances and benchmarks. The first row is the zero-based index of the variance matrix (that is, one less than the index of the third dimension of `variance`). The second row is the index within the assets of the benchmark (this starts numbering from zero); a negative number indicates no benchmark. However if given, then the second row is ignored and is created by the `benchmarks` attribute that is required. This attribute needs to be a character vector as long as the number of columns in `vtable`; the elements are either asset names or the empty string (meaning no benchmark). The third row is one or zero depending on if the variance-benchmark combination is used in the utility or not.
`dumpfile` | a character string giving the name of a file to be produced for the purposes of debugging in the event of certain errors being triggered due to a bug. This is hopefully a superfluous argument. No file is created by default.
`...` | individual arguments to `trade.optimizer.control` (or whatever other function is given as `control`) may be given if `control` is not specifically given as a list.
`seed` | the seed for the random number generator that is internal to the optimizer. The whole name ("seed") must be used – no abbreviations allowed. If this is given, it will most likely be `NULL` or a single integer to create a random seed via `seed.BurSt`. Specifying this produces a random result as opposed to the default behavior of using a particular seed (`.standard.seed.BurSt`).
`control` | a list like the output of `trade.optimizer.control` that sets numerous controls for the optimizer. Alternatively, it can be a function that produces such a list. The whole name ("control") must be used – no abbreviations allowed.
`identity` | an arbitrary object, most likely a string or an integer. This is merely added unchanged to the output. It is useful when an optimization is repeatedly done in parallel. The whole name ("identity") must be used – no abbreviations allowed.

### Value

an object of class `portfolBurSt` which is a list with the following components:

`new.portfolio` | named numeric vector giving the optimal portfolio. The numbers are the number of units (shares, lots) of the assets.
`trade` | named numeric vector giving the trade needed to achieve the optimal portfolio. The numbers are the number of units (shares, lots) of the assets.
`results` | numeric vector containing various results from the optimization. It contains the objective achieved, the negative utility, the trading cost, and the penalty (for unmet constraints) component of the objective. The objective is the sum of the negative utility and the penalty. The cost is included (possibly non-linearly) in the negative utility.
`converged` | logical value(s): if a sufficiently large number of consecutive iterations failed to improve the solution, then convergence is declared to have occurred. If `stringency` is positive, then two values are returned: the first element (called `"total"`) is `TRUE` if the stringency requirement of finding enough identical solutions is satisfied; the second element is the convergence status of the final run performed.
`objective.utility` | character string stating the utility that is the objective of the optimization.
`universe.size` | a vector giving the number of assets in the universe, the number of assets allowed to trade, the number that the `universe.trade` argument allows to trade, and the number that the `positions` argument allows to trade. This component is suppressed when the object is printed, but it is a part of the output of the `summary` method for optimized portfolios.
`utable` | the utility table that was input or created for the problem. This component is suppressed when the object is printed.
`atable` | the input or created `atable`. This component is suppressed when the object is printed.
`vtable` | the input or created `vtable`. This component is suppressed when the object is printed.
`alpha.values` | vector with length equal to the number of expected return-benchmark combinations giving the (ex-ante) expected return(s) of the optimal portfolio. The values assume that the net asset value is the gross value. Scaling is called for if that assumption is not correct.
`var.values` | vector with length equal to the number of variance-benchmark combinations giving the (ex-ante) variance(s) of the optimal portfolio. The values assume that the net asset value is the gross value. Scaling is called for if that assumption is not correct.
`utility.values` | vector of the negative utilities (including costs and penalties) of the optimal portfolio. If there are multiple values, these are sorted – they are not in the same order as the columns of `utable` or destinations.
`constraint.violations` | numeric vector of the violations of each constraint type. Zero means the constraint is satisfied. This component is suppressed when the object is printed.
`penalty.constraint` | numeric vector of the penalties for each constraint type. This component is suppressed when the object is printed.
`value.limits` | two-column matrix giving the lower and upper bounds of the gross value, net value, long value and short value. This component is suppressed when the object is printed, but is shown in the summary.
`prices` | the vector of prices of relevant assets used in the optimization. That is, prices relevant to the solution found. This component is suppressed when the object is printed.
`optim.mumbo.jumbo` | numeric vector of results of the optimization. The first four values pertain to the final run (which is the only run unless `stringency` is positive). These give: number of iterations performed, the number of iterations to have improved the solution, the final number of consecutive iteration failures, and the maximum number of consecutive iteration failures. The next group refers to the entire optimization. These give: the number of portfolios evaluated, the total number of requested evaluations, the number of evaluations requested that were amusingly silly, and a flag denoting the state of the result. Finally there are values that are relevant when `stringency` is positive: the number of runs, the total number of iterations, the total number of successes and the number of assets that were in the trades of the runs in the initial phase. This component is suppressed when the object is printed, but is shown in the summary.
`risk.fraction` | if argument `risk.fraction` is given or there are variance fraction style linear constraints, then this component will be a matrix containing the fractions of variance for the assets. This component is suppressed when the object is printed.
`existing` | the existing portfolio before the optimization.
`violated` | character vector giving the types (if any) of constraints that are broken by the solution.
`seed` | the random seed for the internal random number generator of the optimizer. This component is suppressed when the object is printed.
`version` | character vector giving the version numbers for the C code and the S language code. This component is suppressed when the object is printed.
`sizes` | numeric vector describing aspects of the problem – generally uninteresting. This component is suppressed when the object is printed.
`dist.table` | a data frame giving information on each distance. The columns are: `style` (character); `trade` logical stating if the distance is for the trade or portfolio; `utility` logical stating if the distance is a utility or a constraint; and then the three numeric columns `lower.bnd`, `upper.bnd`, `value`.
`dist.center` | a list giving the target portfolio(s). This component is suppressed when the object is printed.
`dist.prices` | either `NULL` or a list giving the custom distance prices. This component is suppressed when the object is printed.
`benchmarks` | vector giving any benchmarks used. The names of the vector are the names of the benchmarks. The values in the vector are the zero-based indices of the benchmarks as used in `atable` and `vtable`. This component is not present if there are no benchmarks. This component is suppressed when the object is printed.
`forced.explicit` | vector giving the trades explicitly forced using the `forced.trade` argument. This component is not present if no trades were explicitly forced.
`positions.forced` | vector giving the trades that were forced via the `positions` argument. This component is not present if there were no such trades.
`all.forced` | vector giving the trades that were forced – including trades implicitly forced in order to try to satisfy maximum weight constraints, and trades forced via the `positions` argument. This component is not present if no trades were forced.
`positions` | the input `positions` if given. This component is suppressed when the object is printed.
`tol.positions` | the input `tol.positions` if `positions` is given. This component is suppressed when the object is printed.
`lin.table` | a data frame showing information on the set of linear constraints, one row for each (top-level) constraint. The columns are: `style`: states the style of the constraint (`"varfraction"`, `"count"`, `"weight"`, etc.). `trade`: logical stating whether the constraint is for the trade or the portfolio. `absolute`: logical stating whether the constraint is for the gross or net. `levels`: the number of levels for the constraint; this is zero for numeric constraints. `direction`: 0 for all assets, 1 for long-only constraints, -1 for short-only constraints. `rfloc`: the zero-based column of `vtable` to which a variance fraction style constraint refers; this is -1 for other constraint styles. `riskfrac.col`: the column of the `risk.fraction` matrix (in the output) that a variance fraction style constraint uses; this is 0 for other constraint styles. This component is not present unless `lin.constraints` was given. This component is suppressed when the object is printed, but is shown in the summary.
`con.realized` | a list with 0 or 1 components. The possible component is: `linear`: matrix giving bounds, values and violations of the linear constraints. This component is suppressed when the object is printed, but is shown in the summary.
`iterhistory` | a vector giving the objective value at each iteration of the optimization process. The length of this is two more than the number of iterations done: the first value gives the objective after the pre-iteration phase, and the last value gives the objective after the post-iteration phase. This is only present if the `save.iterhistory` control parameter is `TRUE`. In general, this is only of interest when investigating the quality of optimizations.
`identity` | the input value of `identity`. This component is suppressed when the object is printed.
`checkinput` | a list containing components: `prices`, `variance`, `expected.return` and `existing` with a few values each of those inputs. This is used in particular with random portfolios and updating to try to make sure that no sleight of hand is taking place with data. This component is suppressed when the object is printed.
`timestamp` | two character strings giving the time and date of creation (the time the command started and the time it ended).
`call` | an image of the call that created the object.

### Side Effects

The S language random seed is changed or created if the `seed` argument is such that it generates a new seed. That is not the default.

### Details

SPECIFYING THE MONETARY VALUE. While `prices` is always required, there is no other single argument that is always required. However, there is the requirement that the value of the portfolio be specified somehow. For any problem, specifying `turnover` is enough. For long-only problems, any one of `gross.value`, `long.value` or `net.value` being specified works. For long-short portfolios, then either `gross.value` and `net.value` need to be specified, or `long.value` and `short.value` (assuming that `turnover` has not been given). If any of the gross, net, long or short values are given, then at least one pair – either gross and net, or long and short – need to be given.

BOUNDING THE TRADE. The `lower.trade` and `upper.trade` arguments bound the number of units that may be traded for each asset. The optimizer insists that the range of allowable units includes zero. But you can use the `forced.trade` argument to specify trades that must be performed. You can also give the `positions` argument which is in monetary value rather than shares (or lots). `positions` can give limits on the value in the portfolio and the value to trade including forced trades; it can also specify assets not to trade (by placing `NA` in at least one of the first four columns of that row).

THE PENALTY. The objective not only includes the negative utility (including the cost of the trade) but also a penalty for breaking constraints. If the penalty is non-zero, then the optimization should generally be redone, or the constraints changed – the portfolio may not be very optimal when penalties are imposed. There are times when trivial penalties are imposed by constraints that are at the boundary – the optimality will not be affected in such cases.

SPEED AND OPTIMIZATION QUALITY. There is a trade-off between the time the optimizer takes and the quality of the optimization that you are likely to get. The control arguments `iterations.max` and `fail.iter` can be increased to improve the solution, or decreased to speed the optimization. The quality can also be improved by increasing `stringency` from zero. The User's Manual has more on this.

### Bugs

If the existing portfolio breaks maximum weight constraints (from the `max.weight` argument), there are situations in which the optimal portfolio will not satisfy those constraints – see the User's Manual for more information.

For long-only portfolios if more than one of `gross.value`, `net.value`, `long.value` is given, then the range of all these values is used as the allowable interval. More logical (but much more bother) would be the intersection of the intervals. Best is to just give one of these.

The `trace` argument has no effect under Windows in some cases – tracing information on this platform is given in batch mode.

### Revision

This help was last revised 2012 June 10.

### See Also

`trade.optimizer.control`, `build.constraints`, `random.portfolio`, `summary.portfolBurSt`, `deport.portfolBurSt`, `seed.BurSt`, `constraints.realized`, `Cfrag.list`.

### Examples

    # build long-only portfolio worth 1 million containing no more than 60 assets
    op1 <- trade.optimizer(eq.prices, varian, long.only=TRUE,
    	gross.value=1e6, ntrade=60)
    summary(op1)
    deport(op1) # csv file of the trade

    # revise a long-short portfolio, keep the number of assets no more than 50
    op2 <- trade.optimizer(eq.prices, varian, gross.value=1e6,
    	net.value=c(-1e3, 5e3), exist=cur.port, port.size=50)

[Package PortfolioProbe version 1.06 Index]