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,
...              weights=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 weights parameter is an array of strictly positive per-point weights. Weights only change the contribution of points to the scaled cost used by optimizers: each residual is multiplied by sqrt(weight). Parameter errors are estimated from the unscaled cost, which uses only the data errors. Masked points are removed from both the optimization and the parameter error estimation.

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 = '', weights: ArrayLike | None = None) → 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 weights: Optional strictly positive per-point weights for the scaled

(optimization) cost; parameter errors are not affected

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 = '', raise_exceptions: bool = False) → 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 raise_exceptions: When True, raise on load errors; otherwise store in last_error
Returns:: data_obj instance that loads from the file
Raises:: escape_exc: If the file cannot be read or parsed and raise_exceptions is True

class escape.core.data.data_obj#

Container class for experimental data.

bind_python_object(observer=None)#

coordinates#: Get coordinates array with masked points removed.

errors#: Get errors array with masked points removed.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

has_weights#: Check whether user-defined weights are set.

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

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

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

ini_weights#: Get initial weights array (ignoring mask), empty when weights are not set.

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.

on_state_changed()#

on_value_changed()#

parameters#: Get list of parameters.

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

reset_weights() → None#: Remove user-defined weights (all weights become 1.0).

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

set_weights(weights: ArrayLike, copy: bool = False) → None#

Set per-point weights for the scaled (optimization) cost.

Args:

weights: Array of finite, strictly positive weights with the same: length as the initial (unmasked) intensities

copy: If True, always copy source data. If False, avoid copying when possible

Raises:

RuntimeError: If the size does not match or any weight is not finite and > 0

settings#: Get list of settings.

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

unbind_python_object()#

weights#: Get weights array with masked points removed (1.0 when weights are not set).

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

bind_python_object(observer=None)#

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.

get_hash_int() → int#: Return the C++ entity hash used for stable identity.

name#: Get datastack name.

on_state_changed()#

on_value_changed()#

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

settings#: Get list of settings.

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

unbind_python_object()#