lightcurvelynx.graph_state

A collection of sampled parameters from a statistic distribution.

Model parameters are random variables that are sampled together in a joint distribution using a graph of dependencies. For example, the functions:

f(a, b) = x
g(c) = y
h(x, y) = z

indicate that x depends on a and b, y depends on c, and z depends on x and y (and thus on a, b, and c as well). These would form a graph that looks like:

a - \
     x -- \
b - /      \
            z
c -- y --- /

Within LightCurveLynx, variables are grouped into logical sets called nodes. The combination of node name and variable name are used to indicate specific values, allowing us to use the same variable names in multiple nodes. For example a node to generate samples from a Gaussian distribution may have internal parameters called mean and scale that might take on different values depending on what the node is generating. We could have one mean for an object’s brightness and another for its positional relative to the center of a host galaxy.

Classes

`GraphState`	A class to hold the state(s) of the each variable for one or more samples of the random
`DependencyGraph`	A class to hold the dependencies between parameters in a model. Used for

Functions

transpose_dict_of_list(input_dict, num_elem)

Transpose a dictionary of iterables to a list of dictionaries.

Module Contents

class GraphState(num_samples=1, *, sample_offset=0)[source]

A class to hold the state(s) of the each variable for one or more samples of the random variables in the graph. Each entry is indexed by a combination of node’s (unique) name and variable’s name. This allows nodes to have parameters with the same name, such as ra and dec.

states[source]

A dictionary of dictionaries mapping the node’s string and variable name to either a value or array of values for that parameters.

Type:: dict

num_samples[source]

A count of the number of samples stored in the GraphState. If num_samples > 1, then all parameters are stored as arrays of length num_samples. If num_samples == 1, then all parameters are stored as scalars.

Type:: int

num_parameters[source]

The total number of parameters stored in a single sample within GraphState.

Type:: int

fixed_vars[source]

A dictionary mapping the node name to a set of the variable names that are fixed (not changed by resampling) in this GraphState instance. This is used for presetting certain parameters to fixed values (such as during automatic differentiation). Nodes are only included if they have at least one fixed variable.

Type:: dict

sample_offset[source]

An optional offset to add to the graph state for any stateful nodes. Default: 0

Type:: int

sample_idx[source]

An optional index of the current sample within a larger set of samples. Only used when we have extracted a single sample from a multi-sample GraphState. Default: None

Type:: int or None

num_samples = 1[source]

num_parameters = 0[source]

states[source]

fixed_vars[source]

sample_offset = 0[source]

sample_idx = None[source]

__len__()[source]

__next__()[source]

__iter__()[source]

__contains__(key)[source]

Check if the GraphState contains an entry.

The key can be:

the name of a node (in which case we return True if the node exists),
the full name of a parameter (in which case we return True if the combination of node and parameter exists), or
the name of a parameter in a GraphState with a single node (in which case we return True if the parameter exists in that node).

Parameters:: key (str) – The name of the entry to check.

__str__()[source]

__eq__(other)[source]

__getitem__(key)[source]

Access an entry in the GraphState.

The key can be:

the name of a node (in which case we return that node’s dictionary of parameter_name -> value),
the full name of a parameter (in which case we return the values), or
the name of a parameter in a GraphState with a single node (in which case we return that parameter’s values).

Parameters:: key (str) – The name of the entry to access.

copy()[source]

Create a deep copy of the GraphState.

Returns:: The copied GraphState.
Return type:: GraphState

static extended_param_name(node_name, param_name)[source]

A helper function to create the full parameter name.

Parameters:

node_name (str) – The name of the node.
param_name (str) – The name of the parameter.

Returns:

extended – A name of the form {node_name}.{param_name}

Return type:

str

classmethod from_table(input_table)[source]

Create the GraphState from an AstroPy Table with columns for each parameter and column names of the form ‘{node_name}.{param_name}’.

Parameters:: input_table (astropy.table.Table) – The input table.

classmethod from_file(filename)[source]

Create the GraphState from a saved file.

Parameters:: filename (str or Path) – The name of the file.

classmethod from_dict(data, num_samples=1)[source]

Create a GraphState from either a flattened dictionary, where the keys of the dictionary are {node_name}.{param_name}, or a nested dictionary, where data[node_name][param_name] = value.

Parameters:

data (dict) – The dictionary mapping the parameter identifier (node name and parameter name) to their values.
num_samples (int) – The number of samples. Default: 1

Returns:

The corresponding graph state.

Return type:

GraphState

classmethod from_pyarrow_struct_array(struct_array, num_samples=1)[source]

Create a GraphState from a PyArrow StructArray with fields for each parameter and field names of the form ‘{node_name}.{param_name}’.

Parameters:

struct_array (pyarrow.StructArray) – The input StructArray.
num_samples (int) – The number of samples. Default: 1

classmethod from_list(data)[source]

Concatenate a list of GraphStates or single state dictionaries into a single GraphState. All the entries in the data must have the same set of parameters (keys).

Parameters:: data (list of GraphState or dict) – A list of the individual GraphState information to combine.
Returns:: The corresponding graph state.
Return type:: GraphState

get_all_params_names()[source]

Get the full name of all the parameters.

Returns:: names – A list of all the parameter names.
Return type:: list

get_node_state(node_name, sample_num=0)[source]

Get a dictionary of all parameters local to the given node for a single sample state.

Parameters:

node_name (str) – The parent node whose variables to extract.
sample_num (int) – The number of sample to extract.

Returns:

values – A dictionary mapping the parameter name to its value.

Return type:

dict

set(node_name, var_name, value, force_copy=False, fixed=False)[source]

Set a (new) parameter’s value(s) in the GraphState from a given constant value or an array of length num_samples (to set all the values at once).

Parameters:

node_name (str) – The parent node holding this variable.
var_name (str) – The parameter’s name.
value (any) – The new value of the parameter.
force_copy (bool) – Make a copy of data in an array. If set to False, this will link to the array, saving memory and computation time. Default: False
fixed (bool) – Treat this parameter as fixed and do not change it during subsequent calls to set. It is recommended not to manually set this to True as it can cause difficult to debug issues. It is primarily intended for use in automatic differentiation. Default: False

update(inputs, force_copy=False, all_fixed=False)[source]

Set multiple parameters’ value in the GraphState from a GraphState or a dictionary of the same form.

Note

The number of samples in input must either match the number of samples in the current object or be 1.

Parameters:

inputs (GraphState or dict) – Values to copy.
force_copy (bool) – Make a copy of data in an array. If set to False, this will link to the array, saving memory and computation time. Default: False
all_fixed (bool) – Treat all the parameters in inputs as fixed. Default: False

Raises:

ValueError – If the input an invalid number of samples.

extract_single_sample(sample_num)[source]

Create a new GraphState with a single sample state and all scalar values.

Parameters:: sample_num (int) – The number of sample to extract.

extract_parameters(params)[source]

Extract the parameter value(s) by a given name. This is often used for recording the important parameters from an entire model (set of nodes).

Parameters:: params (str or list-like, optional) – The parameter names to extract. These can be full names (“node.param”) or use the parameter names.
Returns:: values – The resulting dictionary.
Return type:: dict

to_table()[source]

Flatten the graph state to an AstroPy Table with columns for each parameter.

The column names are: {node_name}.{param_name}

Returns:: values – The resulting Table.
Return type:: astropy.table.Table

to_dict()[source]

Flatten the graph state to a dictionary with columns for each parameter.

The column names are: {node_name}.{param_name}

Returns:: values – The resulting dictionary.
Return type:: dict

to_pyarrow_struct_array()[source]

Flatten the graph state to a PyArrow StructArray with fields for each parameter.

The column names are: {node_name}.{param_name}

Returns:: values – The resulting StructArray.
Return type:: pyarrow.StructArray

save_to_file(filename, overwrite=False)[source]

Save the GraphState to a file.

Parameters:

filename (str) – The name of the file to save.
overwrite (bool) – Whether to overwrite an existing file. Default: False

class DependencyGraph[source]

A class to hold the dependencies between parameters in a model. Used for analysis, documentation, testing, and visualization of the model structure. The full parameter names are in the same form used by GraphState.

all_params[source]

A set of all (full) parameter names in the graph.

Type:: set

all_nodes[source]

A set of all node names in the graph.

Type:: set

incoming[source]

A dictionary mapping each parameter to the set of parameters that it depends on (the incoming edges).

Type:: dict

outgoing[source]

A dictionary mapping each parameter to the set of parameters that depend on it (the outgoing edges).

Type:: dict

num_constants[source]

The number of constant parameters in the graph.

Type:: int

all_params[source]

all_nodes[source]

incoming[source]

outgoing[source]

num_constants = 0[source]

__len__()[source]

__contains__(full_param_name)[source]

add_parameter(param_name, node_name=None)[source]

Add a parameter to the dependency graph if it is not already present.

Parameters:

param_name (str) – The name of the parameter to add.
node_name (str, optional) – The name of the node holding this parameter. If provided, the full parameter name will be in the same form used by GraphState for storage. Default: None

add_constant(value)[source]

Add a constant parameter to the dependency graph.

Parameters:: value (any) – The value of the constant.
Returns:: const_name – The name of the constant parameter added to the graph.
Return type:: str

add_edge(from_param, to_param)[source]

Add a directed edge to the dependency graph.

Parameters:

from_param (str) – The name of the parameter that the edge is coming from (the dependency).
to_param (str) – The name of the parameter that the edge is going to (the dependent).

build_subgraph(param_name, incoming=True, outgoing=True)[source]

Get the DAG subgraph that contains this parameter. This can be: 1) the parameters on which this parameter depends (incoming=True, outgoing=False), 2) the parameters that depend on this parameter (incoming=False, outgoing=True), or 3) all parameters in the same connected component as this parameter (incoming=True, outgoing=True).

Parameters:

param_name (str) – The name of the parameter to get the subgraph for.
incoming (bool) – If True, include the parameters that have incoming edges to nodes in the subgraph. Default: True
outgoing (bool) – If True, include the parameters that have outgoing edges from nodes in the subgraph. Default: True

Returns:

subgraph – The resulting subgraph.

Return type:

DependencyGraph

build_connected_components()[source]

Get the DAG subgraphs that are the connected components of the graph.

Returns:: components – The resulting subgraphs.
Return type:: list of DependencyGraph

compute_depths()[source]

Compute the depth of each parameter in the graph.

Note

This function is primarily used for visualization purposes.

Returns:: depths – A dictionary mapping parameter names to their depth.
Return type:: dict

to_networkx()[source]

Create a NetworkX graph from the dependency graph.

Returns:: graph – The resulting directed graph.
Return type:: networkx.DiGraph

draw(param_name=None)[source]: Draw the connected components of the graph using NetworkX and Matplotlib.

transpose_dict_of_list(input_dict, num_elem)[source]

Transpose a dictionary of iterables to a list of dictionaries.

Parameters:

input_dict (dict) – A dictionary of iterables, each of which is length num_elem.
num_elem (int) – The length of the iterables.

Returns:

output_list – A length num_elem list of dictionaries, each with the same keys mapping to a single value.

Return type:

list

Raises:

ValueError – If any of the iterables have different lengths.