esat.rotational package

esat.rotational package#

Submodules#

esat.rotational.constrained module#

class esat.rotational.constrained.ConstrainedModel(base_model: SA, data_handler: DataHandler, softness: float = 1.0)#

Bases: object

The constrained model class that creates an instead of a constrained model using a base SA model.

The constrained model takes as input a previously completed SA instance, the solution of a base model run (single SA instance) is used for the initial conditions of a constrained model run. Additional inputs include the instance of the DataHandler used to provided data to the SA instance (used for plotting) and a ‘softness’ parameter that determines how soft, or how large, the Q(aux) value is in comparison to the Q(Robust) and Q(True) loss values.

Parameters:

  • base_model (SA) – The completed base model instance of SA.

  • data_handler (DataHandler) – The instance of the DataHandler user to preprocess the input data for SA.

  • softness (float) – The softness parameter that determines how large the Q(aux) loss value is in comparison to the primary Q loss.

add_constraint(constraint_type: str, index: tuple, target: str, target_value: float | None = None, min_value: float | None = None, max_value: float | None = None, dQ: float | None = None)#

Adds a single constraint to the ConstrainedModel instance. What constraints are available and valid structure of the constraint parameters can be found in the Constraint class. A factor element can only have one constraint.

Parameters:

  • constraint_type (str) – The type of constraint being added, there are 6 types which are detailed in the Constraint class.

  • index (tuple) – The index of the factor element (as they natively appear in either the H or W matrices). i.e. (i,j)

  • target (str) – The target factor element matrix. A factor feature element (H) is ‘feature’ while a factor sample element (W) is ‘sample’.

  • target_value (float) – The target value for pull to value constraint.

  • min_value (float) – The min value for the define limits constraint.

  • max_value (float) – The max value for the define limits constraint.

  • dQ (float) – The dQ value for the constraints with dQ limits.

Returns:

True if the constraint was added or False if the constraint wasn’t valid and is not added.

Return type:

bool

add_expression(expression)#

Add an expression to the constrained model. An expression is an equation involving 2 or more factor elements that quantifies the relationship between those factor elements. These expressions are structured as formatted strings, that take the form:

“(0.66*[factor:1|feature:2])-(4.2*[factor:2|feature:4])=0,250” “(0.35*[factor:0|feature:3])-(2.0*[factor:1|feature:3])-(3.7*[factor:3|feature:4])=0,250” “(3.2*[factor:2|feature:4])+(1.2*[factor:3|feature:10])+(0.1*[factor:1|feature:3])+(20.0*[factor:4|feature:3])-(10.7*[factor:5|feature:4])=0,250”

Where each element is defined inside of () and consist of a coefficient and the factor element, i.e. (COEF_ij*(factor:I|feature:J). Then the combination of factor elements are correlated by +/0- operators with the resulting equation equal to 0. The comma and following value is the dQ limit. These limits are summed for all expressions and used to decrease the amount of change these expressions can apply to the solution matrices if the expressions dQ is greater than that summed limit.

Parameters:

expression (str) – A string expression to be added to the list of expressions for the constrained model.

display_results()#

Print the results of the constrained model run.

evaluate_constraints()#

Evaluate and show the factor element constraint results of the constrained model run. TODO: Perform factor mapping between the base solution and the constrained solution.

evaluate_expressions()#

Evaluate and show the expression results of the constrained model run. TODO: Perform factor mapping between the base solution and the constrained solution.

list_constraints()#

List all the constraints that are currently set for this constrained model.

list_expressions()#

List all the current expressions assigned to the constrained model.

static load(file_path: str)#

Load a previously saved Constrained SA pickle file.

Parameters:

file_path (str) – File path to a previously saved Constrained SA pickle file

Returns:

On successful load, will return a previously saved Constrained SA object. Will return None on load fail.

Return type:

ConstrainedModel

plot_Q(Qtype: str = 'True')#

Plot the loss value Q as it changes over iterations. Four options for Qtype are available.

Parameters:

Qtype (str) – The Q loss value to plot. Available options are: true, robust, aux, and main. Q(Main) is the loss value of the objective function for the constrained model and is the sum of true and aux.

plot_contributions(factor_idx)#

Plot the constrained model factor contributions by factor index.

Parameters:

factor_idx (int) – The factor index to plot. Valid index values range from 1 to the total number of factors.

plot_factor_contributions(feature_idx, threshold: float = 0.06)#

Plot the constrained model factor contributions for a specified feature by feature index.

Parameters:

  • feature_idx (int) – The feature index to plot. Valid index range from 1 to the number of features in the model.

  • threshold (float) – The factor contribution threshold for a factor to be included in the plot.

plot_factor_fingerprints()#

Plot the constrained model factor fingerprints.

plot_g_space(factor_idx1, factor_idx2, show_base: bool = False, show_delta: bool = False)#

Plot the constrained model G-Space plot for two factors. Options include adding the base model values and/or adding the change of values from the base values and the constrained model.

Parameters:

  • factor_idx1 (int) – The first factor index to plot. Valid index values range from 1 to the total number of factors.

  • factor_idx2 (int) – The second factor index to plot. Valid index values range from 1 to the total number of factors.

  • show_base (bool) – Include the base model values in the plot.

  • show_delta (bool) – Include the change of the constrained model from the base model, will set show_base to True.

plot_profile(factor_idx)#

Plot the constrained model factor profile by index.

Parameters:

factor_idx (int) – The factor index to plot. Valid index values range from 1 to the total number of factors.

plot_profile_contributions(factor_idx)#

Plot the constrained model factor profile and factor contribution by index. The plots are similar to those available to SA models in the analysis module.

Parameters:

factor_idx (int) – The factor index to plot. Valid index values range from 1 to the total number of factors.

remove_constraint(constraint_label)#

Remove a constraint. When a constraint is added to a ConstrainedModel, a label is created for that constraint that is defined by: ‘factor:I|feature:K’ or ‘factor:I|sample:J’. The labels can also be found by listing the constraints.

Parameters:

constraint_label (str) – The label of the constraint to be removed.

remove_expression(expression_idx)#

Remove an expression from the current list of expressions by index.

Parameters:

expression_idx (int) – The index of the expression to remove, values from 0 to the number of expressions - 1.

save(model_name: str, output_directory: str, pickle_model: bool = False)#

Save the constrained model instance.

Parameters:

  • model_name (str) – The name to use for the constrained model save files.

  • output_directory – The output directory to save the constrained model instance to.

  • pickle_model (bool) – Pickle the constrained model, useful for reloading the instance. Default = False.

Returns:

The path to the output directory, if pickle=False or the path to the pickle file. If save fails returns None

Return type:

str

train(max_iterations: int = 20000, converge_delta: float = 0.01, converge_n: int = 10)#

Retrain the specified nmf model applying the constraints and expressions conditions on the solution and finding to calculate a new solution. If no arguments are provided, the values used in the base nmf model will be applied.

Prior to beginning the update iterations, all the expressions are processed and converted into data structures that will be used to solve those expressions.

For each iteration, the constraint and expression target values are calculated and two matrices are created which contain the difference between the curren value in those matrices and the target value. The expression target values are calculated first and then followed by the constraint values. The difference matrices are added to the solution matrices before being updated by the SA update algorithm that is used in the base model.

The model is considered converged when Q(Main) changes by less than converge_delta over converge_n iterations, where Q(Main) is defined as Q(main) = Q(True) + Q(aux). Q(aux) is defined as Q(aux) = sum(square(W_base + Difference_to_Target_W - W_i)/S_W) + sum(square(H_base + Difference_to_Target_H - H_i)/S_H).

The completed constrained model solution is assigned to the .constrained_model variable, which is an instance of SA. This constrained SA solution can then be passed into any of the error estimation methods in the same way as an SA solution from the BatchNMF instance.

Parameters:

  • max_iterations (int) – The maximum number of iterations to run the update procedure. Defaults to the value set in the base model.

  • converge_delta (float) – The change in Q that determines convergence. Defaults to the value set in the base model.

  • converge_n (int) – The number of iterations where the change in Q is less than converge_delta for the model to be considered converged.

class esat.rotational.constrained.Constraint(constraint_type: str, index: tuple, target: str, target_values=None)#

Bases: object

The constrained model takes a base SA solution and finds a new solution that applies both constraints and expressions. The Constraint class objects are created from the add_constraint method in the constrained model class. The constraint class does not need to be called directly.

Defines a constraint targeting a single factor element in the solution. There are 6 different constraint types: “pull down”, “pull up”, “pull to value”, “set to zero”, “set to base value”, “define limits”. A constraint must target a factor element in either the ‘sample’ or ‘feature’ solutions, which determines which matrix the provided index is targeting. The target_values of the constraint can take several forms depending on what constraint type is provided. Here are examples of each type and their target_values:

Constraint(constraint_type=’pull down’, index=(0,0), target=’feature’, target_values=dQ_limit) Constraint(constraint_type=’pull up’, index=(0,0), target=’feature’, target_values=dQ_limit) Constraint(constraint_type=’pull to value’, index=(0,0), target=’feature’, target_values=(pull_to_value, dQ_limit)) Constraint(constraint_type=’set to zero’, index=(0,0), target=’feature’) Constraint(constraint_type=’set to base value’, index=(0,0), target=’feature’) Constraint(constraint_type=’define limits’, index=(0,0), target=’feature’, target_values=(min_value, max_value))

These examples are created when a user calls the add_constraint method from a ConstrainedModel instance.

Parameters:

  • constraint_type (str) – The type of constraint that is being defined. Valid types are: “pull down”, “pull up”, “pull to value”, “set to zero”, “set to base value”, “define limits”.

  • index (tuple) – A tuple that specifies the index of the factor matrix that is being constrained.

  • target (str) – The target matrix for the constraint. Options are ‘feature’ (H) or ‘sample’ (W) matrices.

  • target_values – The target values for the constraint. The parameter type and value is dependent on the constraint type, details shown in the Constraint description.

describe(label)#

Prints the constraint details.

Parameters:

label (str) – The label or title of the constraint, created by the ConstrainedModel class.

tostring(label: str | None = None)#

Get string representation of the constraint.

Parameters:

label (str) – Optional label for the constraint.

Returns:

The constraint string.

Return type:

str

type_list = ('pull down', 'pull up', 'pull to value', 'set to zero', 'set to base value', 'define limits')#

Module contents#