Ensemble¶

class ompy.Ensemble(raw=None, bg=None, bg_ratio=1, path=None)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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>)[source]¶

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)[source]¶

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>)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

Loads a saved ensamble

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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)[source]¶

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

action_from_state(state)[source]

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)[source]

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)[source]

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>)[source]

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)[source]

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>)[source]

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)[source]

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)[source]

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)[source]

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)[source]

Loads a saved ensamble

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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