Module-Level Functions

escape.escaped(func, convertOutput2EscData='auto')

Decorator that lifts a NumPy/dask function to operate on escape Arrays.

When any positional or keyword argument is an Array, the decorator automatically:

1. Finds the intersection of all Array indices.

2. Aligns (re-indexes) every Array argument to the common pulse IDs, using the first Array found as the ordering reference.

3. Passes the aligned raw data arrays to func.

4. Wraps each output whose length matches the number of common events back into a new Array carrying the correct index and scan metadata.

Non-Array arguments are passed through unchanged.

Parameters:

• func (callable) – Any function that accepts NumPy or dask arrays.

• convertOutput2EscData ("auto" or list of int) – Which output positions to wrap as Arrays. "auto" (default) wraps every output whose length equals the number of common events. Pass a list of integer indices (e.g. [0]) to wrap only specific outputs.

Returns:

Wrapped function with the same signature as func, plus an optional escSorter keyword to override the master Array (default: first Array found in the argument list).

Return type:

callable

Examples

Decorate a function at definition time:

@escape.escaped
def normalise(signal, reference):
    return signal / reference

sig_norm = normalise(sig, i0)   # sig_norm is an escape.Array

Or apply to an existing NumPy function:

my_polyfit = escape.escaped(np.polyfit)

escape.match_arrays(*args, escSorter='first', convertOutput2EscData='auto', **kwargs)

escape.concatenate(arraylist, grid_specs=None)

Concatenate a list of Arrays along the event axis.

Merges data, indices, and scan metadata (step lengths and parameter values) from all input Arrays into a single Array. All input Arrays must share the same scan parameter names.

Parameters:

• arraylist (list of escape.Array) – Arrays to concatenate. They must have identical scan parameter keys.

• grid_specs (dict, optional) – Grid metadata to attach to the resulting Array.

Returns:

Combined Array whose scan has len(arraylist[0].scan) + … steps.

Return type:

escape.Array

Examples

>>> combined = escape.concatenate([run1, run2, run3])
>>> print(combined.scan.par_steps)

escape.compute(*args)

compute multiple escape arrays or dask arrays. Interesting when calculating multiple small arrays from the same ancestor dask based array

escape.store(arrays, lock='auto', **kwargs)

Storing of multiple escape arrays (as iterable, list or similar), efficient when they originate from the same ancestor

escape.storage.storage.digitize(array, bins, include_outlier_bins=False, sort_groups_by_index=True, right=False, foo=<function digitize>, **kwargs)

Digitization function for escape arrays according to numpy.digitize. Works for 1D arrays only.

Args:

array (escape.Array): the escape array holding data that are supposed

to be sorted/digitized.

bins (array_kile): array of bins, has to be 1-dimensional and monotonic. include_outlier_bins (bool/’right’/’left’ optional): option to include

outliers of described bin edges on either or both siges of the bins array. Defaults to False.

sort_groups_by_index (bool, optional): sorting escape.Array data within

bins according to their index value. Defaults to True.

right (bool, optional): Indicating whether the intervals include the

right or the left bin edge. Default behavior is (right==False) indicating that the interval does not include the right edge. The left bin end is open in this case, i.e., bins[i-1] <= x < bins[i] is the default behavior for monotonically increasing bins. Defaults to False.

foo (function, optional): option to modify the digitisation function,

needs still to behave closely to np digitize. Defaults to np.digitize.

Raises:

NotImplementedError: error if no 1d escape.Array is provided as array

argument.

Returns:

escape.Array: Digitized/ resorted escape.Array

escape.storage.storage.filter(array, *args, foos_filtering=[<built-in function ge>, <built-in function le>], **kwargs)

general filter function for escape arrays. checking for 1D arrays, applies arbitrary number of filter functions that take one argument as input and

escape.storage.storage.unravel_arrays(*arrays, categorize_target=None)

Unravel multiple escape arrays to a sorter array spanning out the dimensions of the arrays.

Args:

*arrays: arbitrary number of escape arrays. categorize_target: optional argument to categorize the resulting array according to a target array, e.g. for coloring in plots. Returns:

escape.Array: The unraveled array.