API

General

Utilities for processing data from the Large Area Time-Resolved Detector

This module provides tools to interpret NeXus-like data in HDF5 format from the experimental Timepix-based event-mode detector, codenamed Tristan, at Diamond Light Source.

class tristan.WithLocalDistributedCluster(*args, **kwargs)[source]

Bases: ContextDecorator

A decorator to run a function in a distributed.Client context.

Example

Using this decorator like so

>>> @WithLocalDistributedCluster()
... def foo(*args):
...     ...

is equivalent to

>>> def foo(*args):
...     with Client(processes=False):
...         ...

tristan.compute_with_progress(*collection, gather=False)[source]

Compute Dask collections, showing a progress bar, assuming a distributed client.

Parameters:

collection – A Dask object or built-in collection of objects.
gather – If true, return the computed result.

Binning

Tools for binning events to images.

tristan.binning.align_bins(start: int, align: int, end: int, n_bins: int) → tuple[int, int][source]

Divide an interval into a specified number of bins, aligning with a given value.

Take three integers, start ≤ align ≤ end, and find a way to span the largest possible interval between start and end with a specified number of bins, while ensuring that one of the bin edges is aligned with a specified value.

Parameters:

start – The start of the interval.
align – The value to which a bin edge should be aligned.
end – The end of the interval.
n_bins – The number of bins.

Returns:

The first bin edge and the bin width, from which all the bin edges can be derived.

Cache the contents of array in cache by addition.

If array is a sparse.COO, write to the cache more efficiently by writing only the non-null data.

Parameters:

array – Array to be added to the cache. This may be sparse.
cache – Cache to which array should be added. This must be dense. This may be a Zarr array or HDF5 dataset, if an on-disk cache is necessary. If a tristan.storage.IAddArray, the inplace addition sycnhronisation method will be used.

Bin a chunk of events to a partial image or image stack and cache the result.

Parameters:

coords – The coordinates of each event.
shape – The shape of the image or image stack.
cache – Cache to which array should be added. This must be dense. This may be a Zarr array or HDF5 dataset, if an on-disk cache is necessary. If a tristan.storage.IAddArray, the inplace addition sycnhronisation method will be used.

Construct a stack of images from events data.

From a sequence of LATRD events data, bin the events to images and store the binned images in a cache array. The cache may be backed with on-disk storage, as in the case of a Zarr array, or may be a simple in-memory object, like a NumPy array.

Parameters:

data – LATRD events data. Must have columns event_id and event_time_offset. Column order must be the order of dimensions in the resulting image array, i.e. (..., event_time_offset, event_id) where ... are optional extra columns. The number of columns should be one fewer than the length of shape becasue event_id is decoded into two dimensions, the slow and fast axes of the image.
bins – The time bin edges of the images (in clock cycles, to match the event timestamps).
shape – The shape of the image stack.
cache – An array representing the eventual image stack, having shape (len(bins) - 1, *image_size), to which the pixel counts from this binning operation will be added.

Returns:

A Dask collection representing the lazy image binning computation.

tristan.binning.find_preceding_bin_edge(a: ndarray[Any, dtype[_ScalarType_co]], bins: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]][source]

From sorted bin edges, find the bin edge preceding each value in an array.

Parameters:

a – An array of values for which corresponding preceding bin edges are sought.
bins – A sorted array of bin edges.

Returns:

An array with the same length as a. Each entry is the bin edge immediately preceding the corresponding entry in a.

tristan.binning.find_preceding_bin_edge_index(a: ndarray[Any, dtype[_ScalarType_co]], bins: ndarray[Any, dtype[_ScalarType_co]]) → ndarray[Any, dtype[_ScalarType_co]][source]

From sorted bin edges, find the index of the bin edge preceding each value in an array.

Parameters:

a – An array of values for which we seek the the indices in bin of the preceding bin edges.
bins – A sorted array of bin edges.

Returns:

An array with the same length as a. Each entry is the index in bins of the bin edge immediately preceding the corresponding entry in a.

tristan.binning.find_time_bins(data: DataFrame, bins: Sequence[int])[source]

Convert the event timestamps in LATRD data to time bin indices.

For each event, determine the index of the bin into which the event will fall.

Parameters:

data – LATRD events data. Must have an event_time_offset column.
bins – The time bin edges of the images (in clock cycles, to match the event timestamps).

Returns:

A DataFrame which matches the input data except that the event_time_offset column is replaced with a column of time_bin indices.

Bin LATRD events data into images of event counts.

Given an array of events data, and a known shape of the image or stack of images to which the events should be binned, bin the events to images, with pixel intensities recording the number of events recorded at each pixel.

shape should have length n_dims ≥ 2, representing the dimensions of the image or stack of images. Events will first be binned into a (stack of) flattened image(s), i.e. having dimensions (*shape[:-2], shape[-2] * shape[-1]) before being reshaped to shape.

coords should have shape (n_dims - 1, n_events), where n_events is the number of events. The last column, coords[-1], should contain each event’s pixel index in the flattened array of the image (i.e. for a 20px × 30px image, the values would run from 0 to 599).

Parameters:

coords – The coordinates of each event.
shape – The shape of the image or image stack.

Data

Tools for extracting data on cues and events from Tristan data files.

tristan.data.cue_times(data: DataFrame, message: uint16, after: int | None = None, before: int | None = None) → ndarray[source]

Find the timestamps of all instances of a cue message in a Tristan data set.

The found timestamps are de-duplicated and sorted.

Parameters:

data – A DataFrame of LATRD data. Must contain one column for cue id messages and one for cue timestamps.
message – The message code, as defined in the Tristan standard.
after – Ignore instances of the specified message before this timestamp.

Returns:

The timestamps, measured in clock cycles from the global synchronisation signal, de-duplicated and sorted in ascending order.

tristan.data.find_start_end(data: DataFrame) → tuple[int, int][source]

Find the shutter open and shutter close timestamps.

Parameters:: data – LATRD data. Must contain one ‘cue_id’ entry and one ‘cue_timestamp_zero’ entry. The two arrays are assumed to have the same length.
Returns:: The shutter open and shutter close timestamps, in clock cycles.

tristan.data.first_cue_time(data: DataFrame, message: uint16, after: uint64 | None = None) → uint64 | None[source]

Find the timestamp of the first instance of a cue message in a Tristan data set.

Parameters:

data – LATRD data. Must contain one ‘cue_id’ column and one ‘cue_timestamp_zero’ column. The two arrays are assumed to have the same length.
message – The message code, as defined in the Tristan standard.
after – Ignore instances of the specified message before this timestamp.

Returns:

The timestamp, measured in clock cycles from the global synchronisation signal. If the message doesn’t exist in the data set, this returns None.

tristan.data.latrd_data(path: str | Path, keys: Iterable[str]) → DataFrame[source]

Read LATRD data sets from a file of raw Tristan events data.

The returned DataFrame has a column for each of the specified LATRD data keys. Each key must be a valid LATRD data key and the corresponding data sets must all have the same length.

Parameters:

paths – The path to the raw LATRD data file.
keys – The set of LATRD data keys to read.

Returns:

The data from all the files.

tristan.data.latrd_mf_data(paths: Iterable[str | Path], keys: Iterable[str]) → DataFrame[source]

Read LATRD data sets from multiple files of raw Tristan events data.

The returned DataFrame has a column for each of the specified LATRD data keys. Each key must be a valid LATRD data key and the corresponding data sets must all have the same length.

Parameters:

paths – The paths to the raw LATRD data files.
keys – The set of LATRD data keys to read.

Returns:

The data from all the files.

tristan.data.pixel_index(data: DataFrame | DataFrame, image_size: tuple[int, int]) → DataFrame | DataFrame[source]

Extract pixel coordinate information from an event location (event_id) message.

Translate a Tristan event location message to the index of the corresponding pixel in the flattened image array (i.e. numbered from zero, in row-major order).

The pixel coordinates of an event on a Tristan detector are encoded in a 32-bit integer location message (the event_id) with 2n bits of useful information. Extract the y coordinate (the n least significant bits) and the x coordinate (the n next least significant bits). The value of n is recorded as tristan.data.coordinate_bitdepth and is usually 13. Find the corresponding pixel index in the flattened image array by multiplying the y value by the size of the array in x, and adding the x value.

In the resulting dataframe, the "event_id"" column is replaced with a column named "pixel_index", with values, encoding the positions of each pixel in the flattened image array.

Parameters:

data – A Dask DataFrame, having a column named event_location_key.
image_size – Shape of the image array in (y, x), i.e. (slow, fast).

Returns:

A Dask DataFrame like the input data but having the new "pixel_index" column in place of the old "event_id" column.

tristan.data.seconds(timestamp: int, reference: int = 0) → Quantity[source]

Convert a Tristan timestamp to seconds, measured from a given reference timestamp.

The time between the provided timestamp and a reference timestamp, both provided as a number of clock cycles from the same time origin, is converted to units of seconds. By default, the reference timestamp is zero clock cycles, the beginning of the detector epoch.

Parameters:

timestamp – A timestamp in number of clock cycles, to be converted to seconds.
reference – A reference time stamp in clock cycles.

Returns:

The difference between the two timestamps in seconds.

tristan.data.valid_events(data: DataFrame, start: int, end: int) → DataFrame[source]

Return those events that have a timestamp in the specified range.

Parameters:

data – LATRD data, containing an ‘event_time_offset’ column and optional ‘event_id’ and ‘event_energy’ columns.
start – The start time of the accepted range, in clock cycles.
end – The end time of the accepted range, in clock cycles.

Returns:

The valid events.

Diagnostics API

General

Diagnostic tools for Tristan detector. To be run before collection.

tristan.diagnostics.utils.define_modules(det_config: TristanConfig = '10M') → dict[str, tuple][source]

Define the start and end pixel of each module in the Tristan detector.

Parameters:: det_config (TristanConfig, optional) – Specify how many physical modules make up the Tristan detector currently in use. Available configurations: 1M, 2M, 10M. Defaults to “10M”.
Returns:: Start and end pixel value of each module - which are defined by a (x,y) tuple. For example a Tristan 1M will return {“0”: ([0, 515], [0, 2069])}
Return type:: dict[str, tuple]

tristan.diagnostics.utils.module_cooordinates(det_config: TristanConfig = '10M') → dict[str, tuple][source]

Create a conversion table between module number and its location on the detector.

Parameters:: det_config (TristanConfig, optional) – Specify how many physical modules make up the Tristan detector currently in use. Available configurations: 1M, 2M, 10M. Defaults to “10M”.
Returns:: effectively a conversion table mapping the module number to its location on the detector. For example a Trisstan 1M will return {“0”: (0, 0)}
Return type:: dict[str, tuple]

tristan.diagnostics.utils.assign_files_to_modules(filelist: list[Path], det_config: TristanConfig = '10M', check_for: FileChecker = 'events')[source]

Assign each file to the correct module after having checked that it has valid events/cues in it. While the files should be in order i.e. for module 0 we’ll have file numbers 000001-000010, for module 1 file numbers 000011-000020 and so on, when checking for events an additional check will be done on the event id when assigning to each module.

Parameters:

filelist (list[Path]) – List of input tristan files.
det_config (TristanConfig, optional) – Specify how many physical modules make up the Tristan detector currently in use. Available configurations: 1M, 2M, 10M. Defaults to “10M”.
check_for (FileChecker, optional) – Specify whether to check for valid events or cues. Defaults to “cues”.

Returns:

List of files assigned to each module.

Return type:

files_per_module(dict[str, list(Path)])

tristan.diagnostics.utils.get_full_file_list(filename_template: str | Path) → list[Path][source]

Given a template filename, including directory, get a list of all the files using that template.

Parameters:: filename_template (str | Path) – Template to look up in the directory.
Returns:: A list of all the files found matching the template.
Return type:: file_list(list[Path])

tristan.diagnostics.utils.find_shutter_times(filelist)[source]: Find shutter open and close timestamps.

Logging configuration

Logging configuration for Tristan diagnostics.

tristan.diagnostics.diagnostics_log.config(logfile: str | None = None, write_mode: str = 'a')[source]

Configure the logger.

Parameters:

logfile (str, optional) – If passed, create a file handle for the logger to write a logfile output. Defaults to None.
write_mode (str, optional) – Writing mode for the logfile output. Defaults to “a”.

API

General

Binning

Data

Diagnostics API

General

Logging configuration

tristan

Navigation

Related Topics