'AddConstraint' Command Details
Below, we list examples of the 'addConstraint' command for each type of
constraint, as well as the arguments required for each one.
HARD CONSTRAINTS
Hard-bound constraints
SOFT CONSTRAINTS
Soft-distance constraints
Soft meta-constraints
Soft correlation constraints
Soft entropy constraints
HARD CONSTRAINTS
Hard-bound constraints:
REQUIRED:
sosObj - name of the SOS object to which the constraint pertains
name - name of the constraint being created
constraintType - type of constraint to be created (here, 'hard')
fnc - type of function the constraint will perform. Here, options are:
floor - lower-bound on values of a particular variable. No values
lower will be included in the optimized sample(s).
ceiling - upper-bound on values of a particular variable. No values
greater will be included in the optimized sample(s).
sample1 - name of sample to which constraint applies
s1ColName - name of column in sample to which constraint applies
value - floor or ceiling value
EXAMPLES:
mySOS.addConstraint('sosObj', mySOS, 'name', 'constraint1',
'constraintType', 'hard', 'fnc', 'floor', 'sample1', 's1', 's1ColName',
'col1', 'value', 10);
SOFT CONSTRAINTS
Soft-distance constraints:
REQUIRED:
sosObj - name of the SOS object to which the constraint pertains
name - name of the constraint being created
constraintType - type of constraint beng created (here, 'soft')
fnc - type of function the constraint will perform. Here, options are:
min - minimizes differences between two samples on a variable
max - maximizes differences between two samples on a variable
orderedMax - maximizes differences between two samples on a variable and requires that sample1 has a lower mean or
stdev than sample2
match1SampleVal - matches the mean or stdev of a single sample
to a specified value
stat - the statistic to which the constraint applies. Here, can be
'mean', or 'stdev' (standard deviation).
sample1 - name of first sample to which constraint applies
sample2 - name of second sample to which constraint applies
(required for 'min', 'max', and 'orderedMax' types)
s1ColName - name of column in first sample to which constraint
applies
s2ColName - name of column in second sample to which constraint
applies (required for 'min', 'max', and 'orderedMax' types)
'paired'/logical - determines if pairwse or group-wise distances are
calculated.
targVal - required only for 'match1SampleVal' constraints; specifies the value to which the sample is matched
OPTIONAL:
exponent - determines power to which difference is raised in cost
function. Defaults to 2 (quadratic difference)
weight - determines weighting factor on constraint. Defaults to 1 (equal weighting of all soft constraints)
EXAMPLES:
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType', 'soft', 'fnc', 'min', 'stat', 'mean',
'sample1', s1, 'sample2', s2, 's1ColName', 'col1', 's2ColName', 'col2',
'paired', false);
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType1', 'soft', 'fnc', 'orderedMax', 'stat',
'mean', 'sample1', s1, 'sample2', s2, 's1ColName', 'col1',
's2ColName', 'col2', 'paired', true);
(Note that the name of the sample desired to have the lower
value should be entered as 'sample1'.)
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType1', 'soft', 'fnc', 'match1SampleVal',
'stat', 'stdev', 'sample1', s1, 's1ColName', 'col1', 'paired', false,
'targVal', 1);
Soft meta-constraints:
REQUIRED:
sosObj - name of the SOS object to which the constraint pertains
name - name of the constraint being created
constraintType - type of constraint beng created (here, 'meta')
fnc - type of function the constraint will perform. Here, options are:
matchCost - matches the cost associated with two different
constraints
matchCostNotMin - ensures that a minimization constraint is
satisfied before a maximization constraint is addressed
constraint1 - name of the first constraint. With 'matchCostNotMin'
constraints, 'constraint1' must be the name of the minimization
constraint.
constraint2 - name of the second constraint. With
'matchCostNotMin', 'constraint2' must be the name of the
maximization constraint.
OPTIONAL:
exponent - determines power to which difference is raised in cost
function. Defaults to 2 (quadratic difference)
weight - determines weighting factor on constraint. Defaults to 1 (equal weighting of all soft constraints)
constraint2costScale - multiplier that affects cost of constraint2
EXAMPLES:
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType', 'meta', 'fnc', 'matchCostNotMin',
'constraint1', 'minConst1', 'constraint2', 'maxConst1');
Soft correlation constraints:
REQUIRED:
sosObj - name of the SOS object to which the constraint pertains
name - name of the constraint being created
constraintType - type of constraint beng created (here, 'soft')
fnc - type of function the constraint will perform. Here, options are:
matchCorrel - matches the correlation between two samples to a
specified value
sample1 - name of first sample to which constraint applies
sample2 - name of second sample to which constraint applies
s1ColName - name of column in first sample to which constraint
applies
s2ColName - name of column in second sample to which constraint
applies
targVal - value to which the correlation between samples should be
matched
OPTIONAL:
exponent - determines power to which difference is raised in cost
function. Defaults to 2 (quadratic difference)
weight - determines weighting factor on constraint. Defaults to 1 (equal weighting of all soft constraints)
EXAMPLES:
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType', 'soft', 'fnc', 'matchCorrel',
'sample1', s1, 'sample2', s2, 's1ColName', 'col1', 's2ColName', 'col2',
'targVal', 0.0);
Soft entropy constraints:
REQUIRED:
sosObj - name of the SOS object to which the constraint pertains
name - name of the constraint being created
constraintType - type of constraint beng created (here, 'soft')
fnc - type of function the constraint will perform. Here, options are:
minEnt - minimizes entropy of a particular distribution of values
maxEnt - maximizes entropy of a particular distribution of values
sample1 - name of sample to which constraint applies
s1ColName - name of column in sample to which constraint applies
pdSpread - determines relative to what entropy is maximized or
minimized. Options are:
sample - entropy will be maximized or minimized relative to items
in the sample only
allItems - entropy will be maximized or minimized relative to all
items in the population
OPTIONAL:
exponent - determines power to which difference is raised in cost
function. Defaults to 2 (quadratic difference)
weight - determines weighting factor on constraint. Defaults to 1 (equal weighting of all soft constraints)
nbin/int - number of bins into which to divide data for purposes of
calculating probability distribution. Defaults to number of items in
the sample. Must be greater than 2 and less than or equal to
number of items in the sample.
EXAMPLES:
myConstraint = mySOS.addConstraint('sosObj', mySOS, 'name',
'constraint1', 'constraintType', 'soft', 'fnc', 'maxEnt', 'sample1', s1,
's1ColName', 'col1', 'pdSpread', 'allItems',);