ResponseMatrixArrayBuilder

class remu.migration.ResponseMatrixArrayBuilder(nstat)

Class that generates consistent ndarrays from multiple response matrix objects.

Parameters:

nstat : int

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 ResponseMatrices are then combined with a ResponseMatrixArrayBuilder.

The ResponseMatrixArrayBuilder is designed to use as little memory as possible. It stores only the necessary information of the ResponseMatrices, 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 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 / sum_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 decreases 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 sum 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.

add_matrix(response_matrix)

Add a matrix to the collection.

Parameters:

response_matrix : ResponseMatrix

See also

ResponseMatrix.generate_random_response_matrices

Notes

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

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:

ndarray

A big ndarray containing the mean matrix for each ResponseMatrix that has been added.

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 ResponseMatrices. 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:

ndarray

A big ndarray containing nstat generated matrices for each ResponseMatrix that has been added.

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 ResponseMatrices. The shape of the returned array will be:

(#(RepsonseMatrices), [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_response_values_as_ndarray()

Return the mean values of the response bins.

get_truth_entries_as_ndarray()

Return the array of maximum entries in the truth bins.

reset()

Reset everything to 0.