experiment

Modules:

Name	Description
experiment

Classes:

Name	Description
Experiment	Holds data from an experiment as a sc.DataArray along with metadata.

Classes

Experiment(display_name='MyExperiment', unique_name=None, data=None)

Holds data from an experiment as a sc.DataArray along with metadata.

This is a minimal implementation that will be extended in the future.

Examples:

Loading experimental data from the repository

Use pooch to download the example vanadium dataset directly from the repository:

import pooch
import easydynamics as edyn

file_path = pooch.retrieve(
    url='https://github.com/easyscience/dynamics-lib/raw/refs/heads/master/docs/docs/tutorials/data/vanadium_data_example.h5',
    known_hash='16cc1b327c303feeb88fb9dda5390dc4880b62396b1793f98c6fef0b27c7b873',
)

experiment = edyn.Experiment(display_name='Vanadium')
experiment.load_hdf5(filename=file_path)

Rebinning and plotting

After loading, rebin to reduce the number of bins along each dimension before plotting:

experiment.rebin({'Q': 5, 'energy': 50})
experiment.plot_data()

Parameters:

Name	Type	Description	Default
display_name	str | None	Display name of the experiment.	'MyExperiment'
unique_name	str | None	Unique name of the experiment. If None, a unique name will be generated. None.	None
data	sc.DataArray | str | None	Dataset associated with the experiment. Can be a sc.DataArray or a filename string to load from. If None, no data is loaded.	None

Raises:

Type	Description
TypeError	If data is not a sc.DataArray, a string, or None.

Methods:

Name	Description
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object from a full encoded dictionary.
get_masked_energy	Get the energy values from the dataset, removing points where the y values or variances are
get_finite_energy_mask	Get a boolean scipp Variable selecting energy points with finite intensity at the given Q.
get_masked_binned_data	Get the binned data for a single Q slice with non-finite points masked out.
load_hdf5	Load data from an HDF5 file.
save_hdf5	Save the dataset to HDF5.
remove_data	Remove the dataset from the experiment.
rebin	Rebin the dataset along specified dimensions.
plot_data	Plot the dataset using plopp: https://scipp.github.io/plopp/.
extract_x_y_weights_only_finite	Extract the x, y, and weights arrays from the experiment for the given Q index, removing
__copy__	Return a copy of the object.

Attributes:

Name	Type	Description
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.
data	sc.DataArray | None	Get the dataset associated with this experiment.
binned_data	sc.DataArray | None	Get the binned dataset associated with this experiment.
Q	sc.Variable | None	Get the Q values from the dataset.
energy	sc.Variable | None	Get the energy values from the dataset.

Attributes

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
str	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

data property writable

Get the dataset associated with this experiment.

Returns:

Type	Description
sc.DataArray | None	The dataset associated with this experiment, or None if no data is loaded.

binned_data property writable

Get the binned dataset associated with this experiment.

Returns:

Type	Description
sc.DataArray | None	The binned dataset associated with this experiment, or None if no data is loaded.

Q property writable

Get the Q values from the dataset.

Returns:

Type	Description
sc.Variable | None	The Q values from the dataset, or None if no data is loaded.

energy property writable

Get the energy values from the dataset.

Returns:

Type	Description
sc.Variable | None	The energy values from the dataset, or None if no data is loaded.

Methods:

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

Parameters:

Name	Type	Description	Default
skip	Optional[List[str]]	List of field names as strings to skip when forming the dictionary. By default, None.	None

Returns:

Type	Description
Dict[str, Any]	Encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object from a full encoded dictionary.

Parameters:

Name	Type	Description	Default
obj_dict	Dict[str, Any]	Dictionary containing the serialized contents (from SerializerDict) of an EasyScience object.	required

Returns:

Type	Description
NewBase	Reformed EasyScience object.

Raises:

Type	Description
ValueError	If the input dictionary does not describe the expected class.

get_masked_energy(Q_index, mask=None)

Get the energy values from the dataset, removing points where the y values or variances are NaN or Inf for the given Q index.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to get the masked energy values for.	required
mask	sc.Variable | None	Optional precomputed finite-energy mask (as returned by :meth:get_finite_energy_mask), so callers that already extracted the data do not pay for a second extraction. If None, the mask is computed.	None

Returns:

Type	Description
sc.Variable | None	The masked energy values from the dataset, or None if no data is loaded.

get_finite_energy_mask(Q_index)

Get a boolean scipp Variable selecting energy points with finite intensity at the given Q.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to get the mask for.	required

Returns:

Type	Description
sc.Variable | None	Boolean scipp Variable of length n_energy with dim 'energy', or None if no data is loaded.

get_masked_binned_data(Q_index)

Get the binned data for a single Q slice with non-finite points masked out.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to extract.	required

Returns:

Type	Description
sc.DataArray | None	The binned data for the given Q index with NaN/Inf points removed, or None if no data is loaded.

load_hdf5(filename, display_name=None)

Load data from an HDF5 file.

Parameters:

Name	Type	Description	Default
filename	str	Path to the HDF5 file.	required
display_name	str | None	Optional display name for the experiment.	None

Raises:

Type	Description
TypeError	If filename is not a string or if display_name is not a string or None or if the loaded data is not a sc.DataArray.

save_hdf5(filename=None)

Save the dataset to HDF5.

Parameters:

Name	Type	Description	Default
filename	str | None	Path to the output HDF5 file. If None, the file will be named after the unique_name of the experiment with a .h5 extension.	None

Raises:

Type	Description
TypeError	If filename is not a string or None.
ValueError	If there is no data to save.

remove_data()

Remove the dataset from the experiment.

rebin(dimensions)

Rebin the dataset along specified dimensions.

Parameters:

Name	Type	Description	Default
dimensions	dict[str, int | sc.Variable]	A dictionary mapping dimension names to number of bins (int) or bin edges (sc.Variable).	required

Raises:

Type	Description
TypeError	If dimensions is not a dictionary or if keys/values are of incorrect types.
ValueError	If there is no data to rebin.
KeyError	If a specified dimension is not in the dataset.

plot_data(slicer=False, transpose_axes=False, **kwargs)

Plot the dataset using plopp: https://scipp.github.io/plopp/.

Parameters:

Name	Type	Description	Default
slicer	bool	If True, use plopp's slicer instead of plot.	False
transpose_axes	bool	If True, transpose the data to have dimensions in the order (energy, Q) before plotting, so that energy is on the x-axis. This only applies when slicer=False.	False
**kwargs	dict	Additional keyword arguments to pass to plopp.	{}

Returns:

Type	Description
InteractiveFigure	A plot of the data and model.

Raises:

Type	Description
ValueError	If there is no data to plot.
RuntimeError	If not in a Jupyter notebook environment.
TypeError	If slicer or transpose_axes are not True or False.

extract_x_y_weights_only_finite(Q_index)

Extract the x, y, and weights arrays from the experiment for the given Q index, removing any NaN and Inf values.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to extract the data for.	required

Raises:

Type	Description
ValueError	If any variances are zero after removing NaNs and Infs, since this would lead to infinite weights.

Returns:

Type	Description
tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]	The x, y, weights, and mask arrays extracted from the experiment for the given Q index, with NaNs and Infs removed.

__copy__()

Return a copy of the object.

Returns:

Type	Description
Experiment	A copy of the Experiment object.

Modules

experiment

Classes:

Name	Description
Experiment	Holds data from an experiment as a sc.DataArray along with metadata.

Classes

Experiment(display_name='MyExperiment', unique_name=None, data=None)

Holds data from an experiment as a sc.DataArray along with metadata.

This is a minimal implementation that will be extended in the future.

Examples:

Loading experimental data from the repository

Use pooch to download the example vanadium dataset directly from the repository:

import pooch
import easydynamics as edyn

file_path = pooch.retrieve(
    url='https://github.com/easyscience/dynamics-lib/raw/refs/heads/master/docs/docs/tutorials/data/vanadium_data_example.h5',
    known_hash='16cc1b327c303feeb88fb9dda5390dc4880b62396b1793f98c6fef0b27c7b873',
)

experiment = edyn.Experiment(display_name='Vanadium')
experiment.load_hdf5(filename=file_path)

Rebinning and plotting

After loading, rebin to reduce the number of bins along each dimension before plotting:

experiment.rebin({'Q': 5, 'energy': 50})
experiment.plot_data()

Parameters:

Name	Type	Description	Default
display_name	str | None	Display name of the experiment.	'MyExperiment'
unique_name	str | None	Unique name of the experiment. If None, a unique name will be generated. None.	None
data	sc.DataArray | str | None	Dataset associated with the experiment. Can be a sc.DataArray or a filename string to load from. If None, no data is loaded.	None

Raises:

Type	Description
TypeError	If data is not a sc.DataArray, a string, or None.

Methods:

Name	Description
get_masked_energy	Get the energy values from the dataset, removing points where the y values or variances are
get_finite_energy_mask	Get a boolean scipp Variable selecting energy points with finite intensity at the given Q.
get_masked_binned_data	Get the binned data for a single Q slice with non-finite points masked out.
load_hdf5	Load data from an HDF5 file.
save_hdf5	Save the dataset to HDF5.
remove_data	Remove the dataset from the experiment.
rebin	Rebin the dataset along specified dimensions.
plot_data	Plot the dataset using plopp: https://scipp.github.io/plopp/.
extract_x_y_weights_only_finite	Extract the x, y, and weights arrays from the experiment for the given Q index, removing
__copy__	Return a copy of the object.
to_dict	Convert an EasyScience object into a full dictionary using
from_dict	Re-create an EasyScience object from a full encoded dictionary.

Attributes:

Name	Type	Description
data	sc.DataArray | None	Get the dataset associated with this experiment.
binned_data	sc.DataArray | None	Get the binned dataset associated with this experiment.
Q	sc.Variable | None	Get the Q values from the dataset.
energy	sc.Variable | None	Get the energy values from the dataset.
unique_name	str	Get the unique name of the object.
display_name	str	Get a pretty display name.
name	str	Get the name of the model.

Attributes

data property writable

Get the dataset associated with this experiment.

Returns:

Type	Description
sc.DataArray | None	The dataset associated with this experiment, or None if no data is loaded.

binned_data property writable

Get the binned dataset associated with this experiment.

Returns:

Type	Description
sc.DataArray | None	The binned dataset associated with this experiment, or None if no data is loaded.

Q property writable

Get the Q values from the dataset.

Returns:

Type	Description
sc.Variable | None	The Q values from the dataset, or None if no data is loaded.

energy property writable

Get the energy values from the dataset.

Returns:

Type	Description
sc.Variable | None	The energy values from the dataset, or None if no data is loaded.

unique_name property writable

Get the unique name of the object.

display_name property writable

Get a pretty display name.

Returns:

Type	Description
str	The pretty display name.

name property writable

Get the name of the model.

Returns:

Type	Description
str	The name of the model.

Methods:

get_masked_energy(Q_index, mask=None)

Get the energy values from the dataset, removing points where the y values or variances are NaN or Inf for the given Q index.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to get the masked energy values for.	required
mask	sc.Variable | None	Optional precomputed finite-energy mask (as returned by :meth:get_finite_energy_mask), so callers that already extracted the data do not pay for a second extraction. If None, the mask is computed.	None

Returns:

Type	Description
sc.Variable | None	The masked energy values from the dataset, or None if no data is loaded.

get_finite_energy_mask(Q_index)

Get a boolean scipp Variable selecting energy points with finite intensity at the given Q.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to get the mask for.	required

Returns:

Type	Description
sc.Variable | None	Boolean scipp Variable of length n_energy with dim 'energy', or None if no data is loaded.

get_masked_binned_data(Q_index)

Get the binned data for a single Q slice with non-finite points masked out.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to extract.	required

Returns:

Type	Description
sc.DataArray | None	The binned data for the given Q index with NaN/Inf points removed, or None if no data is loaded.

load_hdf5(filename, display_name=None)

Load data from an HDF5 file.

Parameters:

Name	Type	Description	Default
filename	str	Path to the HDF5 file.	required
display_name	str | None	Optional display name for the experiment.	None

Raises:

Type	Description
TypeError	If filename is not a string or if display_name is not a string or None or if the loaded data is not a sc.DataArray.

save_hdf5(filename=None)

Save the dataset to HDF5.

Parameters:

Name	Type	Description	Default
filename	str | None	Path to the output HDF5 file. If None, the file will be named after the unique_name of the experiment with a .h5 extension.	None

Raises:

Type	Description
TypeError	If filename is not a string or None.
ValueError	If there is no data to save.

remove_data()

Remove the dataset from the experiment.

rebin(dimensions)

Rebin the dataset along specified dimensions.

Parameters:

Name	Type	Description	Default
dimensions	dict[str, int | sc.Variable]	A dictionary mapping dimension names to number of bins (int) or bin edges (sc.Variable).	required

Raises:

Type	Description
TypeError	If dimensions is not a dictionary or if keys/values are of incorrect types.
ValueError	If there is no data to rebin.
KeyError	If a specified dimension is not in the dataset.

plot_data(slicer=False, transpose_axes=False, **kwargs)

Plot the dataset using plopp: https://scipp.github.io/plopp/.

Parameters:

Name	Type	Description	Default
slicer	bool	If True, use plopp's slicer instead of plot.	False
transpose_axes	bool	If True, transpose the data to have dimensions in the order (energy, Q) before plotting, so that energy is on the x-axis. This only applies when slicer=False.	False
**kwargs	dict	Additional keyword arguments to pass to plopp.	{}

Returns:

Type	Description
InteractiveFigure	A plot of the data and model.

Raises:

Type	Description
ValueError	If there is no data to plot.
RuntimeError	If not in a Jupyter notebook environment.
TypeError	If slicer or transpose_axes are not True or False.

extract_x_y_weights_only_finite(Q_index)

Extract the x, y, and weights arrays from the experiment for the given Q index, removing any NaN and Inf values.

Parameters:

Name	Type	Description	Default
Q_index	int	The Q index to extract the data for.	required

Raises:

Type	Description
ValueError	If any variances are zero after removing NaNs and Infs, since this would lead to infinite weights.

Returns:

Type	Description
tuple[np.ndarray, np.ndarray, np.ndarray, np.ndarray]	The x, y, weights, and mask arrays extracted from the experiment for the given Q index, with NaNs and Infs removed.

__copy__()

Return a copy of the object.

Returns:

Type	Description
Experiment	A copy of the Experiment object.

to_dict(skip=None)

Convert an EasyScience object into a full dictionary using SerializerBases generic convert_to_dict method.

Parameters:

Name	Type	Description	Default
skip	Optional[List[str]]	List of field names as strings to skip when forming the dictionary. By default, None.	None

Returns:

Type	Description
Dict[str, Any]	Encoded object containing all information to reform an EasyScience object.

from_dict(obj_dict) classmethod

Re-create an EasyScience object from a full encoded dictionary.

Parameters:

Name	Type	Description	Default
obj_dict	Dict[str, Any]	Dictionary containing the serialized contents (from SerializerDict) of an EasyScience object.	required

Returns:

Type	Description
NewBase	Reformed EasyScience object.

Raises:

Type	Description
ValueError	If the input dictionary does not describe the expected class.

Functions: