Ensemble

class ompy.Ensemble(raw=None, bg=None, bg_ratio=1, path='saved_run/ensemble')

Bases: object

Generates perturbated matrices to estimate uncertainty

Note

When adding any functionality that runs withing the parallelized loop make sure to use the random generator exposed via the arguments. If one uses np.random instead, this will be the same an exact copy for each process.

Variables:

• raw (Matrix) – The raw matrix used as model for the ensemble. If a background is provided, this will initially be the the “prompt+bg” matrix.

• bg – Background matrix to subtract.

• bg_ratio – Prompt is obtainied by raw - bg_ratio * bg. Defaults to 1.

• path (str) – The path used for saving the generated matrices.

• unfolder (Unfolder) – An instance of Unfolder which is used in the unfolding of the generated matrices. Only has to support obj.unfold(raw: Matrix).

• first_generation_method (FirstGeneration) – An instance of FirstGeneration for applying the first generation method to unfolded matrices. Only has to be callable with (unfolded: Matrix)

• regenerate (bool) – If true, regenerate the matrices instead of loading from path.

• std_raw (Matrix) – The computed standard deviation of the raw ensemble.

• std_unfolded (Matrix) – The computed standard deviation of the unfolded ensemble.

• std_firstgen (Matrix) – The computed standard deviation of the first generation method matrices.

• firstgen_ensemble (np.ndarray) – The entire firstgen ensemble.

• action_raw (Action[Matrix]) – An arbitrary action to apply to each generated raw matrix. Defaults to NOP.

• action_prompt_w_bg (Action[Matrix]) – An arbitrary action to apply to each generated prompt_w_bg matrix. Defaults to NOP.

• action_bg (Action[Matrix]) – An arbitrary action to apply to each generated bg matrix. Defaults to NOP.

• action_unfolded (Action[Matrix]) – An arbitrary action to apply to each generated unfolded matrix. Defaults to NOP.

• action_firstgen (Action[Matrix]) – An arbitrary action to apply to each generated firstgen matrix. Defaults to NOP.

• nprocesses (int) – Number of processes for multiprocessing. Defaults to number of available cpus-1 (with mimimum 1).

• seed (int) – Random seed for reproducibility of results

Todo

• Separate each step - generation, unfolded, firstgening?

• (Re)generation with book keeping is a recurring pattern. Try to abstract it away.

Sets up attributes and loads a saved ensemble if provided.

Parameters:

• raw (Optional[Matrix]) – The model matrix to peturbate. If a background is provided, this is the “prompt+bg” matrix.

• bg (Optional[Matrix]) – Background matrix to subtract.

• bg_ratio (float) – Prompt is obtainied by raw - bg_ratio * bg. Defaults to 1. This is the case for equal time gate length of prompt+bg and bg.

• path (Union[str, Path, None]) – The path where to save the ensemble. If set, the ensemble will try to load from the path, but will fail silently if it is unable to. It is recommended to call load([path]) explicitly.

Methods Summary

action_from_state(state)	Return the action corresponding to a given state :type state: str :param state: The state
first_generation(step, unfolded)	Applies first generation method to an unfolded matrix
generate(number[, method, regenerate])	Generates an ensemble of matrices and estimates standard deviation
generate_gaussian(state[, rstate])	Generates an array with Gaussian perturbations of a matrix.
generate_perturbed(step, method, state, rstate)	Generate a perturbated matrix
generate_poisson(state[, rstate])	Generates an array with Poisson perturbations of a matrix
get_firstgen(index)	Get the first generation matrix(ces) created in ensemble generation.
get_raw(index)	Get the raw matrix(ces) created in ensemble generation.
get_unfolded(index)	Get the unfolded matrix(ces) created in ensemble generation.
load([path])	Loads a saved ensamble.
load_matrix(path)	Check if file exists and should not be regenerated
matrix_from_state(state)	Return the matrix corresponding to a given state :type state: str :param state: The state
plot(*[, ax, vmin, vmax, add_cbar, scale_by])	Plot the computed standard deviations
rebin(out_array, member)	Rebins the first generations matrixes and recals std
step(step, rsequence, method)	Single step in self.generate
subtract_bg(step, matrix, bg)	Subtract bg from "raw" (prompt+bg) matrix
unfold(step, raw)	Unfolds the raw matrix

Methods Documentation

action_from_state(state)

Return the action corresponding to a given state :type state: str :param state: The state

Returns:

The corresponding action

Return type:

action

first_generation(step, unfolded)

Applies first generation method to an unfolded matrix

Looks for an already generated file before applying first generation. :type step: int :param step: The identifier of the matrix to unfold. :type unfolded: Matrix :param unfolded: The matrix to apply first generation method to.

Return type:

Matrix

Returns:

The resulting matrix

generate(number, method='poisson', regenerate=False)

Generates an ensemble of matrices and estimates standard deviation

Perturbs the initial raw matrix using either a Gaussian or Poisson process, unfolds them and applies the first generation method to them. Uses the variation to estimate standard deviation of each step.

Parameters:

• number (int) – The number of perturbed matrices to generate.

• method (str) – The stochastic method to use to generate the perturbations Can be ‘gaussian’ or ‘poisson’.

• regenerate (bool) – Whether to use already generated files (False) or generate them all anew (True).

Return type:

None

generate_gaussian(state, rstate=<built-in function default_rng>)

Generates an array with Gaussian perturbations of a matrix. Note that entries are truncated at 0 (only positive).

Parameters:

• state (str) – State of the matrx/which matrix should be taken as a base

• rstate (optional) – numpy random generator (random state)

Return type:

ndarray

Returns:

The resulting array

generate_perturbed(step, method, state, rstate)

Generate a perturbated matrix

Looks for an already generated file before generating the matrix.

Parameters:

• step (int) – The identifier of the matrix to generate

• method (str) – The name of the method to use. Can be either “gaussian” or “poisson”

• state (str) – Either “raw”, “prompt+bg” or “bg”.

• rstate (Generator) – numpy random generator (random state)

Return type:

Matrix

Returns:

The generated matrix

generate_poisson(state, rstate=<built-in function default_rng>)

Generates an array with Poisson perturbations of a matrix

Parameters:

• state (str) – State of the matrx/which matrix should be taken as a base

• rstate (optional) – numpy random generator (random state)

Return type:

ndarray

Returns:

The resulting array

get_firstgen(index)

Get the first generation matrix(ces) created in ensemble generation.

Parameters:

index (Union[int, List[int]]) – The index of the ensemble. If an iterable, a list of matrices will be returned.

Return type:

Union[Matrix, List[Matrix]]

Returns:

The matrix(ces) corresponding to index(ces)

get_raw(index)

Get the raw matrix(ces) created in ensemble generation.

Parameters:

index (Union[int, List[int]]) – The index of the ensemble. If an iterable, a list of matrices will be returned.

Return type:

Union[Matrix, List[Matrix]]

Returns:

The matrix(ces) corresponding to index(ces)

get_unfolded(index)

Get the unfolded matrix(ces) created in ensemble generation.

Parameters:

index (Union[int, List[int]]) – The index of the ensemble. If an iterable, a list of matrices will be returned.

Return type:

Union[Matrix, List[Matrix]]

Returns:

The matrix(ces) corresponding to index(ces)

load(path=None)

Loads a saved ensamble. Alternative to regenerate.

Currently only supports ‘.npy’ format.

Parameters:

path (Union[str, Path, None]) – The path to the ensemble directory. If the value is None, ‘self.path’ will be used.

load_matrix(path)

Check if file exists and should not be regenerated

Parameters:

path (Union[Path, str]) – Path to file to load

Return type:

Optional[Matrix]

Returns:

Matrix if file exists and can be loaded, None otherwise.

matrix_from_state(state)

Return the matrix corresponding to a given state :type state: str :param state: The state

Returns:

The corresponding matrix

Return type:

Matrix

plot(*, ax=None, vmin=None, vmax=None, add_cbar=True, scale_by='all', **kwargs)

Plot the computed standard deviations

Parameters:

• ax (optional) – A matplotlib axis to plot onto.

• vmin (optional, float) – The lower cutoff for colors.

• vmax (optional, float) – The upper cutoff for colors.

• add_cbar (optional, bool) – Whether to add a colorbar. Defaults to True.

• scale_by (optional, str) – Which std matrix to set color limits by. Can be “raw”, “unfolded”, “firstgen” or “all”. Defaults to “all”.

Return type:

Tuple[Any, ndarray]

Returns:

The matplotlib figure and axis

rebin(out_array, member)

Rebins the first generations matrixes and recals std

Parameters:

• out_array (ndarray) – mid-bin energy calibration of output matrix along rebin axis

• member (str) – which member to rebin, currently only FG available

Return type:

None

step(step, rsequence, method)

Single step in self.generate

Parameters:

• step (int) – step (loop) number

• rsequence (np.random.SeedSequence) – SeedSequence for random seed

• method (str) – see self.generate

Returns:

raw, unfolded, firstgen

subtract_bg(step, matrix, bg)

Subtract bg from “raw” (prompt+bg) matrix

Looks for an already generated file before generating the matrix. :type step: int :param step: The identifier of the matrix to act on. :type matrix: Matrix :param matrix: The matrix to subtract from (usually, prompt+bg) :type bg: Matrix :param bg: The bg matrix.

Returns:

The prompts only matrix (“raw” matrix).

Return type:

raw

unfold(step, raw)

Unfolds the raw matrix

Looks for an already generated file before generating the matrix. :type step: int :param step: The identifier of the matrix to unfold. :type raw: Matrix :param raw: The raw matrix to unfold

Return type:

Matrix

Returns:

The unfolded matrix