Array

class escape.Array(data=None, index=None, step_lengths=None, parameter=None, name=None, source=None, grid_specs=None)

Bases: object

nd array data wrapper with optional scan metadata and grid support.

Array stores raw measurement data together with an event index and optional scan grouping information. When step_lengths and parameter are provided, a lazily constructed scan property exposes grouped step selection and scan-level operations.

Args:

data: nd data array or callable returning data. index: Event identifiers aligned with the first dimension of data. step_lengths: List of step sizes for each scan step. parameter: Scan parameter metadata for each step. name: Optional array name. source: Optional source metadata object. grid_specs: Optional metadata used to build scan.grid.

property T

__getitem__(*args, **kwargs)

__init__(data=None, index=None, step_lengths=None, parameter=None, name=None, source=None, grid_specs=None)

__len__()

abs(*args, **kwargs)

Apply numpy.abs() to this Array’s data.

absolute(x, /, out=None, *, where=True, casting=’same_kind’, order=’K’, dtype=None, subok=True[, signature])

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

all(*args, **kwargs)

Apply numpy.all() to this Array’s data.

Test whether all array elements along a given axis evaluate to True.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

any(*args, **kwargs)

Apply numpy.any() to this Array’s data.

Test whether any array element along a given axis evaluates to True.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

astype(newtype)

average(*args, **kwargs)

Apply numpy.average() to this Array’s data.

Compute the weighted average along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

categorize(other_array)

Re-sort and re-group other_array to match this Array’s index ordering and scan-step boundaries.

The returned Array contains other_array’s data values at the pulse IDs that are common to both arrays, ordered and grouped exactly as self. This is the primary tool for applying a new grouping (obtained e.g. via digitize() or get_index_array()) to another channel.

Parameters:

other_array (escape.Array) – The array to re-sort.

Returns:

other_array restricted to the common pulse IDs and re-grouped according to self’s scan structure.

Return type:

escape.Array

Notes

Equivalent to escape.match_arrays(self, other_array)[1].

Examples

>>> time_bins = sig.get_index_array(N_index_aggregation=1000)
>>> i0_rebinned = time_bins.categorize(i0)

compute(**kwargs)

Evaluate the dask graph and return a new Array backed by a NumPy array.

No-op when the data is already a NumPy array (returns self with a message). All index and scan metadata are preserved.

Parameters:

**kwargs – Forwarded to dask.array.Array.compute().

Returns:

Same Array with NumPy data instead of a dask graph.

Return type:

escape.Array

See also

escape.compute

Compute several Arrays in one dask scheduler pass.

correct_for_references(isref_bool, N_index_aggregation=None, operation=<built-in function truediv>)

correlation_analysis_to(ref, order=2)

property data

digitize(bins, **kwargs)

property dtype

filter(*args, **kwargs)

get_index_array(N_index_aggregation=None)

Return an Array whose data equals its own index (pulse IDs), optionally grouped into contiguous bins.

Without aggregation this is a simple 1-D Array where data == index, useful as an “identity” sorter. With N_index_aggregation the pulse IDs are binned into groups of width N_index_aggregation index units (typically pulse IDs), creating a coarser time-ordered grouping.

Parameters:

N_index_aggregation (int, optional) – Width of each pulse-ID bin. If None no binning is applied.

Returns:

1-D Array with data == index (before any binning).

Return type:

escape.Array

Notes

The resulting Array can be used with categorize() to apply the new grouping to any other channel:

Examples

>>> # Group into bins of 1000 consecutive pulse IDs
>>> time_bins = sig.get_index_array(N_index_aggregation=1000)
>>> sig_rebinned = time_bins.categorize(sig)
>>> i0_rebinned  = time_bins.categorize(i0)

get_modulo_array(mod, offset=0)

get_random_events(n, seed=None)

property grid

hist(cut_percentage=0, bins='auto', normalize_to=None, scanpar_name=None, plot_results=True, plot_axis=None)

property index

is_dask_array()

isfinite(*args, **kwargs)

Apply numpy.isfinite() element-wise to this Array’s data.

isfinite(x, /, out=None, *, where=True, casting=’same_kind’, order=’K’, dtype=None, subok=True[, signature])

Returns an Array with the same index and scan structure.

isinf(*args, **kwargs)

Apply numpy.isinf() element-wise to this Array’s data.

isinf(x, /, out=None, *, where=True, casting=’same_kind’, order=’K’, dtype=None, subok=True[, signature])

Returns an Array with the same index and scan structure.

isnan(*args, **kwargs)

Apply numpy.isnan() element-wise to this Array’s data.

isnan(x, /, out=None, *, where=True, casting=’same_kind’, order=’K’, dtype=None, subok=True[, signature])

Returns an Array with the same index and scan structure.

classmethod load_from_h5(parent_h5py, name)

map_index_blocks(foo, *args, drop_axis=None, new_axis=None, new_element_size=None, event_dim='same', **kwargs)

Apply foo block-wise over the event axis using dask’s map_blocks.

The function foo receives a raw NumPy array (one dask chunk along the event axis) and returns a NumPy array. The result is assembled back into a lazy dask-backed Array with the same index and scan metadata.

This is the preferred way to apply arbitrary NumPy or SciPy functions (gain correction, thresholding, peak fitting, …) to large detector data without loading everything into memory.

Parameters:

• foo (callable) – f(block, *args, **kwargs) -> ndarray. block has shape (n_events_in_chunk, *element_shape).

• *args – Extra positional arguments forwarded to foo.

• drop_axis (int or list of int, optional) – Axes to remove from the output (forwarded to dask.map_blocks).

• new_axis (int or list of int, optional) – New axes to add to the output.

• new_element_size (list of int, optional) – Shape of each per-event element in the output (excluding the event axis). Required when foo changes the per-event shape.

• **kwargs – Extra keyword arguments forwarded to foo.

Returns:

Lazy Array with the transformed data.

Return type:

escape.Array

Examples

Threshold pixels below 4 keV to NaN:

def threshold(block, thr):
    out = block.copy()
    out[out < thr] = np.nan
    return out

imgs_clean = imgs.map_index_blocks(threshold, 4.0)

Extract two scalars per event (change per-event shape):

posamp = tt_proj.map_index_blocks(
    lambda block: np.array([find_edge(row) for row in block]),
    new_element_size=(2,),
    dtype=float,
)

Notes

Formerly called map_event_blocks in older versions of escape.

max(*args, **kwargs)

Apply numpy.max() to this Array’s data.

Return the maximum of an array or maximum along an axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

mean(*args, **kwargs)

Apply numpy.mean() to this Array’s data.

Compute the arithmetic mean along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

median(*args, **kwargs)

Apply numpy.median() to this Array’s data.

Compute the median along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

min(*args, **kwargs)

Apply numpy.min() to this Array’s data.

Return the minimum of an array or minimum along an axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nancount()

Return the number of finite (non-NaN) events in this Array.

nanmax(*args, **kwargs)

Apply numpy.nanmax() to this Array’s data.

Return the maximum of an array or maximum along an axis, ignoring any

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanmean(*args, **kwargs)

Apply numpy.nanmean() to this Array’s data.

Compute the arithmetic mean along the specified axis, ignoring NaNs.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanmedian(*args, **kwargs)

Apply numpy.nanmedian() to this Array’s data.

Compute the median along the specified axis, while ignoring NaNs.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanmin(*args, **kwargs)

Apply numpy.nanmin() to this Array’s data.

Return minimum of an array or minimum along an axis, ignoring any NaNs.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanpercentile(*args, **kwargs)

Apply numpy.nanpercentile() to this Array’s data.

Compute the qth percentile of the data along the specified axis,

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanquantile(*args, **kwargs)

Apply numpy.nanquantile() to this Array’s data.

Compute the qth quantile of the data along the specified axis,

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nanstd(*args, **kwargs)

Apply numpy.nanstd() to this Array’s data.

Compute the standard deviation along the specified axis, while

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

nansum(*args, **kwargs)

Apply numpy.nansum() to this Array’s data.

Return the sum of array elements over a given axis treating Not a

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

property ndim

property ndim_nonzero

ones(**kwargs)

percentile(*args, **kwargs)

Apply numpy.percentile() to this Array’s data.

Compute the q-th percentile of the data along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

persist()

plot(axis=None, linespec='.', *args, **kwargs)

plot_corr(arr, ratio=False, axis=None, linespec='.', polyfit_order=None, *args, **kwargs)

quantile(*args, **kwargs)

Apply numpy.quantile() to this Array’s data.

Compute the q-th quantile of the data along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

ravel_event_data()

Flatten all non-event axes into a single dimension per event.

Converts an Array of shape (N, d1, d2, ...) to (N, d1*d2*...), preserving the event axis and scan structure. Useful for feeding multi-dimensional detector data into functions that expect a 1-D value per event.

Returns:

Array with shape (N, d1*d2*...).

Return type:

escape.Array

Examples

>>> imgs.shape                   # (500, 64, 64)
>>> flat = imgs.ravel_event_data()
>>> flat.shape                   # (500, 4096)

property scan

set_h5_storage(parent_h5py, name=None)

set_h5_storage_file(file_name, parent_group_name, name=None)

property shape

std(*args, **kwargs)

Apply numpy.std() to this Array’s data.

Compute the standard deviation along the specified axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

store(parent_h5py=None, name=None, unit=None, lock='auto', **kwargs)

a way to store data, especially expensively computed data, into a new file.

store_file(parent_h5py=None, name=None, unit=None, **kwargs)

a way to store data, especially expensively computed data, into a new file.

sum(*args, **kwargs)

Apply numpy.sum() to this Array’s data.

Sum of array elements over a given axis.

Omitting axis or passing axis=0 reduces over events and returns a plain numpy/dask result. Pass axis=N (N > 0) to reduce along a non-event axis and receive a new Array.

property tools

transpose(*args)

update(array)

Merge array into this Array, adding only events with new pulse IDs.

Events already present in self (matched by pulse ID) are ignored; new events are appended as additional scan steps so that the existing scan structure is preserved and the new events keep their own step grouping. Intended for incremental accumulation during acquisition — call repeatedly with newer snapshots to build up a complete dataset.

Parameters:

array (escape.Array) – Source Array whose new events will be added to this one.

Returns:

New Array containing all events from self plus any events in array whose pulse ID was absent from self. Returns self unchanged (same object) if array contributes no new events.

Return type:

escape.Array