ResponseMatrixArrayBuilder

class remu.migration.ResponseMatrixArrayBuilder(nstat)

Class that generates consistent ndarrays from multiple response matrix objects.

Parameters

nstatint

The number of random matrices to be generated for each ResponseMatrix. If nstat is 0, no random matrices are generated. Instead the output of ResponseMatrix.get_response_matrix_as_ndarray() is used.

Notes

This class is used to generate the random response matrices from multiple toy simulations covering the detector uncertainties. Each toy simulation yields one ResponseMatrix object. These are then combined with the ResponseMatrixArrayBuilder.

The ResponseMatrixArrayBuilder is designed to use as little memory as possible. It stores only the necessary information of the ResponseMatrix, not the ResponseMatrix objects themselves. It only stores the truth bins that were actually filled.

The matrices must have been built using the same truth information! The filled bins may only differ in the nuisance bins. When creating the final ndarray, missing nuisance columns that were filled in some but not all matrices are filled with default values (0).

The relative efficiencies of the nuisance bins are guaranteed to be consistent between the different response matrices. The absolute value of the efficiencies is not conserved. In fact, the efficiency for nuisance bin j in ResponseMatrix t will be:

eff_tj = N_tj / max_t( N_tj)

where N_tj is the value of nuisance truth bin j in ResponseMatrix t. This means the efficiency of the nuisance bins can decrease with the number of added matrices. This has to be taken into account when creating truth templates for the nuisance bins. They should consist of the max of the selected nuisance events over the different toy simulations. This way, the template multiplied with the ndarray will re-create the number of selected nuisance events in each bin for all toy response matrices.

Attributes

nstat	(int) The number of statistical throws to generate for each added matrix.
nmatrices	(int) The number of matrices that were added.

Methods

add_matrix(response_matrix[, weight])	Add a matrix to the collection.
export(filename[, compress])	Save all necessary information for using the response matrix.
get_filled_truth_indices()	Return the list of filled truth indices.
get_mean_response_matrices_as_ndarray()	Get the mean response matrices as ndarray.
get_random_response_matrices_as_ndarray()	Get the response matrices as consistent ndarray.
get_truth_entries_as_ndarray()	Return the array of maximum entries in the truth bins.
reset()	Reset everything to 0.

add_matrix(response_matrix, weight=1.0)

Add a matrix to the collection.

Parameters

response_matrixResponseMatrix

weightfloat, optional

See also

ResponseMatrix.generate_random_response_matrices

Notes

This immediately triggers the generation of nstat random variations of response_matrix.

export(filename, compress=False)

Save all necessary information for using the response matrix.

Saves all necessary information for using the response matrix in a NumPy .npz archive.

Parameters

filenamestr or file

Where to store the arrays

compressbool, optional

Whether to use compression

See also

ResponseMatrix.export

get_filled_truth_indices()

Return the list of filled truth indices.

This list contains the indices of all truth bins that have been filled in at least one of the matrices that were added to the ResponseMatrixArrayBuilder.

get_mean_response_matrices_as_ndarray()

Get the mean response matrices as ndarray.

Returns

M, weightsndarray

A big ndarray containing nstat generated matrices for each ResponseMatrix that has been added, and a vector of weights for corresponding the matrices.

See also

get_random_response_matrices_as_ndarray

Notes

The returned matrices will only contain the columns, i.e. truth bins, that have been filled in at least one of the added ResponseMatrix objects. The shape of the returned array will be:

(#(RepsonseMatrices), #(reco bins), #(filled truth bins))

The indices of the returned (filled) truth bins can be requested with the get_filled_truth_indices() method.

get_random_response_matrices_as_ndarray()

Get the response matrices as consistent ndarray.

Returns

M, weightsndarray

A big ndarray containing nstat generated matrices for each ResponseMatrix that has been added, and a vector of weights for corresponding the matrices.

See also

get_mean_response_matrices_as_ndarray

Notes

The returned matrices will only contain the columns, i.e. truth bins, that have been filled in at least one of the added ResponseMatrix objects. The shape of the returned array will be:

(#(RepsonseMatrices) x nstat, #(reco bins), #(filled truth bins))

The indices of the returned (filled) truth bins can be requested with the get_filled_truth_indices() method.

get_truth_entries_as_ndarray()

Return the array of maximum entries in the truth bins.

reset()

Reset everything to 0.