hu.birot.OTKit.otBuildingBlocks
Class Hierarchy

java.lang.Object
  hu.birot.OTKit.otBuildingBlocks.Hierarchy

public class Hierarchy
extends java.lang.Object

Realizes a constraint hierarchy. A constraint hierarchy is a set of constraints with "ranking variables". OT literature employs several ranking variables, such as the unperturbed and the perturbed r in Paul Boersma's Stochastic OT or the K-value in Tamas Biro's SA-OT. This class is flexible, it allows employing more ranking variables at the same time, and one can add new ones in the future. Yet, an important feature of this class is the existence of methods sorting the constraint set for each of the "ranking variables".

At this moment, a constraint can be given the following "ranking variables": kvalue, rank, rank1, rank2, unperturbedRank (aka unperturbed_rank), perturbedRank (aka perturbed_rank) and weight. Moreover, the hash rvariable creates the opportunity to add further ones. All these ranking variables have real values (of type Double).

Two further types have non-real values. Ranking variable "violrank" has a value of type dataType.Violation. The idea is that violations realize a data type that is a generalization of real numbers: two violations can be compared, and the difference of two violations can be defined. So the field "violrank" allows you to create more general constraint rankings.

Ranking variable "setrank" allows creating a lattice of constraints with only a partial order. A "setrank" is a string seen as a set of characters. Constraint A is ranked higher than constraint B, if the setrank associated with A is a superset of the setrank of B.

Beside a Vector of ConstrValues (that is, tuples of constraint together with ranking variables), a Hierarchy also may have a name (see field Hierarchy.name) and a type (see field Hierarchy.type). The latter specifies which type of hierarchy we are speaking of: OT, HG, etc.

Important note: This class is planned to undergo a serious revision in the (near) future, especially regarding the "ranking variables".

Field Summary

protected java.util.Vector<hu.birot.OTKit.otBuildingBlocks.Hierarchy.ConstrValue>	cv
static java.lang.String	HG Constant String field used to represent type "hg".
static java.lang.String	KVALUE Name of ranking variable 'kvalue'.
java.lang.String	name The name of the hierarchy (optional).
static java.lang.Object	no_ranking_value This object is returned whenever a constraint has no ranking value.
static java.lang.String	OT Constant String field used to represent type "ot".
static java.lang.String	PERTURBED_RANK Name of ranking variable 'perturbed_rank'.
static java.lang.String	RANK Name of ranking variable 'rank'.
static java.lang.String	RANK1 Name of ranking variable 'rank1'.
static java.lang.String	RANK2 Name of ranking variable 'rank2'.
static java.lang.String	SETRANK Name of ranking variable 'setrank'.
java.lang.String	type The type of grammar the hierarchy is meant for.
static java.lang.RuntimeException	unknownCon
static java.lang.RuntimeException	unknownConName
static java.lang.String	UNPERTURBED_RANK Name of ranking variable 'unperturbed_rank'.
static java.lang.String	VIOLRANK Name of ranking variable 'violrank'.
static java.lang.String	WEIGHT Name of ranking variable 'weight'.

Constructor Summary

Hierarchy()
Construct a hierarchy without any argument.

Hierarchy(java.lang.String name_of_hierarchy)
Construct a hierarchy by specifying its name.

Method Summary

void	addConstraint(Constraint cnstr) Add a constraint to the hierarchy.
void	addConstraintWithKvalue(Constraint cnstr, double k) Add a constraint to the hierarchy with K-value r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithPerturbedRank(Constraint cnstr, double r) Add a constraint to the hierarchy with perturbed rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithRank(Constraint cnstr, double r) Add a constraint to the hierarchy with rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithRank1(Constraint cnstr, double r) Add a constraint to the hierarchy with rank1 r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithRank2(Constraint cnstr, double r) Add a constraint to the hierarchy with rank2 r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithUnperturbedRank(Constraint cnstr, double r) Add a constraint to the hierarchy with unperturbed rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
void	addConstraintWithWeight(Constraint cnstr, double w) Add a constraint to the hierarchy with weight w, unless the constraint (a constraint with the same name) is already contained by the hierarchy.
java.util.HashSet<java.lang.String>	allRankingVariables() Returns a set of all ranking variable names that are used by the hierarchy.
Hierarchy	clone() Creates a clone of the hierarchy, with the same name, the same type and the same constraints.
java.util.Vector<java.lang.String>	constraintNames() This method returns a Vector containing the names of all the constraints in the Hierarchy.
java.util.Vector<Constraint>	constraints() This method returns a Vector containing all constraints in the Hierarchy.
void	copyRank(java.lang.String r1, java.lang.String r2) Copy values of ranking variable r1 to ranking variable r2, for all constraints in the hierarchy.
java.lang.Object	get(java.lang.String cnstr_name, java.lang.String rankname) The value of ranking variable rankname for constraints .
void	increaseRank(Constraint cnstr, double delta) Increase the value of rank variable "rank" by delta for constraint cnstr.
void	kvalue2rank() This method copies the values in the ranking variable "K-values" to the ranking variable "rank", for each constraint.
java.lang.Double	kvalueOf(Constraint cnstr) Returns the K-value of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
int	numberOfConstraints() This method returns the number of constraints in the hierarchy.
void	perturbed2rank() This method copies the values in the ranking variable "perturbed rank" to the ranking variable "rank", for each constraint.
java.lang.Double	perturbedRankOf(Constraint cnstr) Returns the perturbed rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
void	perturbGaussian(double m, double s) The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank".
void	perturbUniform(double r) The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank".
void	perturbUniform(double r, double m) The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank".
java.lang.Double	rank1Of(Constraint cnstr) Returns the rank1 of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
java.lang.Double	rank2Of(Constraint cnstr) Returns the rank2 of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
void	rank2weight(double q) For each constraint in the hierarchy, this method sets the value of weight based on the values of rank.
java.lang.Double	rankOf(Constraint cnstr) Returns the rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
void	removeConstraint(Constraint cnstr) Removes a constraint from the hierarchy.
void	removeConstraint(java.lang.String cnstr) Removes a constraint from the hierarchy, whose name is cnstr.
java.util.HashMap<java.lang.String,java.lang.Double>	rvariableOf(Constraint cnstr)
void	set(java.lang.String cnstr_name, java.lang.String rankname, java.lang.Object r) Set the value of ranking variable rankname to r for constraint with name cnstr_name.
void	setKvalue(Constraint cnstr, double r) Set the value of rank variable "kvalue" to r for constraint cnstr.
void	setKvalue(java.lang.String cnstr_name, double r) Set the value of rank variable "kvalue" to r for the constraint whose name is cnstr_name.
void	setPerturbedRank(Constraint cnstr, double r) Set the value of rank variable "perturbed rank" to r for constraint cnstr.
void	setPerturbedRank(java.lang.String cnstr_name, double r) Set the value of rank variable "perturbed rank" to r for the constraint whose name is cnstr_name.
void	setRank(Constraint cnstr, double r) Set the value of rank variable "rank" to r for constraint cnstr.
void	setRank(java.lang.String string_describing_hierarchy) Set the values of the ranking parameter "rank" according to the hierarchy described in the parameter of this method.
void	setRank(java.lang.String cnstr_name, double r) Set the value of rank variable "rank" to r for the constraint whose name is cnstr_name.
void	setRank1(Constraint cnstr, double r) Set the value of rank variable "rank1" to r for constraint cnstr.
void	setRank1(java.lang.String cnstr_name, double r) Set the value of rank variable "rank1" to r for the constraint whose name is cnstr_name.
void	setRank2(Constraint cnstr, double r) Set the value of rank variable "rank2" to r for constraint cnstr.
void	setRank2(java.lang.String cnstr_name, double r) Set the value of rank variable "rank2" to r for the constraint whose name is cnstr_name.
void	setUnperturbedRank(Constraint cnstr, double r) Set the value of rank variable "unperturbed rank" to r for constraint cnstr.
void	setUnperturbedRank(java.lang.String cnstr_name, double r) Set the value of rank variable "unperturbed rank" to r for the constraint whose name is cnstr_name.
void	setWeight(Constraint cnstr, double w) Set the value of rank variable "weight" to w for constraint cnstr.
void	setWeight(java.lang.String cnstr_name, double w) Set the value of rank variable "weight" to w for the constraint whose name is cnstr_name.
Constraint[]	sortBy(java.lang.String rank) Returns an array of the constraints in the hierarchy, sorted from "least influential" to "most influential", with respect to the ranking variable rank.
Constraint[]	sortByKvalue() Returns an array of constraints sorted by increasing K-values.
Constraint[]	sortByPerturbedRank() Returns an array of constraints sorted by increasing perturbed rank.
Constraint[]	sortByRank() Returns an array of constraints sorted by rank in an increasing order.
Constraint[]	sortByRank1() Returns an array of constraints sorted by increasing rank1.
Constraint[]	sortByRank2() Returns an array of constraints sorted by increasing rank2.
void	sortByRank2hierarchyKvalue() This method sorts the constraints in the hierarchy by ranking variable "rank", and encodes it in the ranking variable "K-value".
void	sortByRank2hierarchyKvalueAndWeight(double q) This method combines the methods sortByRank(), sortByRank2hierarchyKvalue() and sortByRank2hierarchyWeight(double q).
void	sortByRank2hierarchyWeight(double q) This method sorts the constraints in the hierarchy by ranking variable "rank", and encodes it in the ranking variable "weight".
Constraint[]	sortByUnperturbedRank() Returns an array of constraints sorted by increasing unperturbed rank.
Constraint[]	sortByWeight() Returns an array of constraints sorted by decreasing weight.
Constraint[]	sortedByRank() This method returns the constraints in the hierarchy sorted by ranking variable "rank", provided that method sortByRank has been applied previously.
java.lang.String	sortedByRankHierarchy() This method returns a string describing the hierarchy as sorted by rank, supposing that method sortByRank has been applied previously.
void	unperturbed2rank() This method copies the values in the ranking variable "unperturbed rank" to the ranking variable "rank", for each constraint.
java.lang.Double	unperturbedRankOf(Constraint cnstr) Returns the unperturbed rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).
java.util.HashMap<Constraint,Violation>	value(Candidate can) Returns the evaluation of a candidate by each constraint in this hierarchy in the form of a hash table.
void	weight2rank(double q) For each constraint in the hierarchy, this method sets the value of rank based on the values of weight.
java.lang.Double	weightOf(Constraint cnstr) Returns the weight of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

no_ranking_value

public static final java.lang.Object no_ranking_value

This object is returned whenever a constraint has no ranking value. Its toString() method returns an empty string. Note that standard ranking variables with a double value return Double.NaN in similar cases.

cv

protected java.util.Vector<hu.birot.OTKit.otBuildingBlocks.Hierarchy.ConstrValue> cv

name

public java.lang.String name

The name of the hierarchy (optional). Default value: an empty string.

type

public java.lang.String type

The type of grammar the hierarchy is meant for. In general, its use is optional. Yet, certain classes (such as those in package performance) require it to be specified as "ot" or "hg". Hence, suggested values are "ot" and "hg", or rather the constant fields Hierarchy.OT and Hierarchy.HG. Default value: an empty string.

OT

public static final java.lang.String OT

Constant String field used to represent type "ot".

See Also:

Constant Field Values

HG

public static final java.lang.String HG

Constant String field used to represent type "hg".

See Also:

Constant Field Values

unknownCon

public static final java.lang.RuntimeException unknownCon

unknownConName

public static final java.lang.RuntimeException unknownConName

RANK

public static final java.lang.String RANK

Name of ranking variable 'rank'.

See Also:

Constant Field Values

RANK1

public static final java.lang.String RANK1

Name of ranking variable 'rank1'.

See Also:

Constant Field Values

RANK2

public static final java.lang.String RANK2

Name of ranking variable 'rank2'.

See Also:

Constant Field Values

PERTURBED_RANK

public static final java.lang.String PERTURBED_RANK

Name of ranking variable 'perturbed_rank'.

See Also:

Constant Field Values

UNPERTURBED_RANK

public static final java.lang.String UNPERTURBED_RANK

Name of ranking variable 'unperturbed_rank'.

See Also:

Constant Field Values

KVALUE

public static final java.lang.String KVALUE

Name of ranking variable 'kvalue'.

See Also:

Constant Field Values

WEIGHT

public static final java.lang.String WEIGHT

Name of ranking variable 'weight'.

See Also:

Constant Field Values

SETRANK

public static final java.lang.String SETRANK

Name of ranking variable 'setrank'.

See Also:

Constant Field Values

VIOLRANK

public static final java.lang.String VIOLRANK

Name of ranking variable 'violrank'.

See Also:

Constant Field Values

Constructor Detail

Hierarchy

public Hierarchy()

Construct a hierarchy without any argument.

Hierarchy

public Hierarchy(java.lang.String name_of_hierarchy)

Construct a hierarchy by specifying its name.

Parameters:

name_of_hierarchy - : The name of the hierarchy to be constructed.

Method Detail

addConstraint

public void addConstraint(Constraint cnstr)

Add a constraint to the hierarchy. If the constraint (a constraint with the same name) is already contained by the hierarchy, then the new constraint takes the place of the old one (keeping the ranking variables of the old one).

Parameters:

cnstr - : The constraint to be added to the hierarchy.

addConstraintWithRank

public void addConstraintWithRank(Constraint cnstr,
                                  double r)

Add a constraint to the hierarchy with rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of rank is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

r - : the value of rank.

addConstraintWithKvalue

public void addConstraintWithKvalue(Constraint cnstr,
                                    double k)

Add a constraint to the hierarchy with K-value r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of K-value is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

k - : the value of K-value.

addConstraintWithRank1

public void addConstraintWithRank1(Constraint cnstr,
                                   double r)

Add a constraint to the hierarchy with rank1 r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of rank1 is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

r - : the value of rank1.

addConstraintWithRank2

public void addConstraintWithRank2(Constraint cnstr,
                                   double r)

Add a constraint to the hierarchy with rank2 r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of rank2 is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

r - : the value of rank2.

addConstraintWithUnperturbedRank

public void addConstraintWithUnperturbedRank(Constraint cnstr,
                                             double r)

Add a constraint to the hierarchy with unperturbed rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of unperturbed rank is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

r - : the value of unperturbed rank.

addConstraintWithPerturbedRank

public void addConstraintWithPerturbedRank(Constraint cnstr,
                                           double r)

Add a constraint to the hierarchy with perturbed rank r, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of perturbed rank is set to r.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

r - : the value of perturbed rank.

addConstraintWithWeight

public void addConstraintWithWeight(Constraint cnstr,
                                    double w)

Add a constraint to the hierarchy with weight w, unless the constraint (a constraint with the same name) is already contained by the hierarchy. (In that case, the value of the weight is set to w.)

Parameters:

cnstr - : The constraint to be added to the hierarchy.

w - : the value of the weight.

constraints

public java.util.Vector<Constraint> constraints()

This method returns a Vector containing all constraints in the Hierarchy.

constraintNames

public java.util.Vector<java.lang.String> constraintNames()

This method returns a Vector containing the names of all the constraints in the Hierarchy.

rankOf

public java.lang.Double rankOf(Constraint cnstr)

Returns the rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

kvalueOf

public java.lang.Double kvalueOf(Constraint cnstr)

Returns the K-value of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

rank1Of

public java.lang.Double rank1Of(Constraint cnstr)

Returns the rank1 of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

rank2Of

public java.lang.Double rank2Of(Constraint cnstr)

Returns the rank2 of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

unperturbedRankOf

public java.lang.Double unperturbedRankOf(Constraint cnstr)

Returns the unperturbed rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

perturbedRankOf

public java.lang.Double perturbedRankOf(Constraint cnstr)

Returns the perturbed rank of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

weightOf

public java.lang.Double weightOf(Constraint cnstr)

Returns the weight of constraint cnstr in the hierarchy (that is, of the constr in the hierarchy whose name is the same as the name of cnstr).

rvariableOf

public java.util.HashMap<java.lang.String,java.lang.Double> rvariableOf(Constraint cnstr)

get

public java.lang.Object get(java.lang.String cnstr_name,
                            java.lang.String rankname)

The value of ranking variable rankname for constraints .

If rankname is one of the following:

"rank", "rank1", "rank2", "perturbed_rank" (sic!), "unperturbed_rank" (sic!), "kvalue" and "weight" (all case sensitive)

then one of the standard ranking variable are returned (see the other methods). Otherwise, the value mapped to by the hash rvariable is returned.

Exception is thrown, if cnstr_name does not correspond to any constraint with that name.

Parameters:

cnstr_name - Name of the constraint.

rankname - Name of the ranking variable.

Returns:

The value of the ranking variable described above; the Hierarchy.no_ranking_value object if no value is specified for the given constraint.

setRank

public void setRank(Constraint cnstr,
                    double r)

Set the value of rank variable "rank" to r for constraint cnstr.

setRank

public void setRank(java.lang.String cnstr_name,
                    double r)

Set the value of rank variable "rank" to r for the constraint whose name is cnstr_name.

setKvalue

public void setKvalue(Constraint cnstr,
                      double r)

Set the value of rank variable "kvalue" to r for constraint cnstr.

setKvalue

public void setKvalue(java.lang.String cnstr_name,
                      double r)

Set the value of rank variable "kvalue" to r for the constraint whose name is cnstr_name.

setRank1

public void setRank1(Constraint cnstr,
                     double r)

Set the value of rank variable "rank1" to r for constraint cnstr.

setRank1

public void setRank1(java.lang.String cnstr_name,
                     double r)

Set the value of rank variable "rank1" to r for the constraint whose name is cnstr_name.

setRank2

public void setRank2(Constraint cnstr,
                     double r)

Set the value of rank variable "rank2" to r for constraint cnstr.

setRank2

public void setRank2(java.lang.String cnstr_name,
                     double r)

Set the value of rank variable "rank2" to r for the constraint whose name is cnstr_name.

setUnperturbedRank

public void setUnperturbedRank(Constraint cnstr,
                               double r)

Set the value of rank variable "unperturbed rank" to r for constraint cnstr.

setUnperturbedRank

public void setUnperturbedRank(java.lang.String cnstr_name,
                               double r)

Set the value of rank variable "unperturbed rank" to r for the constraint whose name is cnstr_name.

setPerturbedRank

public void setPerturbedRank(Constraint cnstr,
                             double r)

Set the value of rank variable "perturbed rank" to r for constraint cnstr.

setPerturbedRank

public void setPerturbedRank(java.lang.String cnstr_name,
                             double r)

Set the value of rank variable "perturbed rank" to r for the constraint whose name is cnstr_name.

setWeight

public void setWeight(Constraint cnstr,
                      double w)

Set the value of rank variable "weight" to w for constraint cnstr.

setWeight

public void setWeight(java.lang.String cnstr_name,
                      double w)

Set the value of rank variable "weight" to w for the constraint whose name is cnstr_name.

setRank

public void setRank(java.lang.String string_describing_hierarchy)

Set the values of the ranking parameter "rank" according to the hierarchy described in the parameter of this method.

The parameter string_describing_hierarchy is a string in the form "C1 >> C2 >> C3 etc.", with C1, C2, C3 etc. being the constraints' name in this hierarchy. The names of the constraints are separated by the character pair ">>", while white spaces (including tabs, etc.) are ignored (trimmed). The format corresponds to the one produced by the method sortedByRankHierarchy().

The constraint whose name appears rightmost in this string is assigned a ranking parameter "rank" of value 1; this is the constraint that is intended to be ranked to the lowest position in the hierarchy. The second constraint from the right gets a rank of 2, and so forth. The leftmost constraint (to be ranked the highest) is assigned a rank equal to the number of constraints mentioned in the string.

The rank of any constraint in the hierarchy whose name is not mentioned in the string will not have its rank changed. A constraint name in the string that does not correspond to the name of any constraint in the hierarchy will result in a Runtime Exception "Unknown constraint name".

Parameters:

string_describing_hierarchy - A string describing the intended hierarchy.

set

public void set(java.lang.String cnstr_name,
                java.lang.String rankname,
                java.lang.Object r)

Set the value of ranking variable rankname to r for constraint with name cnstr_name.

If rankname is one of the following:

"rank", "rank1", "rank2", "perturbed_rank" (sic!), "unperturbed_rank" (sic!), "kvalue" and "weight" (all case sensitive)

then one of the standard ranking variable are affected (see the other methods). Otherwise, the information goes to the hash rvariable.

If r is Hierarchy.no_ranking_value, then the above ranking variables are set to Double.NaN, and all other ranking names are removed from the hash rvariable.

Exception is thrown, if cnstr_name does not correspond to any constraint with that name.

Parameters:

cnstr_name - Name of the constraint whose ranking variable has to be set.

rankname - Name of the ranking variable to be set.

r - Value to which the ranking variable has to be set.

sortByRank

public Constraint[] sortByRank()

Returns an array of constraints sorted by rank in an increasing order. Element 0 is the lowest ranked one (it has the lowest ranking variable "rank"), whereas the last element in the array (nr. length()-1) is ranked the highest (it has the highest value for "rank").

If this array is required several times, you can employ this method only once, and then employ method sortedByRank(), which does not employ the sorting algorithm (provided that the rank values do not change).

sortedByRank

public Constraint[] sortedByRank()

This method returns the constraints in the hierarchy sorted by ranking variable "rank", provided that method sortByRank has been applied previously. The advantage is that sorting needs not be repeated each time the constraints are needed.

Returns:

The constraints in the hierarchy sorted by ranking variable "rank", provided that method sortByRank has been applied previously.

sortedByRankHierarchy

public java.lang.String sortedByRankHierarchy()

This method returns a string describing the hierarchy as sorted by rank, supposing that method sortByRank has been applied previously.

Returns:

A string describing the hierarchy.

sortByKvalue

public Constraint[] sortByKvalue()

Returns an array of constraints sorted by increasing K-values.

sortByRank1

public Constraint[] sortByRank1()

Returns an array of constraints sorted by increasing rank1.

sortByRank2

public Constraint[] sortByRank2()

Returns an array of constraints sorted by increasing rank2.

sortByUnperturbedRank

public Constraint[] sortByUnperturbedRank()

Returns an array of constraints sorted by increasing unperturbed rank.

sortByPerturbedRank

public Constraint[] sortByPerturbedRank()

Returns an array of constraints sorted by increasing perturbed rank.

sortByWeight

public Constraint[] sortByWeight()

Returns an array of constraints sorted by decreasing weight. Note that the direction of sorting is the opposite from when the hierarchy is ranked by rank, K-value, etc.

sortBy

public Constraint[] sortBy(java.lang.String rank)

Returns an array of the constraints in the hierarchy, sorted from "least influential" to "most influential", with respect to the ranking variable rank. For most ranking variable, the constraints are ranked for increasing rank. But for weight, they are ranked for decreasing rank.

Parameters:

rank - Ranking variable according to which constraints are ranked.

Returns:

An array of constraints ranked by their ranking value for ranking variable rank.

copyRank

public void copyRank(java.lang.String r1,
                     java.lang.String r2)

Copy values of ranking variable r1 to ranking variable r2, for all constraints in the hierarchy. Regarding the values of r1 and r2, see methods get and set.

Parameters:

r1 - Name of the original ranking variable.

r2 - Name of the target ranking variable.

increaseRank

public void increaseRank(Constraint cnstr,
                         double delta)

Increase the value of rank variable "rank" by delta for constraint cnstr.

rank2weight

public void rank2weight(double q)

For each constraint in the hierarchy, this method sets the value of weight based on the values of rank. For constraint c[i] with rank r[i], weight is set to w[i] = - q^r[i].

Parameters:

q - : The base defining the transformation (q>0).

weight2rank

public void weight2rank(double q)

For each constraint in the hierarchy, this method sets the value of rank based on the values of weight. For constraint c[i] with rank r[i], rank is set such that w[i] = - q^r[i].

Parameters:

q - : The base defining the transformation (q>0).

perturbUniform

public void perturbUniform(double r)

The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank". The noise follows a uniform distribution between 0 and r. In other words, for each constraint, perturbedRank = unperturbedRank + noise, where noise is a random number between 0 and r, following a uniform distribution. (The value of noise is different for each constraint.)

Parameters:

r - : The width (range) of the uniform distribution that determines the noise to be added to the unperturbed rank values.

perturbUniform

public void perturbUniform(double r,
                           double m)

The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank". The noise follows a uniform distribution with mean m and range r. In other words, for each constraint, perturbedRank = unperturbedRank + noise, where noise is a random number between m-r/2 and m+r/2, following a uniform distribution. (The value of noise is different for each constraint.) If you would like to add a noise between -c and c, you can use perturbUniform(0, 2*c).

Parameters:

r - : The width (or range) of the uniform distribution that determines the noise to be added to the unperturbed rank values.

m - : The mean of the random distribution.

perturbGaussian

public void perturbGaussian(double m,
                            double s)

The ranking variable "perturbed rank" of each constraint is set such that a random perturbation (noise) is added to the value of the ranking variable "unperturbed rank". The noise follows a Gaussian (Normal) distribution with mean m and standard deviation s. In other words, for each constraint, perturbedRank = unperturbedRank + noise, where noise is a random number following the Normal distribution distribution N(m,s). (The value of noise is different for each constraint.)

Parameters:

m - : The mean of the Normal distribution which is followed by the Gauusian noise.

s - : The standard deviation of the Normal distribution which is followed by the Gauusian noise.

perturbed2rank

public void perturbed2rank()

This method copies the values in the ranking variable "perturbed rank" to the ranking variable "rank", for each constraint.

This method can be useful when employing methods Eval.Compare and Eval.CompareOT, which use the ranking variable "rank". In this case, do not forget running the method Hierarchy.sortByRank(), after running method perturbed2rank() and before running Eval.Compare.

unperturbed2rank

public void unperturbed2rank()

This method copies the values in the ranking variable "unperturbed rank" to the ranking variable "rank", for each constraint.

This method can be useful when employing methods Eval.Compare and Eval.CompareOT, which use the ranking variable "rank". In this case, do not forget running the method Hierarchy.sortByRank(), after running method unperturbed2rank() and before running Eval.Compare.

kvalue2rank

public void kvalue2rank()

This method copies the values in the ranking variable "K-values" to the ranking variable "rank", for each constraint.

This method can be useful when employing methods Eval.Compare and Eval.CompareOT, which use the ranking variable "rank". In this case, do not forget running the method Hierarchy.sortByRank(), after running method unperturbed2rank() and before running Eval.Compare.

sortByRank2hierarchyKvalue

public void sortByRank2hierarchyKvalue()

This method sorts the constraints in the hierarchy by ranking variable "rank", and encodes it in the ranking variable "K-value". The lowest ranked constraint (the one with the lowest value for "rank") is assigned a K-value of 0, the second lowest ranked constraint (with respect to "rank") is assigned a K-value of 1, etc. The highest ranked constraint (the one with the highest value for "rank") is assigned a K-value equal to the number of constraints in the hierarchy minus one.

sortByRank2hierarchyWeight

public void sortByRank2hierarchyWeight(double q)

This method sorts the constraints in the hierarchy by ranking variable "rank", and encodes it in the ranking variable "weight". The lowest ranked constraint (the one with the lowest value for "rank") is assigned a weight of -1, the second lowest ranked constraint (with respect to "rank") is assigned a weight of -q, etc. The highest ranked constraint (the one with the highest value for "rank") is assigned a weight equal to -q^L, where L is the number of constraints in the hierarchy minus one.

Parameters:

q - The base used to calculate the weights.

sortByRank2hierarchyKvalueAndWeight

public void sortByRank2hierarchyKvalueAndWeight(double q)

This method combines the methods sortByRank(), sortByRank2hierarchyKvalue() and sortByRank2hierarchyWeight(double q).

Parameters:

q - The base used to calculate the weights.

allRankingVariables

public java.util.HashSet<java.lang.String> allRankingVariables()

Returns a set of all ranking variable names that are used by the hierarchy.

removeConstraint

public void removeConstraint(Constraint cnstr)

Removes a constraint from the hierarchy. If the specified constraint is not contained in the hierarchy, then runtime error "Unknown constraint" is thrown.

Parameters:

cnstr - Constraint to be removed from the hierarchy.

removeConstraint

public void removeConstraint(java.lang.String cnstr)

Removes a constraint from the hierarchy, whose name is cnstr. If no constraint with such a name is contained in the hierarchy, then runtime error "Unknown constraint name" is thrown.

Parameters:

cnstr - Name of the Constraint to be removed from the hierarchy.

value

public java.util.HashMap<Constraint,Violation> value(Candidate can)

Returns the evaluation of a candidate by each constraint in this hierarchy in the form of a hash table. The return value of this method is a hash that maps a constraint c (from this hierarchy) onto c.value(can), that is, the violation level assigned by constraint c to candidate can.

Parameters:

can - The candidate to be evaluated by all constraints in the hierarchy.

Returns:

A HashMap, such that if constraint c maps to violation v in this map, then c appears in the hierarchy and c.value(can) is v.

numberOfConstraints

public int numberOfConstraints()

This method returns the number of constraints in the hierarchy.

Returns:

The number of constraints in the hierarchy.

clone

public Hierarchy clone()

Creates a clone of the hierarchy, with the same name, the same type and the same constraints. For each constraint the values of the ranking variables (rank, rank 1, rank 2, K-value, perturbed rank, perturbed rank, weight) are also copied.

Overrides java.lang.Object.clone. Note that the return type of this method is Hierarchy, and not Object, as the return type of the original method.

Overrides:

clone in class java.lang.Object

Returns:

A clone of the original hierarchy.