Containers of Patterns

Containers of patterns are themselves patterns, and so can contain instantiations of themselves.

Dictionaries of Patterns

class paragami.pattern_containers.PatternDict(free_default=None)

A dictionary of patterns (which is itself a pattern).

Examples

import paragami

# Add some patterns.
dict_pattern = paragami.PatternDict()
dict_pattern['vec'] = paragami.NumericArrayPattern(shape=(2, ))
dict_pattern['mat'] = paragami.PSDSymmetricMatrixPattern(size=3)

# Dictionaries can also contain dictionaries (but they have to
# be populated /before/ being added to the parent).
sub_dict_pattern = paragami.PatternDict()
sub_dict_pattern['vec1'] = paragami.NumericArrayPattern(shape=(2, ))
sub_dict_pattern['vec2'] = paragami.NumericArrayPattern(shape=(2, ))
dict_pattern['sub_dict'] = sub_dict_pattern

# We're done adding patterns, so lock the dictionary.
dict_pattern.lock()

# Get a random intial value for the whole dictionary.
dict_val = dict_pattern.random()
print(dict_val['mat']) # Prints a 3x3 positive definite numpy matrix.

# Get a flattened value of the whole dictionary.
dict_val_flat = dict_pattern.flatten(dict_val, free=True)

# Get a new random folded value of the dictionary.
new_dict_val_flat = np.random.random(len(dict_val_flat))
new_dict_val = dict_pattern.fold(new_dict_val_flat, free=True)

Methods

lock: Prevent additional patterns from being added or removed.
__init__(free_default=None)
Parameters:
flat_length : int

The length of a non-free flattened vector.

free_flat_length : int

The length of a free flattened vector.
as_dict()

Return a dictionary of attributes describing the pattern.

The dictionary should completely describe the pattern in the sense that if the contents of two patterns’ dictionaries are identical the patterns should be considered identical.

If the keys of the returned dictionary match the arguments to __init__, then the default methods for to_json and from_json will work with no additional modification.

empty(valid)

Return an empty parameter in its folded shape.

Parameters:
valid : bool

Whether or folded shape should be filled with valid values.
Returns:
folded_val : Folded value

A parameter value in its original folded shape.
flat_indices(folded_bool, free=None)

Get which flattened indices correspond to which folded values.

Parameters:
folded_bool : Folded booleans

A variable in the folded shape but containing booleans. The elements that are True are the ones for which we will return the flat indices.

free : bool

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.
Returns:
indices : numpy.ndarray (N,)

A list of indices into the flattened value corresponding to the True members of folded_bool.
flatten(folded_val, free=None, validate_value=None)

Flatten a folded value into a flat vector.

Parameters:
folded_val : Folded value

The parameter in its original folded shape.

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.
Returns:
flat_val : numpy.ndarray, (N, )

The flattened value.
fold(flat_val, free=None, validate_value=None)

Fold a flat value into a parameter.

Parameters:
flat_val : numpy.ndarray, (N, )

The flattened value.

free : bool, optional.

Whether or not the flattened value is a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool, optional.

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.
Returns:
folded_val : Folded value

The parameter value in its original folded shape.
freeing_jacobian(folded_val, sparse=True)

The Jacobian of the map from a flat free value to a flat value.

If the folded value of the parameter is val, val_flat = flatten(val, free=False), and val_freeflat = flatten(val, free=True), then this calculates the Jacobian matrix d val_free / d val_freeflat. For entries with no dependence between them, the Jacobian is taken to be zero.

Parameters:
folded_val : Folded value

The folded value at which the Jacobian is to be evaluated.

sparse : bool, optional

Whether to return a sparse or a dense matrix.
Returns:
``numpy.ndarray``, (N, M)

The Jacobian matrix d val_free / d val_freeflat. Consistent with standard Jacobian notation, the elements of val_free correspond to the rows of the Jacobian matrix and the elements of val_freeflat correspond to the columns.

See also

Pattern.unfreeing_jacobian

classmethod from_json(json_string)

Return a pattern from json_string created by to_json.

See also

Pattern.to_json

unfreeing_jacobian(folded_val, sparse=True)

The Jacobian of the map from a flat value to a flat free value.

If the folded value of the parameter is val, val_flat = flatten(val, free=False), and val_freeflat = flatten(val, free=True), then this calculates the Jacobian matrix d val_freeflat / d val_free. For entries with no dependence between them, the Jacobian is taken to be zero.

Parameters:
folded_val : Folded value

The folded value at which the Jacobian is to be evaluated.

sparse : bool, optional

If True, return a sparse matrix. Otherwise, return a dense numpy 2d array.
Returns:
``numpy.ndarray``, (N, N)

The Jacobian matrix d val_freeflat / d val_free. Consistent with standard Jacobian notation, the elements of val_freeflat correspond to the rows of the Jacobian matrix and the elements of val_free correspond to the columns.

See also

Pattern.freeing_jacobian

validate_folded(folded_val, validate_value=None)

Check whether a folded value is valid.

Parameters:
folded_val : Folded value

A parameter value in its original folded shape.

validate_value : bool

Whether to validate the value in addition to the shape. The shape is always validated.
Returns:
is_valid : bool

Whether folded_val is an allowable shape and value.

err_msg : str

Arrays of Patterns

class paragami.pattern_containers.PatternArray(array_shape, base_pattern, free_default=None)

An array of a pattern (which is also itself a pattern).

The first indices of the folded pattern are the array and the final indices are of the base pattern. For example, if shape=(3, 4) and base_pattern = PSDSymmetricMatrixPattern(size=5), then the folded value of the array will have shape (3, 4, 5, 5), where the entry folded_val[i, j, :, :] is a 5x5 positive definite matrix.

Currently this can only contain patterns whose folded values are numeric arrays (i.e., NumericArrayPattern, SimplexArrayPattern, and PSDSymmetricMatrixPattern).

__init__(array_shape, base_pattern, free_default=None)
Parameters:
array_shape: tuple of int

The shape of the array (not including the base parameter)

base_pattern:

The base pattern.
array_shape()

The shape of the array of parameters.

This does not include the dimension of the folded parameters.

as_dict()

Return a dictionary of attributes describing the pattern.

The dictionary should completely describe the pattern in the sense that if the contents of two patterns’ dictionaries are identical the patterns should be considered identical.

If the keys of the returned dictionary match the arguments to __init__, then the default methods for to_json and from_json will work with no additional modification.

empty(valid)

Return an empty parameter in its folded shape.

Parameters:
valid : bool

Whether or folded shape should be filled with valid values.
Returns:
folded_val : Folded value

A parameter value in its original folded shape.
flat_indices(folded_bool, free=None)

Get which flattened indices correspond to which folded values.

Parameters:
folded_bool : Folded booleans

A variable in the folded shape but containing booleans. The elements that are True are the ones for which we will return the flat indices.

free : bool

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.
Returns:
indices : numpy.ndarray (N,)

A list of indices into the flattened value corresponding to the True members of folded_bool.
flat_length(free=None)

Return the length of the pattern’s flattened value.

Parameters:
free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, free_default is used.
Returns:
length : int

The length of the pattern’s flattened value.
flatten(folded_val, free=None, validate_value=None)

Flatten a folded value into a flat vector.

Parameters:
folded_val : Folded value

The parameter in its original folded shape.

free : bool, optional

Whether or not the flattened value is to be in a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.
Returns:
flat_val : numpy.ndarray, (N, )

The flattened value.
fold(flat_val, free=None, validate_value=None)

Fold a flat value into a parameter.

Parameters:
flat_val : numpy.ndarray, (N, )

The flattened value.

free : bool, optional.

Whether or not the flattened value is a free parameterization. If not specified, the attribute free_default is used.

validate_value : bool, optional.

Whether to check that the folded value is valid. If None, the pattern will employ a default behavior.
Returns:
folded_val : Folded value

The parameter value in its original folded shape.
freeing_jacobian(folded_val, sparse=True)

The Jacobian of the map from a flat free value to a flat value.

If the folded value of the parameter is val, val_flat = flatten(val, free=False), and val_freeflat = flatten(val, free=True), then this calculates the Jacobian matrix d val_free / d val_freeflat. For entries with no dependence between them, the Jacobian is taken to be zero.

Parameters:
folded_val : Folded value

The folded value at which the Jacobian is to be evaluated.

sparse : bool, optional

Whether to return a sparse or a dense matrix.
Returns:
``numpy.ndarray``, (N, M)

The Jacobian matrix d val_free / d val_freeflat. Consistent with standard Jacobian notation, the elements of val_free correspond to the rows of the Jacobian matrix and the elements of val_freeflat correspond to the columns.

See also

Pattern.unfreeing_jacobian

classmethod from_json(json_string)

Return a pattern from json_string created by to_json.

See also

Pattern.to_json

shape()

The shape of a folded value.

unfreeing_jacobian(folded_val, sparse=True)

The Jacobian of the map from a flat value to a flat free value.

If the folded value of the parameter is val, val_flat = flatten(val, free=False), and val_freeflat = flatten(val, free=True), then this calculates the Jacobian matrix d val_freeflat / d val_free. For entries with no dependence between them, the Jacobian is taken to be zero.

Parameters:
folded_val : Folded value

The folded value at which the Jacobian is to be evaluated.

sparse : bool, optional

If True, return a sparse matrix. Otherwise, return a dense numpy 2d array.
Returns:
``numpy.ndarray``, (N, N)

The Jacobian matrix d val_freeflat / d val_free. Consistent with standard Jacobian notation, the elements of val_freeflat correspond to the rows of the Jacobian matrix and the elements of val_free correspond to the columns.

See also

Pattern.freeing_jacobian

validate_folded(folded_val, validate_value=None)

Check whether a folded value is valid.

Parameters:
folded_val : Folded value

A parameter value in its original folded shape.

validate_value : bool

Whether to validate the value in addition to the shape. The shape is always validated.
Returns:
is_valid : bool

Whether folded_val is an allowable shape and value.

err_msg : str