analysis

Analysis

Bases: AnalysisBase

For analysing two-dimensional data, i.e. intensity as function of energy and Q.

Supports independent fits of each Q value and simultaneous fits of all Q.

Source code in src/easydynamics/analysis/analysis.py

class Analysis(AnalysisBase):
    """For analysing two-dimensional data, i.e. intensity as function of
    energy and Q.

    Supports independent fits of each Q value and simultaneous fits of
    all Q.
    """

    def __init__(
        self,
        display_name: str | None = 'MyAnalysis',
        unique_name: str | None = None,
        experiment: Experiment | None = None,
        sample_model: SampleModel | None = None,
        instrument_model: InstrumentModel | None = None,
        extra_parameters: Parameter | list[Parameter] | None = None,
    ) -> None:
        """Initialize an Analysis object.

        Args:
            display_name (str | None, default='MyAnalysis'): Display name of the analysis.
            unique_name (str | None, default=None): Unique name of the analysis. If
                None, a unique name is automatically generated.
            experiment (Experiment | None, default=None): The Experiment associated
                with this Analysis. If None, a default Experiment is
                created.
            sample_model (SampleModel | None, default=None): The SampleModel
                associated with this Analysis. If None, a default
                SampleModel is created.
            instrument_model (InstrumentModel | None, default=None): The
                InstrumentModel associated with this Analysis. If None,
                a default InstrumentModel is created.
            extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
                parameters to be included in the analysis for advanced
                users. If None, no extra parameters are added.
        """

        # Avoid triggering updates before the object is fully
        # initialized
        self._call_updaters = False
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            experiment=experiment,
            sample_model=sample_model,
            instrument_model=instrument_model,
            extra_parameters=extra_parameters,
        )

        self._analysis_list = []
        if self.Q is not None:
            for Q_index in range(len(self.Q)):
                analysis = Analysis1d(
                    display_name=f'{self.display_name}_Q{Q_index}',
                    unique_name=(f'{self.unique_name}_Q{Q_index}'),
                    experiment=self.experiment,
                    sample_model=self.sample_model,
                    instrument_model=self.instrument_model,
                    extra_parameters=self._extra_parameters,
                    Q_index=Q_index,
                )
                self._analysis_list.append(analysis)
        # Now we can allow updates to trigger recalculations
        self._call_updaters = True

    #############
    # Properties
    #############

    @property
    def analysis_list(self) -> list[Analysis1d]:
        """Get the Analysis1d objects associated with this Analysis.

        Returns:
            list[Analysis1d]: A list of Analysis1d objects, one for
                each Q index.
        """
        return self._analysis_list

    @analysis_list.setter
    def analysis_list(self, value: list[Analysis1d]) -> None:
        """analysis_list is read-only.

        To change the analysis list, modify the experiment, sample
        model, or instrument model.

        Args:
            value (list[Analysis1d]): The new list of Analysis1d objects. This
                argument is ignored, as analysis_list is read-only.

        Raises:
            AttributeError: Always raised, since analysis_list is
                read-only.
        """

        raise AttributeError(
            'analysis_list is read-only. '
            'To change the analysis list, modify the experiment, sample model, '
            'or instrument model.'
        )

    #############
    # Other methods
    #############
    def calculate(
        self,
        Q_index: int | None = None,
        energy: sc.Variable | None = None,
    ) -> list[np.ndarray] | np.ndarray:
        """Calculate model data for a specific Q index. If Q_index is
        None, calculate for all Q indices and return a list of arrays.

        Args:
            Q_index (int | None, default=None): Index of the Q value to calculate
                for. If None, calculate for all Q values.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.

        Returns:
            list[np.ndarray] | np.ndarray: If Q_index is None, returns
                a list of numpy arrays, one for each Q index.
                If Q_index is an integer, returns a single numpy array
                for that Q index.
        """
        if energy is None:
            energy = self.energy

        if Q_index is None:
            return [analysis.calculate(energy=energy) for analysis in self.analysis_list]

        Q_index = self._verify_Q_index(Q_index)
        return self.analysis_list[Q_index].calculate(energy=energy)

    def fit(
        self,
        fit_method: str = 'independent',
        Q_index: int | None = None,
    ) -> FitResults | list[FitResults]:
        """Fit the model to the experimental data.

        Args:
            fit_method (str, default="independent"): Method to use for fitting. Options are
                "independent" (fit each Q index independently, one after
                the other) or "simultaneous" (fit all Q indices
                simultaneously). Default is "independent".
            Q_index (int | None, default=None): If fit_method is "independent",
                specify which Q index to fit. If None, fit all Q indices
                independently. Ignored if fit_method is "simultaneous".
                Default is None.

        Returns:
            FitResults | list[FitResults]: a list of FitResults if fitting independently,
                or a single FitResults object if fitting simultaneously.

        Raises:
            ValueError: If fit_method is not "independent" or
                "simultaneous" or if there are no Q values available for fitting.
        """

        if self.Q is None:
            raise ValueError(
                'No Q values available for fitting. Please check the experiment data.'
            )

        Q_index = self._verify_Q_index(Q_index)

        if fit_method == 'independent':
            if Q_index is not None:
                return self._fit_single_Q(Q_index)
            else:
                return self._fit_all_Q_independently()
        elif fit_method == 'simultaneous':
            return self._fit_all_Q_simultaneously()
        else:
            raise ValueError("Invalid fit method. Choose 'independent' or 'simultaneous'.")

    def plot_data_and_model(
        self,
        Q_index: int | None = None,
        plot_components: bool = True,
        add_background: bool = True,
        energy: sc.Variable | None = None,
        **kwargs: dict[str, Any],
    ) -> InteractiveFigure:
        """Plot the experimental data and the model prediction.
        Optionally also plot the individual components of the model.

        Uses Plopp for plotting: https://scipp.github.io/plopp/

        Args:
            Q_index (int | None, default=None): Index of the Q value to plot. If
                None, plot all Q values. Default is None.
            plot_components (bool, default=True): Whether to plot the individual
                components. Default is True.
            add_background (bool, default=True): Whether to add background components
                to the sample model components when plotting. Default is
                True.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.
            **kwargs (dict[str, Any]): Additional keyword arguments passed to plopp
                for customizing the plot.

        Raises:
            ValueError: If Q_index is out of bounds, or if there is no
                data to plot, or if there are no Q values available for
                plotting.
            RuntimeError: If not in a Jupyter notebook environment.
            TypeError: If plot_components or add_background is not True
                or False.

        Returns:
            InteractiveFigure: A Plopp InteractiveFigure containing the
                plot of the data and model.
        """

        if Q_index is not None:
            Q_index = self._verify_Q_index(Q_index)
            return self.analysis_list[Q_index].plot_data_and_model(
                plot_components=plot_components,
                add_background=add_background,
                energy=energy,
                **kwargs,
            )

        if self.experiment.binned_data is None:
            raise ValueError('No data to plot. Please load data first.')

        if not _in_notebook():
            raise RuntimeError('plot_data() can only be used in a Jupyter notebook environment.')

        if self.Q is None:
            raise ValueError(
                'No Q values available for plotting. Please check the experiment data.'
            )

        if not isinstance(plot_components, bool):
            raise TypeError('plot_components must be True or False.')

        if not isinstance(add_background, bool):
            raise TypeError('add_background must be True or False.')

        if energy is None:
            energy = self.energy

        import plopp as pp

        plot_kwargs_defaults = {
            'title': self.display_name,
            'linestyle': {'Data': 'none', 'Model': '-'},
            'marker': {'Data': 'o', 'Model': None},
            'color': {'Data': 'black', 'Model': 'red'},
            'markerfacecolor': {'Data': 'none', 'Model': 'none'},
            'keep': 'energy',
        }
        data_and_model = {
            'Data': self.experiment.binned_data,
            'Model': self._create_model_array(energy=energy),
        }

        if plot_components:
            components = self._create_components_dataset(
                add_background=add_background, energy=energy
            )
            for key in components.keys():
                data_and_model[key] = components[key]
                plot_kwargs_defaults['linestyle'][key] = '--'
                plot_kwargs_defaults['marker'][key] = None

        # Overwrite defaults with any user-provided kwargs
        plot_kwargs_defaults.update(kwargs)

        fig = pp.slicer(
            data_and_model,
            **plot_kwargs_defaults,
        )
        for widget in fig.bottom_bar[0].controls.values():
            widget.slider_toggler.value = '-o-'

        return fig

    def parameters_to_dataset(self) -> sc.Dataset:
        """Creates a scipp dataset with copies of the Parameters in the
        model.

        Ensures unit consistency across Q.

        Returns:
            sc.Dataset: A dataset where each entry is a parameter, with
                dimensions "Q" and values corresponding to the parameter
                values.

        Raises:
            UnitError: If there are inconsistent units for the same
                parameter across different Q values.
        """

        ds = sc.Dataset(coords={'Q': self.Q})

        # Collect all parameter names
        all_names = {
            param.name
            for analysis in self.analysis_list
            for param in analysis.get_all_parameters()
        }

        # Storage
        values = {name: [] for name in all_names}
        variances = {name: [] for name in all_names}
        units = {}

        for analysis in self.analysis_list:
            pars = {p.name: p for p in analysis.get_all_parameters()}

            for name in all_names:
                if name in pars:
                    p = pars[name]

                    # Unit consistency check
                    if name not in units:
                        units[name] = p.unit
                    elif units[name] != p.unit:
                        try:
                            p.convert_unit(units[name])
                        except Exception as e:
                            raise UnitError(
                                f"Inconsistent units for parameter '{name}': "
                                f'{units[name]} vs {p.unit}'
                            ) from e

                    values[name].append(p.value)
                    variances[name].append(p.variance)
                else:
                    values[name].append(np.nan)
                    variances[name].append(np.nan)

        # Build dataset variables
        for name in all_names:
            ds[name] = sc.Variable(
                dims=['Q'],
                values=np.asarray(values[name], dtype=float),
                variances=np.asarray(variances[name], dtype=float),
                unit=units.get(name, None),
            )

        return ds

    def plot_parameters(
        self,
        names: str | list[str] | None = None,
        **kwargs: dict[str, Any],
    ) -> InteractiveFigure:
        """Plot fitted parameters as a function of Q.

        Args:
            names (str | list[str] | None, default=None): Name(s) of the parameter(s)
                to plot. If None, plots all parameters.
            **kwargs (dict[str, Any]): Additional keyword arguments passed to
                plopp.slicer for customizing the plot (e.g., title,
                linestyle, marker, color).

        Returns:
            InteractiveFigure: A Plopp InteractiveFigure containing the
                plot of the parameters.

        Raises:
            TypeError: If names is not a string, list of strings, or None.
            ValueError: If any of the specified parameter names are not found in the dataset.
        """

        ds = self.parameters_to_dataset()

        if not names:
            names = list(ds.keys())

        if isinstance(names, str):
            names = [names]

        if not isinstance(names, list) or not all(isinstance(name, str) for name in names):
            raise TypeError('names must be a string or a list of strings.')

        for name in names:
            if name not in ds:
                raise ValueError(f"Parameter '{name}' not found in dataset.")

        data_to_plot = {name: ds[name] for name in names}
        plot_kwargs_defaults = {
            'linestyle': {name: 'none' for name in names},
            'marker': {name: 'o' for name in names},
            'markerfacecolor': {name: 'none' for name in names},
        }

        plot_kwargs_defaults.update(kwargs)

        import plopp as pp

        fig = pp.plot(
            data_to_plot,
            **plot_kwargs_defaults,
        )
        return fig

    #############
    # Private methods - updating models when things change
    #############

    def _on_experiment_changed(self) -> None:
        """Update the Q values in the sample and instrument models when
        the experiment changes.

        Also update all the Analysi1d objects with the new experiment.
        """
        if self._call_updaters:
            super()._on_experiment_changed()
            for analysis in self.analysis_list:
                analysis.experiment = self.experiment

    def _on_sample_model_changed(self) -> None:
        """Update the Q values in the sample model when the sample model
        changes.

        Also update all the Analysi1d objects with the new sample model.
        """
        if self._call_updaters:
            super()._on_sample_model_changed()
            for analysis in self.analysis_list:
                analysis.sample_model = self.sample_model

    def _on_instrument_model_changed(self) -> None:
        """Update the Q values in the instrument model when the
        instrument model changes.

        Also update all the Analysi1d objects with the new instrument
        model.
        """
        if self._call_updaters:
            super()._on_instrument_model_changed()
            for analysis in self.analysis_list:
                analysis.instrument_model = self.instrument_model

    #############
    # Private methods
    #############

    def _fit_single_Q(self, Q_index: int) -> FitResults:
        """Fit data for a single Q index.

        Args:
            Q_index (int): Index of the Q value to fit.

        Returns:
            FitResults: The results of the fit for the specified
                Q index.
        """

        Q_index = self._verify_Q_index(Q_index)

        return self.analysis_list[Q_index].fit()

    def _fit_all_Q_independently(self) -> list[FitResults]:
        """Fit data for all Q indices independently.

        Returns:
            list[FitResults]: A list of FitResults, one for each Q
                index.
        """
        return [analysis.fit() for analysis in self.analysis_list]

    def _fit_all_Q_simultaneously(self) -> FitResults:
        """Fit data for all Q indices simultaneously.

        Returns:
            FitResults: The results of the simultaneous fit across all
                Q indices.
        """

        xs = []
        ys = []
        ws = []

        for analysis in self.analysis_list:
            x, y, weight, _ = self.experiment._extract_x_y_weights_only_finite(analysis.Q_index)
            xs.append(x)
            ys.append(y)
            ws.append(weight)

            # Make sure the convolver is up to date for this Q index
            analysis._convolver = analysis._create_convolver(energy=x)

        mf = MultiFitter(
            fit_objects=self.analysis_list,
            fit_functions=self.get_fit_functions(),
        )

        results = mf.fit(
            x=xs,
            y=ys,
            weights=ws,
        )
        return results

    def get_fit_functions(self) -> list[callable]:
        """Get fit functions for all Q indices, which can be used for
        simultaneous fitting.

        Returns:
            list[callable]: A list of fit functions, one for each
                Q index.
        """
        return [analysis.as_fit_function() for analysis in self.analysis_list]

    def _create_model_array(self, energy: sc.Variable | None = None) -> sc.DataArray:
        """Create a scipp array for the model.

        Args:
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.

        Returns:
            sc.DataArray: A DataArray containing the model values, with
                dimensions "Q" and "energy".
        """
        if energy is None:
            energy = self.energy
        model = sc.array(dims=['Q', 'energy'], values=self.calculate(energy=energy))
        model_data_array = sc.DataArray(
            data=model,
            coords={'Q': self.Q, 'energy': energy},
        )
        return model_data_array

    def _create_components_dataset(
        self,
        add_background: bool = True,
        energy: sc.Variable | None = None,
    ) -> sc.Dataset:
        """Create a scipp dataset containing the individual components
        of the model for plotting.

        Args:
            add_background (bool, default=True): Whether to add background components
                to the sample model components when creating the
                dataset.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the components. If None, uses the energy from
                the experiment.

        Raises:
            TypeError: If add_background is not True or False.

        Returns:
            sc.Dataset: A scipp Dataset where each entry is a component
                of the model, with dimensions "Q".
        """
        if not isinstance(add_background, bool):
            raise TypeError('add_background must be True or False.')

        if energy is None:
            energy = self.energy

        datasets = [
            analysis._create_components_dataset_single_Q(
                add_background=add_background, energy=energy
            )
            for analysis in self.analysis_list
        ]

        return sc.concat(datasets, dim='Q')

__init__(display_name='MyAnalysis', unique_name=None, experiment=None, sample_model=None, instrument_model=None, extra_parameters=None)

Initialize an Analysis object.

Parameters:

Name	Type	Description	Default
display_name	str | None, default='MyAnalysis'	Display name of the analysis.	'MyAnalysis'
unique_name	str | None, default=None	Unique name of the analysis. If None, a unique name is automatically generated.	None
experiment	Experiment | None, default=None	The Experiment associated with this Analysis. If None, a default Experiment is created.	None
sample_model	SampleModel | None, default=None	The SampleModel associated with this Analysis. If None, a default SampleModel is created.	None
instrument_model	InstrumentModel | None, default=None	The InstrumentModel associated with this Analysis. If None, a default InstrumentModel is created.	None
extra_parameters	Parameter | list[Parameter] | None, default=None	Extra parameters to be included in the analysis for advanced users. If None, no extra parameters are added.	None

Source code in src/easydynamics/analysis/analysis.py

def __init__(
    self,
    display_name: str | None = 'MyAnalysis',
    unique_name: str | None = None,
    experiment: Experiment | None = None,
    sample_model: SampleModel | None = None,
    instrument_model: InstrumentModel | None = None,
    extra_parameters: Parameter | list[Parameter] | None = None,
) -> None:
    """Initialize an Analysis object.

    Args:
        display_name (str | None, default='MyAnalysis'): Display name of the analysis.
        unique_name (str | None, default=None): Unique name of the analysis. If
            None, a unique name is automatically generated.
        experiment (Experiment | None, default=None): The Experiment associated
            with this Analysis. If None, a default Experiment is
            created.
        sample_model (SampleModel | None, default=None): The SampleModel
            associated with this Analysis. If None, a default
            SampleModel is created.
        instrument_model (InstrumentModel | None, default=None): The
            InstrumentModel associated with this Analysis. If None,
            a default InstrumentModel is created.
        extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
            parameters to be included in the analysis for advanced
            users. If None, no extra parameters are added.
    """

    # Avoid triggering updates before the object is fully
    # initialized
    self._call_updaters = False
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        experiment=experiment,
        sample_model=sample_model,
        instrument_model=instrument_model,
        extra_parameters=extra_parameters,
    )

    self._analysis_list = []
    if self.Q is not None:
        for Q_index in range(len(self.Q)):
            analysis = Analysis1d(
                display_name=f'{self.display_name}_Q{Q_index}',
                unique_name=(f'{self.unique_name}_Q{Q_index}'),
                experiment=self.experiment,
                sample_model=self.sample_model,
                instrument_model=self.instrument_model,
                extra_parameters=self._extra_parameters,
                Q_index=Q_index,
            )
            self._analysis_list.append(analysis)
    # Now we can allow updates to trigger recalculations
    self._call_updaters = True

analysis_list property writable

Get the Analysis1d objects associated with this Analysis.

Returns:

Type	Description
list[Analysis1d]	list[Analysis1d]: A list of Analysis1d objects, one for each Q index.

calculate(Q_index=None, energy=None)

Calculate model data for a specific Q index. If Q_index is None, calculate for all Q indices and return a list of arrays.

Parameters:

Name	Type	Description	Default
Q_index	int | None, default=None	Index of the Q value to calculate for. If None, calculate for all Q values.	None
energy	sc.Variable | None, default=None	The energy values to use for calculating the model. If None, uses the energy from the experiment.	None

Returns:

Type	Description
list[ndarray] | ndarray	list[np.ndarray] | np.ndarray: If Q_index is None, returns a list of numpy arrays, one for each Q index. If Q_index is an integer, returns a single numpy array for that Q index.

Source code in src/easydynamics/analysis/analysis.py

def calculate(
    self,
    Q_index: int | None = None,
    energy: sc.Variable | None = None,
) -> list[np.ndarray] | np.ndarray:
    """Calculate model data for a specific Q index. If Q_index is
    None, calculate for all Q indices and return a list of arrays.

    Args:
        Q_index (int | None, default=None): Index of the Q value to calculate
            for. If None, calculate for all Q values.
        energy (sc.Variable | None, default=None): The energy values to use for
            calculating the model. If None, uses the energy from the
            experiment.

    Returns:
        list[np.ndarray] | np.ndarray: If Q_index is None, returns
            a list of numpy arrays, one for each Q index.
            If Q_index is an integer, returns a single numpy array
            for that Q index.
    """
    if energy is None:
        energy = self.energy

    if Q_index is None:
        return [analysis.calculate(energy=energy) for analysis in self.analysis_list]

    Q_index = self._verify_Q_index(Q_index)
    return self.analysis_list[Q_index].calculate(energy=energy)

fit(fit_method='independent', Q_index=None)

Fit the model to the experimental data.

Parameters:

Name	Type	Description	Default
fit_method	str, default="independent"	Method to use for fitting. Options are "independent" (fit each Q index independently, one after the other) or "simultaneous" (fit all Q indices simultaneously). Default is "independent".	'independent'
Q_index	int | None, default=None	If fit_method is "independent", specify which Q index to fit. If None, fit all Q indices independently. Ignored if fit_method is "simultaneous". Default is None.	None

Returns:

Type	Description
FitResults | list[FitResults]	FitResults | list[FitResults]: a list of FitResults if fitting independently, or a single FitResults object if fitting simultaneously.

Raises:

Type	Description
ValueError	If fit_method is not "independent" or "simultaneous" or if there are no Q values available for fitting.

Source code in src/easydynamics/analysis/analysis.py

def fit(
    self,
    fit_method: str = 'independent',
    Q_index: int | None = None,
) -> FitResults | list[FitResults]:
    """Fit the model to the experimental data.

    Args:
        fit_method (str, default="independent"): Method to use for fitting. Options are
            "independent" (fit each Q index independently, one after
            the other) or "simultaneous" (fit all Q indices
            simultaneously). Default is "independent".
        Q_index (int | None, default=None): If fit_method is "independent",
            specify which Q index to fit. If None, fit all Q indices
            independently. Ignored if fit_method is "simultaneous".
            Default is None.

    Returns:
        FitResults | list[FitResults]: a list of FitResults if fitting independently,
            or a single FitResults object if fitting simultaneously.

    Raises:
        ValueError: If fit_method is not "independent" or
            "simultaneous" or if there are no Q values available for fitting.
    """

    if self.Q is None:
        raise ValueError(
            'No Q values available for fitting. Please check the experiment data.'
        )

    Q_index = self._verify_Q_index(Q_index)

    if fit_method == 'independent':
        if Q_index is not None:
            return self._fit_single_Q(Q_index)
        else:
            return self._fit_all_Q_independently()
    elif fit_method == 'simultaneous':
        return self._fit_all_Q_simultaneously()
    else:
        raise ValueError("Invalid fit method. Choose 'independent' or 'simultaneous'.")

get_fit_functions()

Get fit functions for all Q indices, which can be used for simultaneous fitting.

Returns:

Type	Description
list[callable]	list[callable]: A list of fit functions, one for each Q index.

Source code in src/easydynamics/analysis/analysis.py

def get_fit_functions(self) -> list[callable]:
    """Get fit functions for all Q indices, which can be used for
    simultaneous fitting.

    Returns:
        list[callable]: A list of fit functions, one for each
            Q index.
    """
    return [analysis.as_fit_function() for analysis in self.analysis_list]

parameters_to_dataset()

Creates a scipp dataset with copies of the Parameters in the model.

Ensures unit consistency across Q.

Returns:

Type	Description
Dataset	sc.Dataset: A dataset where each entry is a parameter, with dimensions "Q" and values corresponding to the parameter values.

Raises:

Type	Description
UnitError	If there are inconsistent units for the same parameter across different Q values.

Source code in src/easydynamics/analysis/analysis.py

def parameters_to_dataset(self) -> sc.Dataset:
    """Creates a scipp dataset with copies of the Parameters in the
    model.

    Ensures unit consistency across Q.

    Returns:
        sc.Dataset: A dataset where each entry is a parameter, with
            dimensions "Q" and values corresponding to the parameter
            values.

    Raises:
        UnitError: If there are inconsistent units for the same
            parameter across different Q values.
    """

    ds = sc.Dataset(coords={'Q': self.Q})

    # Collect all parameter names
    all_names = {
        param.name
        for analysis in self.analysis_list
        for param in analysis.get_all_parameters()
    }

    # Storage
    values = {name: [] for name in all_names}
    variances = {name: [] for name in all_names}
    units = {}

    for analysis in self.analysis_list:
        pars = {p.name: p for p in analysis.get_all_parameters()}

        for name in all_names:
            if name in pars:
                p = pars[name]

                # Unit consistency check
                if name not in units:
                    units[name] = p.unit
                elif units[name] != p.unit:
                    try:
                        p.convert_unit(units[name])
                    except Exception as e:
                        raise UnitError(
                            f"Inconsistent units for parameter '{name}': "
                            f'{units[name]} vs {p.unit}'
                        ) from e

                values[name].append(p.value)
                variances[name].append(p.variance)
            else:
                values[name].append(np.nan)
                variances[name].append(np.nan)

    # Build dataset variables
    for name in all_names:
        ds[name] = sc.Variable(
            dims=['Q'],
            values=np.asarray(values[name], dtype=float),
            variances=np.asarray(variances[name], dtype=float),
            unit=units.get(name, None),
        )

    return ds

plot_data_and_model(Q_index=None, plot_components=True, add_background=True, energy=None, **kwargs)

Plot the experimental data and the model prediction. Optionally also plot the individual components of the model.

Uses Plopp for plotting: https://scipp.github.io/plopp/

Parameters:

Name	Type	Description	Default
Q_index	int | None, default=None	Index of the Q value to plot. If None, plot all Q values. Default is None.	None
plot_components	bool, default=True	Whether to plot the individual components. Default is True.	True
add_background	bool, default=True	Whether to add background components to the sample model components when plotting. Default is True.	True
energy	sc.Variable | None, default=None	The energy values to use for calculating the model. If None, uses the energy from the experiment.	None
**kwargs	dict[str, Any]	Additional keyword arguments passed to plopp for customizing the plot.	{}

Raises:

Type	Description
ValueError	If Q_index is out of bounds, or if there is no data to plot, or if there are no Q values available for plotting.
RuntimeError	If not in a Jupyter notebook environment.
TypeError	If plot_components or add_background is not True or False.

Returns:

Name	Type	Description
InteractiveFigure	InteractiveFigure	A Plopp InteractiveFigure containing the plot of the data and model.

Source code in src/easydynamics/analysis/analysis.py

def plot_data_and_model(
    self,
    Q_index: int | None = None,
    plot_components: bool = True,
    add_background: bool = True,
    energy: sc.Variable | None = None,
    **kwargs: dict[str, Any],
) -> InteractiveFigure:
    """Plot the experimental data and the model prediction.
    Optionally also plot the individual components of the model.

    Uses Plopp for plotting: https://scipp.github.io/plopp/

    Args:
        Q_index (int | None, default=None): Index of the Q value to plot. If
            None, plot all Q values. Default is None.
        plot_components (bool, default=True): Whether to plot the individual
            components. Default is True.
        add_background (bool, default=True): Whether to add background components
            to the sample model components when plotting. Default is
            True.
        energy (sc.Variable | None, default=None): The energy values to use for
            calculating the model. If None, uses the energy from the
            experiment.
        **kwargs (dict[str, Any]): Additional keyword arguments passed to plopp
            for customizing the plot.

    Raises:
        ValueError: If Q_index is out of bounds, or if there is no
            data to plot, or if there are no Q values available for
            plotting.
        RuntimeError: If not in a Jupyter notebook environment.
        TypeError: If plot_components or add_background is not True
            or False.

    Returns:
        InteractiveFigure: A Plopp InteractiveFigure containing the
            plot of the data and model.
    """

    if Q_index is not None:
        Q_index = self._verify_Q_index(Q_index)
        return self.analysis_list[Q_index].plot_data_and_model(
            plot_components=plot_components,
            add_background=add_background,
            energy=energy,
            **kwargs,
        )

    if self.experiment.binned_data is None:
        raise ValueError('No data to plot. Please load data first.')

    if not _in_notebook():
        raise RuntimeError('plot_data() can only be used in a Jupyter notebook environment.')

    if self.Q is None:
        raise ValueError(
            'No Q values available for plotting. Please check the experiment data.'
        )

    if not isinstance(plot_components, bool):
        raise TypeError('plot_components must be True or False.')

    if not isinstance(add_background, bool):
        raise TypeError('add_background must be True or False.')

    if energy is None:
        energy = self.energy

    import plopp as pp

    plot_kwargs_defaults = {
        'title': self.display_name,
        'linestyle': {'Data': 'none', 'Model': '-'},
        'marker': {'Data': 'o', 'Model': None},
        'color': {'Data': 'black', 'Model': 'red'},
        'markerfacecolor': {'Data': 'none', 'Model': 'none'},
        'keep': 'energy',
    }
    data_and_model = {
        'Data': self.experiment.binned_data,
        'Model': self._create_model_array(energy=energy),
    }

    if plot_components:
        components = self._create_components_dataset(
            add_background=add_background, energy=energy
        )
        for key in components.keys():
            data_and_model[key] = components[key]
            plot_kwargs_defaults['linestyle'][key] = '--'
            plot_kwargs_defaults['marker'][key] = None

    # Overwrite defaults with any user-provided kwargs
    plot_kwargs_defaults.update(kwargs)

    fig = pp.slicer(
        data_and_model,
        **plot_kwargs_defaults,
    )
    for widget in fig.bottom_bar[0].controls.values():
        widget.slider_toggler.value = '-o-'

    return fig

plot_parameters(names=None, **kwargs)

Plot fitted parameters as a function of Q.

Parameters:

Name	Type	Description	Default
names	str | list[str] | None, default=None	Name(s) of the parameter(s) to plot. If None, plots all parameters.	None
**kwargs	dict[str, Any]	Additional keyword arguments passed to plopp.slicer for customizing the plot (e.g., title, linestyle, marker, color).	{}

Returns:

Name	Type	Description
InteractiveFigure	InteractiveFigure	A Plopp InteractiveFigure containing the plot of the parameters.

Raises:

Type	Description
TypeError	If names is not a string, list of strings, or None.
ValueError	If any of the specified parameter names are not found in the dataset.

Source code in src/easydynamics/analysis/analysis.py

def plot_parameters(
    self,
    names: str | list[str] | None = None,
    **kwargs: dict[str, Any],
) -> InteractiveFigure:
    """Plot fitted parameters as a function of Q.

    Args:
        names (str | list[str] | None, default=None): Name(s) of the parameter(s)
            to plot. If None, plots all parameters.
        **kwargs (dict[str, Any]): Additional keyword arguments passed to
            plopp.slicer for customizing the plot (e.g., title,
            linestyle, marker, color).

    Returns:
        InteractiveFigure: A Plopp InteractiveFigure containing the
            plot of the parameters.

    Raises:
        TypeError: If names is not a string, list of strings, or None.
        ValueError: If any of the specified parameter names are not found in the dataset.
    """

    ds = self.parameters_to_dataset()

    if not names:
        names = list(ds.keys())

    if isinstance(names, str):
        names = [names]

    if not isinstance(names, list) or not all(isinstance(name, str) for name in names):
        raise TypeError('names must be a string or a list of strings.')

    for name in names:
        if name not in ds:
            raise ValueError(f"Parameter '{name}' not found in dataset.")

    data_to_plot = {name: ds[name] for name in names}
    plot_kwargs_defaults = {
        'linestyle': {name: 'none' for name in names},
        'marker': {name: 'o' for name in names},
        'markerfacecolor': {name: 'none' for name in names},
    }

    plot_kwargs_defaults.update(kwargs)

    import plopp as pp

    fig = pp.plot(
        data_to_plot,
        **plot_kwargs_defaults,
    )
    return fig

analysis

Analysis

Bases: AnalysisBase

For analysing two-dimensional data, i.e. intensity as function of energy and Q.

Supports independent fits of each Q value and simultaneous fits of all Q.

Source code in src/easydynamics/analysis/analysis.py

class Analysis(AnalysisBase):
    """For analysing two-dimensional data, i.e. intensity as function of
    energy and Q.

    Supports independent fits of each Q value and simultaneous fits of
    all Q.
    """

    def __init__(
        self,
        display_name: str | None = 'MyAnalysis',
        unique_name: str | None = None,
        experiment: Experiment | None = None,
        sample_model: SampleModel | None = None,
        instrument_model: InstrumentModel | None = None,
        extra_parameters: Parameter | list[Parameter] | None = None,
    ) -> None:
        """Initialize an Analysis object.

        Args:
            display_name (str | None, default='MyAnalysis'): Display name of the analysis.
            unique_name (str | None, default=None): Unique name of the analysis. If
                None, a unique name is automatically generated.
            experiment (Experiment | None, default=None): The Experiment associated
                with this Analysis. If None, a default Experiment is
                created.
            sample_model (SampleModel | None, default=None): The SampleModel
                associated with this Analysis. If None, a default
                SampleModel is created.
            instrument_model (InstrumentModel | None, default=None): The
                InstrumentModel associated with this Analysis. If None,
                a default InstrumentModel is created.
            extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
                parameters to be included in the analysis for advanced
                users. If None, no extra parameters are added.
        """

        # Avoid triggering updates before the object is fully
        # initialized
        self._call_updaters = False
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            experiment=experiment,
            sample_model=sample_model,
            instrument_model=instrument_model,
            extra_parameters=extra_parameters,
        )

        self._analysis_list = []
        if self.Q is not None:
            for Q_index in range(len(self.Q)):
                analysis = Analysis1d(
                    display_name=f'{self.display_name}_Q{Q_index}',
                    unique_name=(f'{self.unique_name}_Q{Q_index}'),
                    experiment=self.experiment,
                    sample_model=self.sample_model,
                    instrument_model=self.instrument_model,
                    extra_parameters=self._extra_parameters,
                    Q_index=Q_index,
                )
                self._analysis_list.append(analysis)
        # Now we can allow updates to trigger recalculations
        self._call_updaters = True

    #############
    # Properties
    #############

    @property
    def analysis_list(self) -> list[Analysis1d]:
        """Get the Analysis1d objects associated with this Analysis.

        Returns:
            list[Analysis1d]: A list of Analysis1d objects, one for
                each Q index.
        """
        return self._analysis_list

    @analysis_list.setter
    def analysis_list(self, value: list[Analysis1d]) -> None:
        """analysis_list is read-only.

        To change the analysis list, modify the experiment, sample
        model, or instrument model.

        Args:
            value (list[Analysis1d]): The new list of Analysis1d objects. This
                argument is ignored, as analysis_list is read-only.

        Raises:
            AttributeError: Always raised, since analysis_list is
                read-only.
        """

        raise AttributeError(
            'analysis_list is read-only. '
            'To change the analysis list, modify the experiment, sample model, '
            'or instrument model.'
        )

    #############
    # Other methods
    #############
    def calculate(
        self,
        Q_index: int | None = None,
        energy: sc.Variable | None = None,
    ) -> list[np.ndarray] | np.ndarray:
        """Calculate model data for a specific Q index. If Q_index is
        None, calculate for all Q indices and return a list of arrays.

        Args:
            Q_index (int | None, default=None): Index of the Q value to calculate
                for. If None, calculate for all Q values.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.

        Returns:
            list[np.ndarray] | np.ndarray: If Q_index is None, returns
                a list of numpy arrays, one for each Q index.
                If Q_index is an integer, returns a single numpy array
                for that Q index.
        """
        if energy is None:
            energy = self.energy

        if Q_index is None:
            return [analysis.calculate(energy=energy) for analysis in self.analysis_list]

        Q_index = self._verify_Q_index(Q_index)
        return self.analysis_list[Q_index].calculate(energy=energy)

    def fit(
        self,
        fit_method: str = 'independent',
        Q_index: int | None = None,
    ) -> FitResults | list[FitResults]:
        """Fit the model to the experimental data.

        Args:
            fit_method (str, default="independent"): Method to use for fitting. Options are
                "independent" (fit each Q index independently, one after
                the other) or "simultaneous" (fit all Q indices
                simultaneously). Default is "independent".
            Q_index (int | None, default=None): If fit_method is "independent",
                specify which Q index to fit. If None, fit all Q indices
                independently. Ignored if fit_method is "simultaneous".
                Default is None.

        Returns:
            FitResults | list[FitResults]: a list of FitResults if fitting independently,
                or a single FitResults object if fitting simultaneously.

        Raises:
            ValueError: If fit_method is not "independent" or
                "simultaneous" or if there are no Q values available for fitting.
        """

        if self.Q is None:
            raise ValueError(
                'No Q values available for fitting. Please check the experiment data.'
            )

        Q_index = self._verify_Q_index(Q_index)

        if fit_method == 'independent':
            if Q_index is not None:
                return self._fit_single_Q(Q_index)
            else:
                return self._fit_all_Q_independently()
        elif fit_method == 'simultaneous':
            return self._fit_all_Q_simultaneously()
        else:
            raise ValueError("Invalid fit method. Choose 'independent' or 'simultaneous'.")

    def plot_data_and_model(
        self,
        Q_index: int | None = None,
        plot_components: bool = True,
        add_background: bool = True,
        energy: sc.Variable | None = None,
        **kwargs: dict[str, Any],
    ) -> InteractiveFigure:
        """Plot the experimental data and the model prediction.
        Optionally also plot the individual components of the model.

        Uses Plopp for plotting: https://scipp.github.io/plopp/

        Args:
            Q_index (int | None, default=None): Index of the Q value to plot. If
                None, plot all Q values. Default is None.
            plot_components (bool, default=True): Whether to plot the individual
                components. Default is True.
            add_background (bool, default=True): Whether to add background components
                to the sample model components when plotting. Default is
                True.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.
            **kwargs (dict[str, Any]): Additional keyword arguments passed to plopp
                for customizing the plot.

        Raises:
            ValueError: If Q_index is out of bounds, or if there is no
                data to plot, or if there are no Q values available for
                plotting.
            RuntimeError: If not in a Jupyter notebook environment.
            TypeError: If plot_components or add_background is not True
                or False.

        Returns:
            InteractiveFigure: A Plopp InteractiveFigure containing the
                plot of the data and model.
        """

        if Q_index is not None:
            Q_index = self._verify_Q_index(Q_index)
            return self.analysis_list[Q_index].plot_data_and_model(
                plot_components=plot_components,
                add_background=add_background,
                energy=energy,
                **kwargs,
            )

        if self.experiment.binned_data is None:
            raise ValueError('No data to plot. Please load data first.')

        if not _in_notebook():
            raise RuntimeError('plot_data() can only be used in a Jupyter notebook environment.')

        if self.Q is None:
            raise ValueError(
                'No Q values available for plotting. Please check the experiment data.'
            )

        if not isinstance(plot_components, bool):
            raise TypeError('plot_components must be True or False.')

        if not isinstance(add_background, bool):
            raise TypeError('add_background must be True or False.')

        if energy is None:
            energy = self.energy

        import plopp as pp

        plot_kwargs_defaults = {
            'title': self.display_name,
            'linestyle': {'Data': 'none', 'Model': '-'},
            'marker': {'Data': 'o', 'Model': None},
            'color': {'Data': 'black', 'Model': 'red'},
            'markerfacecolor': {'Data': 'none', 'Model': 'none'},
            'keep': 'energy',
        }
        data_and_model = {
            'Data': self.experiment.binned_data,
            'Model': self._create_model_array(energy=energy),
        }

        if plot_components:
            components = self._create_components_dataset(
                add_background=add_background, energy=energy
            )
            for key in components.keys():
                data_and_model[key] = components[key]
                plot_kwargs_defaults['linestyle'][key] = '--'
                plot_kwargs_defaults['marker'][key] = None

        # Overwrite defaults with any user-provided kwargs
        plot_kwargs_defaults.update(kwargs)

        fig = pp.slicer(
            data_and_model,
            **plot_kwargs_defaults,
        )
        for widget in fig.bottom_bar[0].controls.values():
            widget.slider_toggler.value = '-o-'

        return fig

    def parameters_to_dataset(self) -> sc.Dataset:
        """Creates a scipp dataset with copies of the Parameters in the
        model.

        Ensures unit consistency across Q.

        Returns:
            sc.Dataset: A dataset where each entry is a parameter, with
                dimensions "Q" and values corresponding to the parameter
                values.

        Raises:
            UnitError: If there are inconsistent units for the same
                parameter across different Q values.
        """

        ds = sc.Dataset(coords={'Q': self.Q})

        # Collect all parameter names
        all_names = {
            param.name
            for analysis in self.analysis_list
            for param in analysis.get_all_parameters()
        }

        # Storage
        values = {name: [] for name in all_names}
        variances = {name: [] for name in all_names}
        units = {}

        for analysis in self.analysis_list:
            pars = {p.name: p for p in analysis.get_all_parameters()}

            for name in all_names:
                if name in pars:
                    p = pars[name]

                    # Unit consistency check
                    if name not in units:
                        units[name] = p.unit
                    elif units[name] != p.unit:
                        try:
                            p.convert_unit(units[name])
                        except Exception as e:
                            raise UnitError(
                                f"Inconsistent units for parameter '{name}': "
                                f'{units[name]} vs {p.unit}'
                            ) from e

                    values[name].append(p.value)
                    variances[name].append(p.variance)
                else:
                    values[name].append(np.nan)
                    variances[name].append(np.nan)

        # Build dataset variables
        for name in all_names:
            ds[name] = sc.Variable(
                dims=['Q'],
                values=np.asarray(values[name], dtype=float),
                variances=np.asarray(variances[name], dtype=float),
                unit=units.get(name, None),
            )

        return ds

    def plot_parameters(
        self,
        names: str | list[str] | None = None,
        **kwargs: dict[str, Any],
    ) -> InteractiveFigure:
        """Plot fitted parameters as a function of Q.

        Args:
            names (str | list[str] | None, default=None): Name(s) of the parameter(s)
                to plot. If None, plots all parameters.
            **kwargs (dict[str, Any]): Additional keyword arguments passed to
                plopp.slicer for customizing the plot (e.g., title,
                linestyle, marker, color).

        Returns:
            InteractiveFigure: A Plopp InteractiveFigure containing the
                plot of the parameters.

        Raises:
            TypeError: If names is not a string, list of strings, or None.
            ValueError: If any of the specified parameter names are not found in the dataset.
        """

        ds = self.parameters_to_dataset()

        if not names:
            names = list(ds.keys())

        if isinstance(names, str):
            names = [names]

        if not isinstance(names, list) or not all(isinstance(name, str) for name in names):
            raise TypeError('names must be a string or a list of strings.')

        for name in names:
            if name not in ds:
                raise ValueError(f"Parameter '{name}' not found in dataset.")

        data_to_plot = {name: ds[name] for name in names}
        plot_kwargs_defaults = {
            'linestyle': {name: 'none' for name in names},
            'marker': {name: 'o' for name in names},
            'markerfacecolor': {name: 'none' for name in names},
        }

        plot_kwargs_defaults.update(kwargs)

        import plopp as pp

        fig = pp.plot(
            data_to_plot,
            **plot_kwargs_defaults,
        )
        return fig

    #############
    # Private methods - updating models when things change
    #############

    def _on_experiment_changed(self) -> None:
        """Update the Q values in the sample and instrument models when
        the experiment changes.

        Also update all the Analysi1d objects with the new experiment.
        """
        if self._call_updaters:
            super()._on_experiment_changed()
            for analysis in self.analysis_list:
                analysis.experiment = self.experiment

    def _on_sample_model_changed(self) -> None:
        """Update the Q values in the sample model when the sample model
        changes.

        Also update all the Analysi1d objects with the new sample model.
        """
        if self._call_updaters:
            super()._on_sample_model_changed()
            for analysis in self.analysis_list:
                analysis.sample_model = self.sample_model

    def _on_instrument_model_changed(self) -> None:
        """Update the Q values in the instrument model when the
        instrument model changes.

        Also update all the Analysi1d objects with the new instrument
        model.
        """
        if self._call_updaters:
            super()._on_instrument_model_changed()
            for analysis in self.analysis_list:
                analysis.instrument_model = self.instrument_model

    #############
    # Private methods
    #############

    def _fit_single_Q(self, Q_index: int) -> FitResults:
        """Fit data for a single Q index.

        Args:
            Q_index (int): Index of the Q value to fit.

        Returns:
            FitResults: The results of the fit for the specified
                Q index.
        """

        Q_index = self._verify_Q_index(Q_index)

        return self.analysis_list[Q_index].fit()

    def _fit_all_Q_independently(self) -> list[FitResults]:
        """Fit data for all Q indices independently.

        Returns:
            list[FitResults]: A list of FitResults, one for each Q
                index.
        """
        return [analysis.fit() for analysis in self.analysis_list]

    def _fit_all_Q_simultaneously(self) -> FitResults:
        """Fit data for all Q indices simultaneously.

        Returns:
            FitResults: The results of the simultaneous fit across all
                Q indices.
        """

        xs = []
        ys = []
        ws = []

        for analysis in self.analysis_list:
            x, y, weight, _ = self.experiment._extract_x_y_weights_only_finite(analysis.Q_index)
            xs.append(x)
            ys.append(y)
            ws.append(weight)

            # Make sure the convolver is up to date for this Q index
            analysis._convolver = analysis._create_convolver(energy=x)

        mf = MultiFitter(
            fit_objects=self.analysis_list,
            fit_functions=self.get_fit_functions(),
        )

        results = mf.fit(
            x=xs,
            y=ys,
            weights=ws,
        )
        return results

    def get_fit_functions(self) -> list[callable]:
        """Get fit functions for all Q indices, which can be used for
        simultaneous fitting.

        Returns:
            list[callable]: A list of fit functions, one for each
                Q index.
        """
        return [analysis.as_fit_function() for analysis in self.analysis_list]

    def _create_model_array(self, energy: sc.Variable | None = None) -> sc.DataArray:
        """Create a scipp array for the model.

        Args:
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the model. If None, uses the energy from the
                experiment.

        Returns:
            sc.DataArray: A DataArray containing the model values, with
                dimensions "Q" and "energy".
        """
        if energy is None:
            energy = self.energy
        model = sc.array(dims=['Q', 'energy'], values=self.calculate(energy=energy))
        model_data_array = sc.DataArray(
            data=model,
            coords={'Q': self.Q, 'energy': energy},
        )
        return model_data_array

    def _create_components_dataset(
        self,
        add_background: bool = True,
        energy: sc.Variable | None = None,
    ) -> sc.Dataset:
        """Create a scipp dataset containing the individual components
        of the model for plotting.

        Args:
            add_background (bool, default=True): Whether to add background components
                to the sample model components when creating the
                dataset.
            energy (sc.Variable | None, default=None): The energy values to use for
                calculating the components. If None, uses the energy from
                the experiment.

        Raises:
            TypeError: If add_background is not True or False.

        Returns:
            sc.Dataset: A scipp Dataset where each entry is a component
                of the model, with dimensions "Q".
        """
        if not isinstance(add_background, bool):
            raise TypeError('add_background must be True or False.')

        if energy is None:
            energy = self.energy

        datasets = [
            analysis._create_components_dataset_single_Q(
                add_background=add_background, energy=energy
            )
            for analysis in self.analysis_list
        ]

        return sc.concat(datasets, dim='Q')

__init__(display_name='MyAnalysis', unique_name=None, experiment=None, sample_model=None, instrument_model=None, extra_parameters=None)

Initialize an Analysis object.

Parameters:

Name	Type	Description	Default
display_name	str | None, default='MyAnalysis'	Display name of the analysis.	'MyAnalysis'
unique_name	str | None, default=None	Unique name of the analysis. If None, a unique name is automatically generated.	None
experiment	Experiment | None, default=None	The Experiment associated with this Analysis. If None, a default Experiment is created.	None
sample_model	SampleModel | None, default=None	The SampleModel associated with this Analysis. If None, a default SampleModel is created.	None
instrument_model	InstrumentModel | None, default=None	The InstrumentModel associated with this Analysis. If None, a default InstrumentModel is created.	None
extra_parameters	Parameter | list[Parameter] | None, default=None	Extra parameters to be included in the analysis for advanced users. If None, no extra parameters are added.	None

Source code in src/easydynamics/analysis/analysis.py

def __init__(
    self,
    display_name: str | None = 'MyAnalysis',
    unique_name: str | None = None,
    experiment: Experiment | None = None,
    sample_model: SampleModel | None = None,
    instrument_model: InstrumentModel | None = None,
    extra_parameters: Parameter | list[Parameter] | None = None,
) -> None:
    """Initialize an Analysis object.

    Args:
        display_name (str | None, default='MyAnalysis'): Display name of the analysis.
        unique_name (str | None, default=None): Unique name of the analysis. If
            None, a unique name is automatically generated.
        experiment (Experiment | None, default=None): The Experiment associated
            with this Analysis. If None, a default Experiment is
            created.
        sample_model (SampleModel | None, default=None): The SampleModel
            associated with this Analysis. If None, a default
            SampleModel is created.
        instrument_model (InstrumentModel | None, default=None): The
            InstrumentModel associated with this Analysis. If None,
            a default InstrumentModel is created.
        extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
            parameters to be included in the analysis for advanced
            users. If None, no extra parameters are added.
    """

    # Avoid triggering updates before the object is fully
    # initialized
    self._call_updaters = False
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        experiment=experiment,
        sample_model=sample_model,
        instrument_model=instrument_model,
        extra_parameters=extra_parameters,
    )

    self._analysis_list = []
    if self.Q is not None:
        for Q_index in range(len(self.Q)):
            analysis = Analysis1d(
                display_name=f'{self.display_name}_Q{Q_index}',
                unique_name=(f'{self.unique_name}_Q{Q_index}'),
                experiment=self.experiment,
                sample_model=self.sample_model,
                instrument_model=self.instrument_model,
                extra_parameters=self._extra_parameters,
                Q_index=Q_index,
            )
            self._analysis_list.append(analysis)
    # Now we can allow updates to trigger recalculations
    self._call_updaters = True

analysis_list property writable

Get the Analysis1d objects associated with this Analysis.

Returns:

Type	Description
list[Analysis1d]	list[Analysis1d]: A list of Analysis1d objects, one for each Q index.

calculate(Q_index=None, energy=None)

Calculate model data for a specific Q index. If Q_index is None, calculate for all Q indices and return a list of arrays.

Parameters:

Name	Type	Description	Default
Q_index	int | None, default=None	Index of the Q value to calculate for. If None, calculate for all Q values.	None
energy	sc.Variable | None, default=None	The energy values to use for calculating the model. If None, uses the energy from the experiment.	None

Returns:

Type	Description
list[ndarray] | ndarray	list[np.ndarray] | np.ndarray: If Q_index is None, returns a list of numpy arrays, one for each Q index. If Q_index is an integer, returns a single numpy array for that Q index.

Source code in src/easydynamics/analysis/analysis.py

def calculate(
    self,
    Q_index: int | None = None,
    energy: sc.Variable | None = None,
) -> list[np.ndarray] | np.ndarray:
    """Calculate model data for a specific Q index. If Q_index is
    None, calculate for all Q indices and return a list of arrays.

    Args:
        Q_index (int | None, default=None): Index of the Q value to calculate
            for. If None, calculate for all Q values.
        energy (sc.Variable | None, default=None): The energy values to use for
            calculating the model. If None, uses the energy from the
            experiment.

    Returns:
        list[np.ndarray] | np.ndarray: If Q_index is None, returns
            a list of numpy arrays, one for each Q index.
            If Q_index is an integer, returns a single numpy array
            for that Q index.
    """
    if energy is None:
        energy = self.energy

    if Q_index is None:
        return [analysis.calculate(energy=energy) for analysis in self.analysis_list]

    Q_index = self._verify_Q_index(Q_index)
    return self.analysis_list[Q_index].calculate(energy=energy)

fit(fit_method='independent', Q_index=None)

Fit the model to the experimental data.

Parameters:

Name	Type	Description	Default
fit_method	str, default="independent"	Method to use for fitting. Options are "independent" (fit each Q index independently, one after the other) or "simultaneous" (fit all Q indices simultaneously). Default is "independent".	'independent'
Q_index	int | None, default=None	If fit_method is "independent", specify which Q index to fit. If None, fit all Q indices independently. Ignored if fit_method is "simultaneous". Default is None.	None

Returns:

Type	Description
FitResults | list[FitResults]	FitResults | list[FitResults]: a list of FitResults if fitting independently, or a single FitResults object if fitting simultaneously.

Raises:

Type	Description
ValueError	If fit_method is not "independent" or "simultaneous" or if there are no Q values available for fitting.

Source code in src/easydynamics/analysis/analysis.py

def fit(
    self,
    fit_method: str = 'independent',
    Q_index: int | None = None,
) -> FitResults | list[FitResults]:
    """Fit the model to the experimental data.

    Args:
        fit_method (str, default="independent"): Method to use for fitting. Options are
            "independent" (fit each Q index independently, one after
            the other) or "simultaneous" (fit all Q indices
            simultaneously). Default is "independent".
        Q_index (int | None, default=None): If fit_method is "independent",
            specify which Q index to fit. If None, fit all Q indices
            independently. Ignored if fit_method is "simultaneous".
            Default is None.

    Returns:
        FitResults | list[FitResults]: a list of FitResults if fitting independently,
            or a single FitResults object if fitting simultaneously.

    Raises:
        ValueError: If fit_method is not "independent" or
            "simultaneous" or if there are no Q values available for fitting.
    """

    if self.Q is None:
        raise ValueError(
            'No Q values available for fitting. Please check the experiment data.'
        )

    Q_index = self._verify_Q_index(Q_index)

    if fit_method == 'independent':
        if Q_index is not None:
            return self._fit_single_Q(Q_index)
        else:
            return self._fit_all_Q_independently()
    elif fit_method == 'simultaneous':
        return self._fit_all_Q_simultaneously()
    else:
        raise ValueError("Invalid fit method. Choose 'independent' or 'simultaneous'.")

get_fit_functions()

Get fit functions for all Q indices, which can be used for simultaneous fitting.

Returns:

Type	Description
list[callable]	list[callable]: A list of fit functions, one for each Q index.

Source code in src/easydynamics/analysis/analysis.py

def get_fit_functions(self) -> list[callable]:
    """Get fit functions for all Q indices, which can be used for
    simultaneous fitting.

    Returns:
        list[callable]: A list of fit functions, one for each
            Q index.
    """
    return [analysis.as_fit_function() for analysis in self.analysis_list]

parameters_to_dataset()

Creates a scipp dataset with copies of the Parameters in the model.

Ensures unit consistency across Q.

Returns:

Type	Description
Dataset	sc.Dataset: A dataset where each entry is a parameter, with dimensions "Q" and values corresponding to the parameter values.

Raises:

Type	Description
UnitError	If there are inconsistent units for the same parameter across different Q values.

Source code in src/easydynamics/analysis/analysis.py

def parameters_to_dataset(self) -> sc.Dataset:
    """Creates a scipp dataset with copies of the Parameters in the
    model.

    Ensures unit consistency across Q.

    Returns:
        sc.Dataset: A dataset where each entry is a parameter, with
            dimensions "Q" and values corresponding to the parameter
            values.

    Raises:
        UnitError: If there are inconsistent units for the same
            parameter across different Q values.
    """

    ds = sc.Dataset(coords={'Q': self.Q})

    # Collect all parameter names
    all_names = {
        param.name
        for analysis in self.analysis_list
        for param in analysis.get_all_parameters()
    }

    # Storage
    values = {name: [] for name in all_names}
    variances = {name: [] for name in all_names}
    units = {}

    for analysis in self.analysis_list:
        pars = {p.name: p for p in analysis.get_all_parameters()}

        for name in all_names:
            if name in pars:
                p = pars[name]

                # Unit consistency check
                if name not in units:
                    units[name] = p.unit
                elif units[name] != p.unit:
                    try:
                        p.convert_unit(units[name])
                    except Exception as e:
                        raise UnitError(
                            f"Inconsistent units for parameter '{name}': "
                            f'{units[name]} vs {p.unit}'
                        ) from e

                values[name].append(p.value)
                variances[name].append(p.variance)
            else:
                values[name].append(np.nan)
                variances[name].append(np.nan)

    # Build dataset variables
    for name in all_names:
        ds[name] = sc.Variable(
            dims=['Q'],
            values=np.asarray(values[name], dtype=float),
            variances=np.asarray(variances[name], dtype=float),
            unit=units.get(name, None),
        )

    return ds

plot_data_and_model(Q_index=None, plot_components=True, add_background=True, energy=None, **kwargs)

Plot the experimental data and the model prediction. Optionally also plot the individual components of the model.

Uses Plopp for plotting: https://scipp.github.io/plopp/

Parameters:

Name	Type	Description	Default
Q_index	int | None, default=None	Index of the Q value to plot. If None, plot all Q values. Default is None.	None
plot_components	bool, default=True	Whether to plot the individual components. Default is True.	True
add_background	bool, default=True	Whether to add background components to the sample model components when plotting. Default is True.	True
energy	sc.Variable | None, default=None	The energy values to use for calculating the model. If None, uses the energy from the experiment.	None
**kwargs	dict[str, Any]	Additional keyword arguments passed to plopp for customizing the plot.	{}

Raises:

Type	Description
ValueError	If Q_index is out of bounds, or if there is no data to plot, or if there are no Q values available for plotting.
RuntimeError	If not in a Jupyter notebook environment.
TypeError	If plot_components or add_background is not True or False.

Returns:

Name	Type	Description
InteractiveFigure	InteractiveFigure	A Plopp InteractiveFigure containing the plot of the data and model.

Source code in src/easydynamics/analysis/analysis.py

def plot_data_and_model(
    self,
    Q_index: int | None = None,
    plot_components: bool = True,
    add_background: bool = True,
    energy: sc.Variable | None = None,
    **kwargs: dict[str, Any],
) -> InteractiveFigure:
    """Plot the experimental data and the model prediction.
    Optionally also plot the individual components of the model.

    Uses Plopp for plotting: https://scipp.github.io/plopp/

    Args:
        Q_index (int | None, default=None): Index of the Q value to plot. If
            None, plot all Q values. Default is None.
        plot_components (bool, default=True): Whether to plot the individual
            components. Default is True.
        add_background (bool, default=True): Whether to add background components
            to the sample model components when plotting. Default is
            True.
        energy (sc.Variable | None, default=None): The energy values to use for
            calculating the model. If None, uses the energy from the
            experiment.
        **kwargs (dict[str, Any]): Additional keyword arguments passed to plopp
            for customizing the plot.

    Raises:
        ValueError: If Q_index is out of bounds, or if there is no
            data to plot, or if there are no Q values available for
            plotting.
        RuntimeError: If not in a Jupyter notebook environment.
        TypeError: If plot_components or add_background is not True
            or False.

    Returns:
        InteractiveFigure: A Plopp InteractiveFigure containing the
            plot of the data and model.
    """

    if Q_index is not None:
        Q_index = self._verify_Q_index(Q_index)
        return self.analysis_list[Q_index].plot_data_and_model(
            plot_components=plot_components,
            add_background=add_background,
            energy=energy,
            **kwargs,
        )

    if self.experiment.binned_data is None:
        raise ValueError('No data to plot. Please load data first.')

    if not _in_notebook():
        raise RuntimeError('plot_data() can only be used in a Jupyter notebook environment.')

    if self.Q is None:
        raise ValueError(
            'No Q values available for plotting. Please check the experiment data.'
        )

    if not isinstance(plot_components, bool):
        raise TypeError('plot_components must be True or False.')

    if not isinstance(add_background, bool):
        raise TypeError('add_background must be True or False.')

    if energy is None:
        energy = self.energy

    import plopp as pp

    plot_kwargs_defaults = {
        'title': self.display_name,
        'linestyle': {'Data': 'none', 'Model': '-'},
        'marker': {'Data': 'o', 'Model': None},
        'color': {'Data': 'black', 'Model': 'red'},
        'markerfacecolor': {'Data': 'none', 'Model': 'none'},
        'keep': 'energy',
    }
    data_and_model = {
        'Data': self.experiment.binned_data,
        'Model': self._create_model_array(energy=energy),
    }

    if plot_components:
        components = self._create_components_dataset(
            add_background=add_background, energy=energy
        )
        for key in components.keys():
            data_and_model[key] = components[key]
            plot_kwargs_defaults['linestyle'][key] = '--'
            plot_kwargs_defaults['marker'][key] = None

    # Overwrite defaults with any user-provided kwargs
    plot_kwargs_defaults.update(kwargs)

    fig = pp.slicer(
        data_and_model,
        **plot_kwargs_defaults,
    )
    for widget in fig.bottom_bar[0].controls.values():
        widget.slider_toggler.value = '-o-'

    return fig

plot_parameters(names=None, **kwargs)

Plot fitted parameters as a function of Q.

Parameters:

Name	Type	Description	Default
names	str | list[str] | None, default=None	Name(s) of the parameter(s) to plot. If None, plots all parameters.	None
**kwargs	dict[str, Any]	Additional keyword arguments passed to plopp.slicer for customizing the plot (e.g., title, linestyle, marker, color).	{}

Returns:

Name	Type	Description
InteractiveFigure	InteractiveFigure	A Plopp InteractiveFigure containing the plot of the parameters.

Raises:

Type	Description
TypeError	If names is not a string, list of strings, or None.
ValueError	If any of the specified parameter names are not found in the dataset.

Source code in src/easydynamics/analysis/analysis.py

def plot_parameters(
    self,
    names: str | list[str] | None = None,
    **kwargs: dict[str, Any],
) -> InteractiveFigure:
    """Plot fitted parameters as a function of Q.

    Args:
        names (str | list[str] | None, default=None): Name(s) of the parameter(s)
            to plot. If None, plots all parameters.
        **kwargs (dict[str, Any]): Additional keyword arguments passed to
            plopp.slicer for customizing the plot (e.g., title,
            linestyle, marker, color).

    Returns:
        InteractiveFigure: A Plopp InteractiveFigure containing the
            plot of the parameters.

    Raises:
        TypeError: If names is not a string, list of strings, or None.
        ValueError: If any of the specified parameter names are not found in the dataset.
    """

    ds = self.parameters_to_dataset()

    if not names:
        names = list(ds.keys())

    if isinstance(names, str):
        names = [names]

    if not isinstance(names, list) or not all(isinstance(name, str) for name in names):
        raise TypeError('names must be a string or a list of strings.')

    for name in names:
        if name not in ds:
            raise ValueError(f"Parameter '{name}' not found in dataset.")

    data_to_plot = {name: ds[name] for name in names}
    plot_kwargs_defaults = {
        'linestyle': {name: 'none' for name in names},
        'marker': {name: 'o' for name in names},
        'markerfacecolor': {name: 'none' for name in names},
    }

    plot_kwargs_defaults.update(kwargs)

    import plopp as pp

    fig = pp.plot(
        data_to_plot,
        **plot_kwargs_defaults,
    )
    return fig

analysis1d

Analysis1d

Bases: AnalysisBase

For analysing one-dimensional data, i.e. intensity as function of energy for a single Q index.

Is used primarily in the Analysis class, but can also be used on its own for simpler analyses.

Source code in src/easydynamics/analysis/analysis1d.py

class Analysis1d(AnalysisBase):
    """For analysing one-dimensional data, i.e. intensity as function of
    energy for a single Q index.

    Is used primarily in the Analysis class, but can also be used on its
    own for simpler analyses.
    """

    def __init__(
        self,
        display_name: str | None = 'MyAnalysis',
        unique_name: str | None = None,
        experiment: Experiment | None = None,
        sample_model: SampleModel | None = None,
        instrument_model: InstrumentModel | None = None,
        Q_index: int | None = None,
        extra_parameters: Parameter | list[Parameter] | None = None,
    ) -> None:
        """Initialize a Analysis1d.

        Args:
            display_name (str | None, default='MyAnalysis'): Display name of the analysis.
            unique_name (str | None, default=None): Unique name of the analysis. If
                None, a unique name is automatically generated.
            experiment (Experiment | None, default=None): The Experiment associated
                with this Analysis. If None, a default Experiment is
                created.
            sample_model (SampleModel | None, default=None): The SampleModel
                associated with this Analysis. If None, a default
                SampleModel is created.
            instrument_model (InstrumentModel | None, default=None): The
                InstrumentModel associated with this Analysis. If None,
                a default InstrumentModel is created.
            Q_index (int | None, default=None): The Q index to analyze. If None, the
                analysis will not be able to calculate or fit until a
                Q index is set.
            extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
                parameters to be included in the analysis for advanced
                users. If None, no extra parameters are added.
        """
        super().__init__(
            display_name=display_name,
            unique_name=unique_name,
            experiment=experiment,
            sample_model=sample_model,
            instrument_model=instrument_model,
            extra_parameters=extra_parameters,
        )

        self._Q_index = self._verify_Q_index(Q_index)

        if self._Q_index is not None and self.experiment is not None:
            masked_energy = self.experiment.get_masked_energy(Q_index=self._Q_index)
            self._masked_energy = masked_energy
        else:
            self._masked_energy = None

        self._fit_result = None
        if self._Q_index is not None:
            self._convolver = self._create_convolver()
        else:
            self._convolver = None

    #############
    # Properties
    #############

    @property
    def Q_index(self) -> int | None:
        """Get the Q index associated with this Analysis.

        Returns:
            int | None: The Q index associated with this Analysis.
        """

        return self._Q_index

    @Q_index.setter
    def Q_index(self, value: int | None) -> None:
        """Set the Q index for single Q analysis.

        Args:
            value (int | None): The Q index.
        """

        self._Q_index = self._verify_Q_index(value)
        self._on_Q_index_changed()

    #############
    # Other methods
    #############

    def calculate(self, energy: sc.Variable | None = None) -> np.ndarray:
        """Calculate the model prediction for the chosen Q index. Makes
        sure the convolver is up to date before calculating.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                calculation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The calculated model prediction.
        """
        energy = self._verify_energy(energy)
        self._convolver = self._create_convolver(energy=energy)

        return self._calculate(energy=energy)

    def _calculate(self, energy: sc.Variable | None = None) -> np.ndarray:
        """Calculate the model prediction for the chosen Q index. Does
        not check if the convolver is up to date.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                calculation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The calculated model prediction.
        """

        sample_intensity = self._evaluate_sample(energy=energy)

        background_intensity = self._evaluate_background(energy=energy)

        sample_plus_background = sample_intensity + background_intensity

        return sample_plus_background

    def fit(self) -> FitResults:
        """Fit the model to the experimental data for the chosen Q
        index.

        The energy grid is fixed for the duration of the fit.
        Convolution objects are created once and reused during
        parameter optimization for performance reasons.

        Returns:
            FitResults: The result of the fit.

        Raises:
            ValueError: If no experiment is associated with this
                Analysis.
        """
        if self._experiment is None:
            raise ValueError('No experiment is associated with this Analysis.')

        # Create convolver once to reuse during fitting
        self._convolver = self._create_convolver()

        fitter = EasyScienceFitter(
            fit_object=self,
            fit_function=self.as_fit_function(),
        )

        x, y, weights, _ = self.experiment._extract_x_y_weights_only_finite(
            Q_index=self._require_Q_index()
        )
        fit_result = fitter.fit(x=x, y=y, weights=weights)

        self._fit_result = fit_result

        return fit_result

    def as_fit_function(
        self, x: np.ndarray | sc.Variable | None = None, **kwargs: dict[str, Any]
    ) -> callable:
        """Return self._calculate as a fit function.

        The EasyScience fitter requires x as input, but
        self._calculate() already uses the correct energy from the
        experiment. So we ignore the x input and just return the
        calculated model.

        Args:
            x (np.ndarray | sc.Variable | None, default=None): Ignored.
                The energy grid is taken from the experiment.
            **kwargs (dict[str, Any]): Ignored. Included for compatibility with the
                EasyScience fitter.

        Returns:
            callable: A function that can be used as a fit function in the
                EasyScience fitter, which returns the calculated model.
        """

        def fit_function(
            x: np.ndarray | sc.Variable | None = None,
            **kwargs: dict[str, Any],
        ) -> np.ndarray:
            return self._calculate()

        return fit_function

    def get_all_variables(self) -> list[DescriptorNumber]:
        """Get all variables used in the analysis.

        Returns:
            list[DescriptorNumber]: A list of all variables.
        """
        variables = self.sample_model.get_all_variables(Q_index=self.Q_index)

        variables.extend(self.instrument_model.get_all_variables(Q_index=self.Q_index))

        if self._extra_parameters:
            variables.extend(self._extra_parameters)

        return variables

    def plot_data_and_model(
        self,
        plot_components: bool = True,
        add_background: bool = True,
        energy: sc.Variable | None = None,
        **kwargs: dict[str, Any],
    ) -> InteractiveFigure:
        """Plot the experimental data and the model prediction for the
        chosen Q index. Optionally also plot the individual components
        of the model.

        Uses Plopp for plotting: https://scipp.github.io/plopp/

        Args:
            plot_components (bool, default=True): Whether to plot the individual
                components of the model.
            add_background (bool, default=True): Whether to add the background to the
                model prediction when plotting individual components.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                plotting. If None, the energy grid from the experiment
                is used.
            **kwargs (dict[str, Any]): Keyword arguments to pass to the plotting
                function.

        Returns:
            InteractiveFigure: A plot of the data and model.

        Raises:
            ValueError: If no data is available to plot.
        """
        import plopp as pp

        if self.experiment.data is None:
            raise ValueError('No data to plot. Please load data first.')

        energy = self._verify_energy(energy)
        if energy is None:
            energy = self._masked_energy

        data = self.experiment.data['Q', self.Q_index]
        model_array = self._create_sample_scipp_array(energy=energy)

        component_dataset = self._create_components_dataset_single_Q(
            add_background=add_background, energy=energy
        )

        # Create a dataset containing the data, model, and individual
        # components for plotting.
        data_and_model = sc.Dataset({
            'Data': data,
            'Model': model_array,
        })

        data_and_model = sc.merge(data_and_model, component_dataset)
        plot_kwargs_defaults = {
            'title': self.display_name,
            'linestyle': {'Data': 'none', 'Model': '-'},
            'marker': {'Data': 'o', 'Model': 'none'},
            'color': {'Data': 'black', 'Model': 'red'},
            'markerfacecolor': {'Data': 'none', 'Model': 'none'},
        }

        if plot_components:
            for comp_name in component_dataset.keys():
                plot_kwargs_defaults['linestyle'][comp_name] = '--'
                plot_kwargs_defaults['marker'][comp_name] = None

        # Overwrite defaults with any user-provided kwargs
        plot_kwargs_defaults.update(kwargs)

        fig = pp.plot(
            data_and_model,
            **plot_kwargs_defaults,
        )
        return fig

    #############
    # Private methods: small utilities
    #############

    def _require_Q_index(self) -> int:
        """Get the Q index, ensuring it is set. Raises a ValueError if
        the Q index is not set.

        Returns:
            int: The Q index.

        Raises:
            ValueError: If the Q index is not set.
        """
        if self._Q_index is None:
            raise ValueError('Q_index must be set.')
        return self._Q_index

    def _on_Q_index_changed(self) -> None:
        """Handle changes to the Q index.

        This method is called whenever the Q index is changed. It
        updates the Convolution object for the new Q index and the
        masked energy from the experiment for the new Q index.
        """
        masked_energy = self.experiment.get_masked_energy(Q_index=self._Q_index)
        self._masked_energy = masked_energy
        self._convolver = self._create_convolver()

    def _verify_energy(self, energy: sc.Variable | None) -> sc.Variable | None:
        """Verify that the provided energy is the correct type.

        Args:
            energy (sc.Variable | None): The energy to verify.

        Returns:
            sc.Variable | None: The verified energy, or None if no
                energy is provided.

        Raises:
            TypeError: If energy is not a sc.Variable or None.
        """

        if energy is not None and not isinstance(energy, sc.Variable):
            raise TypeError(f'Energy must be a sc.Variable or None. Got {type(energy)}.')
        return energy

    def _calculate_energy_with_offset(
        self,
        energy: sc.Variable,
        energy_offset: Parameter,
    ) -> sc.Variable:
        """Calculate the energy grid with the energy offset applied.

        Args:
            energy (sc.Variable): The energy grid to apply the offset to.
            energy_offset (Parameter): The energy offset to apply.

        Returns:
            sc.Variable: The energy grid with the offset applied.

        Raises:
            sc.UnitError: If the energy and energy offset have
                incompatible units.
        """

        if energy.unit != energy_offset.unit:
            try:
                energy_offset.convert_unit(str(energy.unit))
            except Exception as e:
                raise sc.UnitError(
                    f'Energy and energy offset must have compatible units. '
                    f'Got {energy.unit} and {energy_offset.unit}.'
                ) from e

        energy_with_offset = energy.copy(deep=True)
        energy_with_offset.values -= energy_offset.value
        return energy_with_offset

    #############
    # Private methods: evaluation
    #############

    def _evaluate_components(
        self,
        components: ComponentCollection | ModelComponent,
        convolver: Convolution | None = None,
        convolve: bool = True,
        energy: sc.Variable | None = None,
    ) -> np.ndarray:
        """Calculate the contribution of a set of components, optionally
        convolving with the resolution.

        If convolve is True and a
        Convolution object is provided (for full model evaluation), we
        use it to perform the convolution of the components with the
        resolution.
        If convolve is True but no Convolution object is
        provided, create a new Convolution object for the given
        components (for individual components).
        If convolve is False, evaluate the components directly without
        convolution (for background).

        Args:
            components (ComponentCollection | ModelComponent): The
                components to evaluate.
            convolver (Convolution | None, default=None): An optional Convolution
                object to use for convolution. If None, a new
                Convolution object will be created if convolve is True.
            convolve (bool, default=True): Whether to perform convolution with the
                resolution. Default is True.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The evaluated contribution of the components.
        """

        Q_index = self._require_Q_index()
        if energy is None:
            energy = self._masked_energy

        energy_offset = self.instrument_model.get_energy_offset_at_Q(Q_index)
        energy_with_offset = self._calculate_energy_with_offset(
            energy=energy,
            energy_offset=energy_offset,
        )

        # If there are no components, return zero
        if isinstance(components, ComponentCollection) and components.is_empty:
            return np.zeros_like(energy.values)

        # No convolution
        if not convolve:
            return components.evaluate(energy_with_offset)

        # If a convolver is provided, use it. This allows reusing the
        # same convolver for multiple evaluations during fitting for
        # performance reasons.
        if convolver is not None:
            return convolver.convolution()

        # If no convolver is provided, create a new one. This is for
        # evaluating individual components for plotting, where
        # performance is not important.

        # We don't create a convolver if the resolution is empty.
        resolution = self.instrument_model.resolution_model.get_component_collection(Q_index)
        if resolution.is_empty:
            return components.evaluate(energy_with_offset)

        conv = Convolution(
            sample_components=components,
            resolution_components=resolution,
            energy=energy,
            temperature=self.temperature,
            energy_offset=energy_offset,
        )
        return conv.convolution()

    def _evaluate_sample(
        self,
        energy: sc.Variable | None = None,
    ) -> np.ndarray:
        """Evaluate the sample contribution for a given Q index.

        Assumes that self._convolver is up to date.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The evaluated sample contribution.
        """
        Q_index = self._require_Q_index()
        components = self.sample_model.get_component_collection(Q_index=Q_index)
        return self._evaluate_components(
            components=components,
            convolver=self._convolver,
            convolve=True,
            energy=energy,
        )

    def _evaluate_sample_component(
        self,
        component: ModelComponent,
        energy: sc.Variable | None = None,
    ) -> np.ndarray:
        """Evaluate a single sample component for the chosen Q index.

        Args:
            component (ModelComponent): The sample component to
                evaluate.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The evaluated sample component contribution.
        """
        return self._evaluate_components(
            components=component,
            convolver=None,
            convolve=True,
            energy=energy,
        )

    def _evaluate_background(self, energy: sc.Variable | None = None) -> np.ndarray:
        """Evaluate the background contribution for the chosen Q index.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The evaluated background contribution.
        """
        Q_index = self._require_Q_index()
        background_components = self.instrument_model.background_model.get_component_collection(
            Q_index=Q_index
        )
        return self._evaluate_components(
            components=background_components,
            convolver=None,
            convolve=False,
            energy=energy,
        )

    def _evaluate_background_component(
        self,
        component: ModelComponent,
        energy: sc.Variable | None = None,
    ) -> np.ndarray:
        """Evaluate a single background component for the chosen Q
        index.

        Args:
            component (ModelComponent): The background component to
                evaluate.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            np.ndarray: The evaluated background component contribution.
        """

        return self._evaluate_components(
            components=component,
            convolver=None,
            convolve=False,
            energy=energy,
        )

    def _create_convolver(
        self,
        energy: sc.Variable | None = None,
    ) -> Convolution | None:
        """Initialize and return a Convolution object for the chosen Q
        index. If the necessary components for convolution are not
        available, return None.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                convolution. If None, the energy grid from the experiment
                is used.

        Returns:
            Convolution | None: The initialized Convolution object or
                None if not available.
        """
        Q_index = self._require_Q_index()

        if energy is None:
            energy = self._masked_energy

        sample_components = self.sample_model.get_component_collection(Q_index)
        if sample_components.is_empty:
            return None

        resolution_components = self.instrument_model.resolution_model.get_component_collection(
            Q_index
        )
        if resolution_components.is_empty:
            return None

        # TODO: allow convolution options to be set.
        convolver = Convolution(
            sample_components=sample_components,
            resolution_components=resolution_components,
            energy=energy,
            temperature=self.temperature,
            energy_offset=self.instrument_model.get_energy_offset_at_Q(Q_index),
        )
        return convolver

    #############
    # Private methods: create scipp arrays for plotting
    #############

    def _create_component_scipp_array(
        self,
        component: ModelComponent,
        background: np.ndarray | None = None,
        energy: sc.Variable | None = None,
    ) -> sc.DataArray:
        """Create a scipp DataArray for a single component. Adds the
        background if it is not None.

        Args:
            component (ModelComponent): The component to evaluate.
            background (np.ndarray | None, default=None): Optional background to add
                to the component.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            sc.DataArray: The model calculation of the component.
        """

        values = self._evaluate_sample_component(component=component, energy=energy)
        if background is not None:
            values += background
        return self._to_scipp_array(values=values, energy=energy)

    def _create_background_component_scipp_array(
        self,
        component: ModelComponent,
        energy: sc.Variable | None = None,
    ) -> sc.DataArray:
        """Create a scipp DataArray for a single background component.

        Args:
            component (ModelComponent): The component to evaluate.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            sc.DataArray: The model calculation of the component.
        """

        values = self._evaluate_background_component(
            component=component,
            energy=energy,
        )
        return self._to_scipp_array(values=values, energy=energy)

    def _create_sample_scipp_array(self, energy: sc.Variable | None = None) -> sc.DataArray:
        """Create a scipp DataArray for the full sample model including
        background.

        Args:
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            sc.DataArray: The model calculation of the full sample
                model.
        """
        values = self.calculate(energy=energy)
        return self._to_scipp_array(values=values, energy=energy)

    def _create_components_dataset_single_Q(
        self,
        add_background: bool = True,
        energy: sc.Variable | None = None,
    ) -> dict[str, sc.DataArray]:
        """Create sc.DataArrays for all sample and background
        components.

        Args:
            add_background (bool, default=True): Whether to add background components.
            energy (sc.Variable | None, default=None): Optional energy grid to use for
                evaluation. If None, the energy grid from the experiment
                is used.

        Returns:
            dict[str, sc.DataArray]: A dictionary of component names to
                their corresponding sc.DataArrays.
        """
        scipp_arrays = {}
        sample_components = self.sample_model.get_component_collection(
            Q_index=self.Q_index
        ).components

        background_components = self.instrument_model.background_model.get_component_collection(
            Q_index=self.Q_index
        ).components

        if energy is None:
            energy = self._masked_energy

        background = self._evaluate_background(energy=energy) if add_background else None

        for component in sample_components:
            scipp_arrays[component.display_name] = self._create_component_scipp_array(
                component=component, background=background, energy=energy
            )
        for component in background_components:
            scipp_arrays[component.display_name] = self._create_background_component_scipp_array(
                component=component, energy=energy
            )
        return sc.Dataset(scipp_arrays)

    def _to_scipp_array(
        self,
        values: np.ndarray,
        energy: sc.Variable | None = None,
    ) -> sc.DataArray:
        """Convert a numpy array of values to a sc.DataArray with the
        correct coordinates for energy and Q.

        Args:
            values (np.ndarray): The values to convert.
            energy (sc.Variable | None, default=None): Optional energy grid to use for the
                energy coordinate. If None, the energy grid from the
                experiment is used.

        Returns:
            sc.DataArray: The converted sc.DataArray.
        """

        if energy is None:
            energy = self._masked_energy
        return sc.DataArray(
            data=sc.array(dims=['energy'], values=values),
            coords={
                'energy': energy,
                'Q': self.Q[self.Q_index],
            },
        )

Q_index property writable

Get the Q index associated with this Analysis.

Returns:

Type	Description
int | None	int | None: The Q index associated with this Analysis.

__init__(display_name='MyAnalysis', unique_name=None, experiment=None, sample_model=None, instrument_model=None, Q_index=None, extra_parameters=None)

Initialize a Analysis1d.

Parameters:

Name	Type	Description	Default
display_name	str | None, default='MyAnalysis'	Display name of the analysis.	'MyAnalysis'
unique_name	str | None, default=None	Unique name of the analysis. If None, a unique name is automatically generated.	None
experiment	Experiment | None, default=None	The Experiment associated with this Analysis. If None, a default Experiment is created.	None
sample_model	SampleModel | None, default=None	The SampleModel associated with this Analysis. If None, a default SampleModel is created.	None
instrument_model	InstrumentModel | None, default=None	The InstrumentModel associated with this Analysis. If None, a default InstrumentModel is created.	None
Q_index	int | None, default=None	The Q index to analyze. If None, the analysis will not be able to calculate or fit until a Q index is set.	None
extra_parameters	Parameter | list[Parameter] | None, default=None	Extra parameters to be included in the analysis for advanced users. If None, no extra parameters are added.	None

Source code in src/easydynamics/analysis/analysis1d.py

def __init__(
    self,
    display_name: str | None = 'MyAnalysis',
    unique_name: str | None = None,
    experiment: Experiment | None = None,
    sample_model: SampleModel | None = None,
    instrument_model: InstrumentModel | None = None,
    Q_index: int | None = None,
    extra_parameters: Parameter | list[Parameter] | None = None,
) -> None:
    """Initialize a Analysis1d.

    Args:
        display_name (str | None, default='MyAnalysis'): Display name of the analysis.
        unique_name (str | None, default=None): Unique name of the analysis. If
            None, a unique name is automatically generated.
        experiment (Experiment | None, default=None): The Experiment associated
            with this Analysis. If None, a default Experiment is
            created.
        sample_model (SampleModel | None, default=None): The SampleModel
            associated with this Analysis. If None, a default
            SampleModel is created.
        instrument_model (InstrumentModel | None, default=None): The
            InstrumentModel associated with this Analysis. If None,
            a default InstrumentModel is created.
        Q_index (int | None, default=None): The Q index to analyze. If None, the
            analysis will not be able to calculate or fit until a
            Q index is set.
        extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
            parameters to be included in the analysis for advanced
            users. If None, no extra parameters are added.
    """
    super().__init__(
        display_name=display_name,
        unique_name=unique_name,
        experiment=experiment,
        sample_model=sample_model,
        instrument_model=instrument_model,
        extra_parameters=extra_parameters,
    )

    self._Q_index = self._verify_Q_index(Q_index)

    if self._Q_index is not None and self.experiment is not None:
        masked_energy = self.experiment.get_masked_energy(Q_index=self._Q_index)
        self._masked_energy = masked_energy
    else:
        self._masked_energy = None

    self._fit_result = None
    if self._Q_index is not None:
        self._convolver = self._create_convolver()
    else:
        self._convolver = None

as_fit_function(x=None, **kwargs)

Return self._calculate as a fit function.

The EasyScience fitter requires x as input, but self._calculate() already uses the correct energy from the experiment. So we ignore the x input and just return the calculated model.

Parameters:

Name	Type	Description	Default
x	np.ndarray | sc.Variable | None, default=None	Ignored. The energy grid is taken from the experiment.	None
**kwargs	dict[str, Any]	Ignored. Included for compatibility with the EasyScience fitter.	{}

Returns:

Name	Type	Description
callable	callable	A function that can be used as a fit function in the EasyScience fitter, which returns the calculated model.

Source code in src/easydynamics/analysis/analysis1d.py

def as_fit_function(
    self, x: np.ndarray | sc.Variable | None = None, **kwargs: dict[str, Any]
) -> callable:
    """Return self._calculate as a fit function.

    The EasyScience fitter requires x as input, but
    self._calculate() already uses the correct energy from the
    experiment. So we ignore the x input and just return the
    calculated model.

    Args:
        x (np.ndarray | sc.Variable | None, default=None): Ignored.
            The energy grid is taken from the experiment.
        **kwargs (dict[str, Any]): Ignored. Included for compatibility with the
            EasyScience fitter.

    Returns:
        callable: A function that can be used as a fit function in the
            EasyScience fitter, which returns the calculated model.
    """

    def fit_function(
        x: np.ndarray | sc.Variable | None = None,
        **kwargs: dict[str, Any],
    ) -> np.ndarray:
        return self._calculate()

    return fit_function

calculate(energy=None)

Calculate the model prediction for the chosen Q index. Makes sure the convolver is up to date before calculating.

Parameters:

Name	Type	Description	Default
energy	sc.Variable | None, default=None	Optional energy grid to use for calculation. If None, the energy grid from the experiment is used.	None

Returns:

Type	Description
ndarray	np.ndarray: The calculated model prediction.

Source code in src/easydynamics/analysis/analysis1d.py

def calculate(self, energy: sc.Variable | None = None) -> np.ndarray:
    """Calculate the model prediction for the chosen Q index. Makes
    sure the convolver is up to date before calculating.

    Args:
        energy (sc.Variable | None, default=None): Optional energy grid to use for
            calculation. If None, the energy grid from the experiment
            is used.

    Returns:
        np.ndarray: The calculated model prediction.
    """
    energy = self._verify_energy(energy)
    self._convolver = self._create_convolver(energy=energy)

    return self._calculate(energy=energy)

fit()

Fit the model to the experimental data for the chosen Q index.

The energy grid is fixed for the duration of the fit. Convolution objects are created once and reused during parameter optimization for performance reasons.

Returns:

Name	Type	Description
FitResults	FitResults	The result of the fit.

Raises:

Type	Description
ValueError	If no experiment is associated with this Analysis.

Source code in src/easydynamics/analysis/analysis1d.py

def fit(self) -> FitResults:
    """Fit the model to the experimental data for the chosen Q
    index.

    The energy grid is fixed for the duration of the fit.
    Convolution objects are created once and reused during
    parameter optimization for performance reasons.

    Returns:
        FitResults: The result of the fit.

    Raises:
        ValueError: If no experiment is associated with this
            Analysis.
    """
    if self._experiment is None:
        raise ValueError('No experiment is associated with this Analysis.')

    # Create convolver once to reuse during fitting
    self._convolver = self._create_convolver()

    fitter = EasyScienceFitter(
        fit_object=self,
        fit_function=self.as_fit_function(),
    )

    x, y, weights, _ = self.experiment._extract_x_y_weights_only_finite(
        Q_index=self._require_Q_index()
    )
    fit_result = fitter.fit(x=x, y=y, weights=weights)

    self._fit_result = fit_result

    return fit_result

get_all_variables()

Get all variables used in the analysis.

Returns:

Type	Description
list[DescriptorNumber]	list[DescriptorNumber]: A list of all variables.

Source code in src/easydynamics/analysis/analysis1d.py

def get_all_variables(self) -> list[DescriptorNumber]:
    """Get all variables used in the analysis.

    Returns:
        list[DescriptorNumber]: A list of all variables.
    """
    variables = self.sample_model.get_all_variables(Q_index=self.Q_index)

    variables.extend(self.instrument_model.get_all_variables(Q_index=self.Q_index))

    if self._extra_parameters:
        variables.extend(self._extra_parameters)

    return variables

plot_data_and_model(plot_components=True, add_background=True, energy=None, **kwargs)

Plot the experimental data and the model prediction for the chosen Q index. Optionally also plot the individual components of the model.

Uses Plopp for plotting: https://scipp.github.io/plopp/

Parameters:

Name	Type	Description	Default
plot_components	bool, default=True	Whether to plot the individual components of the model.	True
add_background	bool, default=True	Whether to add the background to the model prediction when plotting individual components.	True
energy	sc.Variable | None, default=None	Optional energy grid to use for plotting. If None, the energy grid from the experiment is used.	None
**kwargs	dict[str, Any]	Keyword arguments to pass to the plotting function.	{}

Returns:

Name	Type	Description
InteractiveFigure	InteractiveFigure	A plot of the data and model.

Raises:

Type	Description
ValueError	If no data is available to plot.

Source code in src/easydynamics/analysis/analysis1d.py

def plot_data_and_model(
    self,
    plot_components: bool = True,
    add_background: bool = True,
    energy: sc.Variable | None = None,
    **kwargs: dict[str, Any],
) -> InteractiveFigure:
    """Plot the experimental data and the model prediction for the
    chosen Q index. Optionally also plot the individual components
    of the model.

    Uses Plopp for plotting: https://scipp.github.io/plopp/

    Args:
        plot_components (bool, default=True): Whether to plot the individual
            components of the model.
        add_background (bool, default=True): Whether to add the background to the
            model prediction when plotting individual components.
        energy (sc.Variable | None, default=None): Optional energy grid to use for
            plotting. If None, the energy grid from the experiment
            is used.
        **kwargs (dict[str, Any]): Keyword arguments to pass to the plotting
            function.

    Returns:
        InteractiveFigure: A plot of the data and model.

    Raises:
        ValueError: If no data is available to plot.
    """
    import plopp as pp

    if self.experiment.data is None:
        raise ValueError('No data to plot. Please load data first.')

    energy = self._verify_energy(energy)
    if energy is None:
        energy = self._masked_energy

    data = self.experiment.data['Q', self.Q_index]
    model_array = self._create_sample_scipp_array(energy=energy)

    component_dataset = self._create_components_dataset_single_Q(
        add_background=add_background, energy=energy
    )

    # Create a dataset containing the data, model, and individual
    # components for plotting.
    data_and_model = sc.Dataset({
        'Data': data,
        'Model': model_array,
    })

    data_and_model = sc.merge(data_and_model, component_dataset)
    plot_kwargs_defaults = {
        'title': self.display_name,
        'linestyle': {'Data': 'none', 'Model': '-'},
        'marker': {'Data': 'o', 'Model': 'none'},
        'color': {'Data': 'black', 'Model': 'red'},
        'markerfacecolor': {'Data': 'none', 'Model': 'none'},
    }

    if plot_components:
        for comp_name in component_dataset.keys():
            plot_kwargs_defaults['linestyle'][comp_name] = '--'
            plot_kwargs_defaults['marker'][comp_name] = None

    # Overwrite defaults with any user-provided kwargs
    plot_kwargs_defaults.update(kwargs)

    fig = pp.plot(
        data_and_model,
        **plot_kwargs_defaults,
    )
    return fig

analysis_base

AnalysisBase

Bases: ModelBase

Base class for analysis in EasyDynamics. This class is not meant to be used directly.

An Analysis consists of an Experiment, a SampleModel, and an InstrumentModel. The Experiment contains the data to be fitted, the SampleModel contains the model for the sample, and the InstrumentModel contains the model for the instrument, including background and resolution

Source code in src/easydynamics/analysis/analysis_base.py

class AnalysisBase(EasyScienceModelBase):
    """Base class for analysis in EasyDynamics. This class is not meant
    to be used directly.

    An Analysis consists of an Experiment, a SampleModel, and an
    InstrumentModel. The Experiment contains the data to be fitted, the
    SampleModel contains the model for the sample, and the
    InstrumentModel contains the model for the instrument, including
    background and resolution
    """

    def __init__(
        self,
        display_name: str | None = 'MyAnalysis',
        unique_name: str | None = None,
        experiment: Experiment | None = None,
        sample_model: SampleModel | None = None,
        instrument_model: InstrumentModel | None = None,
        extra_parameters: Parameter | list[Parameter] | None = None,
    ) -> None:
        """Initialize the AnalysisBase.

        Args:
            display_name (str | None, default='MyAnalysis'): Display name of the analysis.
            unique_name (str | None, default=None): Unique name of the analysis. If
                None, a unique name is automatically generated.
            experiment (Experiment | None, default=None): The Experiment associated
                with this Analysis. If None, a default Experiment is
                created.
            sample_model (SampleModel | None, default=None): The SampleModel
                associated with this Analysis. If None, a default
                SampleModel is created.
            instrument_model (InstrumentModel | None, default=None): The
                InstrumentModel associated with this Analysis. If None,
                a default InstrumentModel is created.
            extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
                parameters to be included in the analysis for advanced
                users. If None, no extra parameters are added.

        Raises:
            TypeError: If experiment is not an Experiment or None or
                if sample_model is not a SampleModel or None or if
                instrument_model is not an InstrumentModel or None or if
                extra_parameters is not a Parameter, a list of Parameters,
                or None.
        """

        super().__init__(display_name=display_name, unique_name=unique_name)

        if experiment is None:
            self._experiment = Experiment()
        elif isinstance(experiment, Experiment):
            self._experiment = experiment
        else:
            raise TypeError('experiment must be an instance of Experiment or None.')

        if sample_model is None:
            self._sample_model = SampleModel()
        elif isinstance(sample_model, SampleModel):
            self._sample_model = sample_model
        else:
            raise TypeError('sample_model must be an instance of SampleModel or None.')

        if instrument_model is None:
            self._instrument_model = InstrumentModel()
        elif isinstance(instrument_model, InstrumentModel):
            self._instrument_model = instrument_model
        else:
            raise TypeError('instrument_model must be an instance of InstrumentModel or None.')

        if extra_parameters is not None:
            if isinstance(extra_parameters, Parameter):
                self._extra_parameters = [extra_parameters]
            elif isinstance(extra_parameters, list) and all(
                isinstance(p, Parameter) for p in extra_parameters
            ):
                self._extra_parameters = extra_parameters
            else:
                raise TypeError('extra_parameters must be a Parameter or a list of Parameters.')
        else:
            self._extra_parameters = []

        self._on_experiment_changed()

    #############
    # Properties
    #############

    @property
    def experiment(self) -> Experiment:
        """Get the Experiment associated with this Analysis.

        Returns:
            Experiment: The Experiment associated with this Analysis.
        """

        return self._experiment

    @experiment.setter
    def experiment(self, value: Experiment) -> None:
        """Set the Experiment for this Analysis.

        Args:
            value (Experiment): The Experiment to set for this Analysis.

        Raises:
            TypeError: if value is not an Experiment.
        """

        if not isinstance(value, Experiment):
            raise TypeError('experiment must be an instance of Experiment')
        self._experiment = value
        self._on_experiment_changed()

    @property
    def sample_model(self) -> SampleModel:
        """Get the SampleModel associated with this Analysis.

        Returns:
            SampleModel: The SampleModel associated with this Analysis.
        """

        return self._sample_model

    @sample_model.setter
    def sample_model(self, value: SampleModel) -> None:
        """Set the SampleModel for this Analysis.

        Args:
            value (SampleModel): The SampleModel to set for this Analysis.

        Raises:
            TypeError: if value is not a SampleModel.
        """
        if not isinstance(value, SampleModel):
            raise TypeError('sample_model must be an instance of SampleModel')
        self._sample_model = value
        self._on_sample_model_changed()

    @property
    def instrument_model(self) -> InstrumentModel:
        """Get the InstrumentModel associated with this Analysis.

        Returns:
            InstrumentModel: The InstrumentModel associated with this
                Analysis.
        """
        return self._instrument_model

    @instrument_model.setter
    def instrument_model(self, value: InstrumentModel) -> None:
        """Set the InstrumentModel for this Analysis.

        Args:
            value (InstrumentModel): The InstrumentModel to set for this
                Analysis.

        Raises:
            TypeError: if value is not an InstrumentModel.
        """
        if not isinstance(value, InstrumentModel):
            raise TypeError('instrument_model must be an instance of InstrumentModel')
        self._instrument_model = value
        self._on_instrument_model_changed()

    @property
    def Q(self) -> sc.Variable | None:
        """Get the Q values from the associated Experiment, if
        available.

        Returns:
            sc.Variable | None: The Q values from the associated Experiment,
                if available, and None if not.
        """
        return self.experiment.Q

    @Q.setter
    def Q(self, value: sc.Variable) -> None:
        """Q cannot be set, as it is a read-only property derived from
        the Experiment.

        Args:
            value (sc.Variable): The Q values to set. This argument is
                ignored, as Q is a read-only property.

        Raises:
            AttributeError: If trying to set Q.
        """
        raise AttributeError('Q is a read-only property derived from the Experiment.')

    @property
    def energy(self) -> sc.Variable | None:
        """Get the energy values from the associated Experiment, if
        available.

        Returns:
            sc.Variable | None: The energy values from the associated
            Experiment, if available, and None if not.
        """

        return self.experiment.energy

    @energy.setter
    def energy(self, value: sc.Variable) -> None:
        """Energy cannot be set, as it is a read-only property derived
        from the Experiment.

        Args:
            value (sc.Variable): The energy values to set. This argument is
                ignored, as energy is a read-only property.

        Raises:
            AttributeError: If trying to set energy.
        """

        raise AttributeError('energy is a read-only property derived from the Experiment.')

    @property
    def temperature(self) -> Parameter | None:
        """Get the temperature from the associated SampleModel, if
        available.

        Returns:
            Parameter | None: The temperature from the associated SampleModel,
            if available, and None if not.
        """

        return self.sample_model.temperature

    @temperature.setter
    def temperature(self, value: np.ndarray | Parameter) -> None:
        """Temperature cannot be set, as it is a read-only property
        derived from the SampleModel.

        Args:
            value (np.ndarray | Parameter): The temperature to set. This argument is
                ignored, as temperature is a read-only property.

        Raises:
            AttributeError: If trying to set temperature.
        """

        raise AttributeError('temperature is a read-only property derived from the SampleModel.')

    @property
    def extra_parameters(self) -> list[Parameter]:
        """Get the extra parameters included in this Analysis.

        Returns:
            list[Parameter]: The extra parameters included in this
                Analysis.
        """
        return self._extra_parameters

    @extra_parameters.setter
    def extra_parameters(self, value: Parameter | list[Parameter]) -> None:
        """Set the extra parameters for this Analysis.

        Args:
            value (Parameter | list[Parameter]): The extra parameters to
                include in this Analysis.

        Raises:
            TypeError: If value is not a Parameter, a list of
                Parameters, or None.
        """
        if isinstance(value, Parameter):
            self._extra_parameters = [value]
        elif isinstance(value, list) and all(isinstance(p, Parameter) for p in value):
            self._extra_parameters = value
        elif value is None:
            self._extra_parameters = []
        else:
            raise TypeError('extra_parameters must be a Parameter, a list of Parameters, or None.')

    #############
    # Other methods
    #############

    #############
    # Private methods
    #############

    def _on_experiment_changed(self) -> None:
        """Update the Q values in the sample and instrument models when
        the experiment changes.
        """
        self.sample_model.Q = self.Q
        self.instrument_model.Q = self.Q

    def _on_sample_model_changed(self) -> None:
        """Update the Q values in the sample model when the sample model
        changes.
        """
        self.sample_model.Q = self.Q

    def _on_instrument_model_changed(self) -> None:
        """Update the Q values in the instrument model when the
        instrument model changes.
        """
        self.instrument_model.Q = self.Q

    def _verify_Q_index(self, Q_index: int | None) -> int | None:
        """Verify that the Q index is valid.

        Args:
            Q_index (int | None): The Q index to verify.

        Returns:
            int | None: The verified Q index.

        Raises:
            IndexError: If the Q index is not valid.
        """
        if Q_index is not None:
            if (
                not isinstance(Q_index, int)
                or Q_index < 0
                or (self.Q is not None and Q_index >= len(self.Q))
            ):
                raise IndexError('Q_index must be a valid index for the Q values.')
        return Q_index

    #############
    # Dunder methods
    #############

    def __repr__(self) -> str:
        """Return a string representation of the Analysis.

        Returns:
            str: A string representation of the Analysis.
        """
        return f' {self.__class__.__name__}  (display_name={self.display_name}, \
        unique_name={self.unique_name})'

Q property writable

Get the Q values from the associated Experiment, if available.

Returns:

Type	Description
Variable | None	sc.Variable | None: The Q values from the associated Experiment, if available, and None if not.

__init__(display_name='MyAnalysis', unique_name=None, experiment=None, sample_model=None, instrument_model=None, extra_parameters=None)

Initialize the AnalysisBase.

Parameters:

Name	Type	Description	Default
display_name	str | None, default='MyAnalysis'	Display name of the analysis.	'MyAnalysis'
unique_name	str | None, default=None	Unique name of the analysis. If None, a unique name is automatically generated.	None
experiment	Experiment | None, default=None	The Experiment associated with this Analysis. If None, a default Experiment is created.	None
sample_model	SampleModel | None, default=None	The SampleModel associated with this Analysis. If None, a default SampleModel is created.	None
instrument_model	InstrumentModel | None, default=None	The InstrumentModel associated with this Analysis. If None, a default InstrumentModel is created.	None
extra_parameters	Parameter | list[Parameter] | None, default=None	Extra parameters to be included in the analysis for advanced users. If None, no extra parameters are added.	None

Raises:

Type	Description
TypeError	If experiment is not an Experiment or None or if sample_model is not a SampleModel or None or if instrument_model is not an InstrumentModel or None or if extra_parameters is not a Parameter, a list of Parameters, or None.

Source code in src/easydynamics/analysis/analysis_base.py

def __init__(
    self,
    display_name: str | None = 'MyAnalysis',
    unique_name: str | None = None,
    experiment: Experiment | None = None,
    sample_model: SampleModel | None = None,
    instrument_model: InstrumentModel | None = None,
    extra_parameters: Parameter | list[Parameter] | None = None,
) -> None:
    """Initialize the AnalysisBase.

    Args:
        display_name (str | None, default='MyAnalysis'): Display name of the analysis.
        unique_name (str | None, default=None): Unique name of the analysis. If
            None, a unique name is automatically generated.
        experiment (Experiment | None, default=None): The Experiment associated
            with this Analysis. If None, a default Experiment is
            created.
        sample_model (SampleModel | None, default=None): The SampleModel
            associated with this Analysis. If None, a default
            SampleModel is created.
        instrument_model (InstrumentModel | None, default=None): The
            InstrumentModel associated with this Analysis. If None,
            a default InstrumentModel is created.
        extra_parameters (Parameter | list[Parameter] | None, default=None): Extra
            parameters to be included in the analysis for advanced
            users. If None, no extra parameters are added.

    Raises:
        TypeError: If experiment is not an Experiment or None or
            if sample_model is not a SampleModel or None or if
            instrument_model is not an InstrumentModel or None or if
            extra_parameters is not a Parameter, a list of Parameters,
            or None.
    """

    super().__init__(display_name=display_name, unique_name=unique_name)

    if experiment is None:
        self._experiment = Experiment()
    elif isinstance(experiment, Experiment):
        self._experiment = experiment
    else:
        raise TypeError('experiment must be an instance of Experiment or None.')

    if sample_model is None:
        self._sample_model = SampleModel()
    elif isinstance(sample_model, SampleModel):
        self._sample_model = sample_model
    else:
        raise TypeError('sample_model must be an instance of SampleModel or None.')

    if instrument_model is None:
        self._instrument_model = InstrumentModel()
    elif isinstance(instrument_model, InstrumentModel):
        self._instrument_model = instrument_model
    else:
        raise TypeError('instrument_model must be an instance of InstrumentModel or None.')

    if extra_parameters is not None:
        if isinstance(extra_parameters, Parameter):
            self._extra_parameters = [extra_parameters]
        elif isinstance(extra_parameters, list) and all(
            isinstance(p, Parameter) for p in extra_parameters
        ):
            self._extra_parameters = extra_parameters
        else:
            raise TypeError('extra_parameters must be a Parameter or a list of Parameters.')
    else:
        self._extra_parameters = []

    self._on_experiment_changed()

__repr__()

Return a string representation of the Analysis.

Returns:

Name	Type	Description
str	str	A string representation of the Analysis.

Source code in src/easydynamics/analysis/analysis_base.py

def __repr__(self) -> str:
    """Return a string representation of the Analysis.

    Returns:
        str: A string representation of the Analysis.
    """
    return f' {self.__class__.__name__}  (display_name={self.display_name}, \
    unique_name={self.unique_name})'

energy property writable

Get the energy values from the associated Experiment, if available.

Returns:

Type	Description
Variable | None	sc.Variable | None: The energy values from the associated
Variable | None	Experiment, if available, and None if not.

experiment property writable

Get the Experiment associated with this Analysis.

Returns:

Name	Type	Description
Experiment	Experiment	The Experiment associated with this Analysis.

extra_parameters property writable

Get the extra parameters included in this Analysis.

Returns:

Type	Description
list[Parameter]	list[Parameter]: The extra parameters included in this Analysis.

instrument_model property writable

Get the InstrumentModel associated with this Analysis.

Returns:

Name	Type	Description
InstrumentModel	InstrumentModel	The InstrumentModel associated with this Analysis.

sample_model property writable

Get the SampleModel associated with this Analysis.

Returns:

Name	Type	Description
SampleModel	SampleModel	The SampleModel associated with this Analysis.

temperature property writable

Get the temperature from the associated SampleModel, if available.

Returns:

Type	Description
Parameter | None	Parameter | None: The temperature from the associated SampleModel,
Parameter | None	if available, and None if not.