pygama.evt package#

Utilities for grouping hit data into events.

Submodules#

pygama.evt.build_tcm module#

pygama.evt.build_tcm.build_tcm(input_tables: list[tuple[str, str]], coin_col: str, hash_func: str = '\\d+', coin_window: float = 0, window_ref: str = 'last', out_file: Optional[str] = None, out_name: str = 'tcm', wo_mode: str = 'write_safe') → Table#

Build a Time Coincidence Map (TCM).

Given a list of input tables, create an output table containing an entry list of coincidences among the inputs. Uses evt.tcm.generate_tcm_cols(). For use with the DataLoader.

Parameters:

  • input_tables (list[tuple[str, str]]) – each entry is (filename, table_name_pattern). All tables matching table_name_pattern in filename will be added to the list of input tables.

  • coin_col (str) – the name of the column in each tables used to build coincidences. All tables must contain a column with this name.

  • hash_func (str) – mapping of table names to integers for use in the TCM. hash_func is a regexp pattern that acts on each table name. The default hash_func r"\d+" pulls the first integer out of the table name. Setting to None will use a table’s index in input_tables.

  • coin_window (float) – the clustering window width.

  • window_ref (str) – Configuration for the clustering window.

  • out_file (Optional[str]) – name (including path) for the output file. If None, no file will be written; the TCM will just be returned in memory.

  • out_name (str) – name for the TCM table in the output file.

  • wo_mode (str) – mode to send to write_object().

Return type:

Table

See also

tcm.generate_tcm_cols

pygama.evt.tcm module#

pygama.evt.tcm.generate_tcm_cols(coin_data: list[numpy.ndarray], coin_window: float = 0, window_ref: str = 'last', array_ids: Optional[list[int]] = None, array_idxs: Optional[list[int]] = None) → dict[numpy.ndarray]#

Generate the columns of a time coincidence map.

Generate the columns of a time coincidence map from a list of arrays of coincidence data (e.g. hit times from different channels). Returns 3 equal-length numpy.ndarrays containing the coincidence index (e.g. event number), array ID (e.g. channel number), and array index (e.g. hit ID). These can be used to retrieve other data at the same tier as the input data into coincidence structures.

Makes use of pandas.concat(), pandas.DataFrame.sort_values(), pandas.DataFrame.groupby(), and pandas.DataFrame.cumsum()/pandas.DataFrame.count() functions:

  • pull data into a pandas.DataFrame

  • sort events by strictly ascending value of coin_col

  • group hits if the difference in coin_data is less than coin_window

Parameters:

  • coin_data (list[numpy.ndarray]) – a list of arrays of the data to be clustered.

  • coin_window (float) – the clustering window width. coin_data within the coin_window get aggregated into the same coincidence cluster. A value of 0 means an equality test.

  • window_ref (str) –

    when testing one datum for inclusion in a cluster, test if it is within coin_window of

    • "first" – the first element in the cluster (rigid window width)

    • "last" – the last element in the cluster (window grows until two data are separated by more than coin_window)

  • array_ids (Optional[list[int]]) – if provided, use array_ids in place of “index in coin_data” as the integer corresponding to each element of coin_data (e.g. a channel number).

  • array_idxs (Optional[list[int]]) – if provided, use these values in places of the DataFrame index for the return values of array_idx.

Returns:

col_dict – keys are coin_idx, array_id, and array_idx. coin_idx specifies which rows of the output arrays correspond to the which coincidence event array_id and array_idx specify the location in coin_data of each datum belonging to the coincidence event.

Return type:

dict[numpy.ndarray]