Data and Datastack¶

This module provides the data_obj and datastack_obj classes for handling experimental data.

Data¶

The data_obj class is a container for experimental data. Create a data object with:

>>> d = esc.data(name="Data name", coordinates, experiment, errors=None, mask=None, copy=False)

All input arrays must be numpy.ndarray type. Arrays will be converted and copied if needed.

Arrays are copied if copy=True, otherwise wrappers are used when possible. If errors=None, errors are calculated as sqrt(experiment) (Poisson distribution). The mask parameter is a boolean array to hide specific data points.

The num_of_variables property returns the number of coordinates per intensity value. For 2D data with function F(x,y), coordinates should be [x0,y0, x1,y1, x2,y2,…].

2D arrays in the form:

coordinates=[
     [x0, y0],
     [x1, y1],
     [x2, y2]
 ]

are supported but will be flattened and copied.

Datastack¶

The datastack_obj class is a container for multiple data objects. Used in modelstack to handle data for multiple models.

Create a datastack with:

>>> s = datastack("Name")

Text file data¶

Load data from a text file with optional parsing options (matches C++ escape::text_file_data):

>>> d = text_file_data("path/to/file.txt")
>>> d = text_file_data("path/to/file.txt", delimiter=" ", skiprows=0, comments="#",
...                    coord_columns="0,1", intensity_column=2, errors_column=-1, max_rows=-1,
...                    name="My data", notes="")

escape.core.data.data(coordinates: ArrayLike, intensities: ArrayLike, errors: ArrayLike | None = None, mask: ArrayLike | None = None, copy: bool = False, name: str = 'Data', notes: str = '') → data_obj¶

Create a data_obj container for experimental data.

Matches the C++ factory escape::data(coordinates, intensities [, errors], name, notes). Errors default to sqrt(|intensity|) when not provided (Poisson).

Args:: coordinates: Array of coordinate values (e.g. scattering/wave-vector components) intensities: Array of intensity values errors: Optional error values (defaults to sqrt(intensities)) mask: Optional boolean mask to exclude data points copy: If True, copy all arrays. If False, use wrappers when possible name: Name of data object notes: Optional notes for the data object
Returns:: data_obj instance
Raises:: ValueError: If coordinates shape length > 2 TypeError: If input arrays are not compatible types

escape.core.data.datastack(data: data_obj | List[data_obj] | None = None, name: str = 'Data Stack', notes: str = '') → datastack_obj¶

Create a datastack_obj container for multiple data objects.

Args:: data: Optional data_obj or list of data_obj instances name: Datastack name notes: Optional notes for the datastack
Returns:: datastack_obj instance
Raises:: TypeError: If data is not data_obj or list of data_obj

escape.core.data.text_file_data(file_path: str, delimiter: str = ' ', skiprows: int = 0, comments: str = '#', coord_columns: str = '0', intensity_column: int = 1, errors_column: int = -1, max_rows: int = -1, name: str = 'Text File Data', notes: str = '') → data_obj¶

Create a data_obj that loads from a text file (escape::text_file_data).

The file is read with the given parsing options. Only 2D (x,y) and 3D (x,y,z) data are supported. If errors_column is -1, errors are computed as sqrt(|intensity|).

Args:: file_path: Path to the text file delimiter: Column delimiter (default “ “) skiprows: Number of rows to skip at the start (default 0) comments: Comment character(s) (default “#”) coord_columns: Comma-separated column indices for coordinates (e.g. “0” or “0,1”) intensity_column: Column index for intensity errors_column: Column index for errors (-1 = auto from intensity) max_rows: Maximum rows to read (-1 = no limit) name: Name for the data object notes: Notes for the data object
Returns:: data_obj instance that loads from the file
Raises:: escape_exc: If the file cannot be read or parsed

class escape.core.data.data_obj¶

Container class for experimental data.

coordinates¶: Get coordinates array with masked points removed.

errors¶: Get errors array with masked points removed.

ini_coordinates¶: Get initial coordinates array (ignoring mask).

ini_errors¶: Get initial errors array (ignoring mask).

ini_intensities¶: Get initial intensities array (ignoring mask).

intensities¶: Get intensities array with masked points removed.

last_error¶: Get last text-data reload error message (empty when no error).

mask¶: Get mask array.

name¶: Get data object name.

num_of_variables¶: Get number of coordinates per intensity point.

parameters¶: Get list of parameters.

reset_mask() → None¶: Remove mask from the data.

set_mask(mask: ArrayLike, copy: bool = False) → None¶

Set mask array to hide certain data points.

Args:: mask: Boolean array with same length as intensities copy: If True, always copy source data. If False, avoid copying when possible

show(config: Any | None = None, **kwargs) → Any¶: Show data object in a widget.

class escape.core.data.datastack_obj¶

Container class for multiple data objects.

add(obj: data_obj) → None¶

Append data object (copy is moved into the stack; C++ add takes data_t&&).

Args:: obj: data_obj to add

data(idx: int) → data_obj¶

Get data object at index.

Args:: idx: Data index
Returns:: data_obj instance

data_length¶: Get total number of data points.

erase(idx: int) → None¶

Remove data object at index.

Args:: idx: Data index to remove

erase_all() → None¶: Remove all data objects.

name¶: Get datastack name.

parameters¶: Get list of parameters.

set(idx: int, obj: data_obj) → None¶

Replace data object at index (copy is moved; C++ set takes data_t&&).

Args:: idx: Data index obj: New data_obj

show(data_configs: Any | None = None, config: Any | None = None, **kwargs) → Any¶

Show data stack in a widget.

Args:

data_configs: Either a single DataConfig applied to all data items,: or a list of DataConfig for each data item

config: Optional layout config for the stack widget **kwargs: Additional keyword arguments passed to DataStackLayout

Returns:

DataStackLayout widget displaying the data stack