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)

all(*args, **kwargs)

any(*args, **kwargs)

astype(newtype)

average(*args, **kwargs)

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)

isinf(*args, **kwargs)

isnan(*args, **kwargs)

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)

mean(*args, **kwargs)

median(*args, **kwargs)

min(*args, **kwargs)

nanmax(*args, **kwargs)

nanmean(*args, **kwargs)

nanmedian(*args, **kwargs)

nanmin(*args, **kwargs)

nanpercentile(*args, **kwargs)

nanquantile(*args, **kwargs)

nanstd(*args, **kwargs)

nansum(*args, **kwargs)

property ndim

property ndim_nonzero

ones(**kwargs)

percentile(*args, **kwargs)

persist()

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

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

quantile(*args, **kwargs)

ravel_event_data(*args)

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)

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)

property tools

transpose(*args)

update(array)

Update one escape array from another. Only array elements not existing in the present array will be added to it.