qblox_scheduler.analysis.base_analysis#

Module containing the analysis abstract base class and several basic analyses.

Attributes#

`FIGURES_LRU_CACHE_SIZE`
`settings`	For convenience the analysis framework provides a set of global settings.

Classes#

`_FiguresMplCache`
`AnalysisSteps`	An enumerate of the steps executed by the `BaseAnalysis` (and the default
`AnalysisMeta`	Metaclass, whose purpose is to avoid storing large amount of figure in memory.
`BaseAnalysis`	A template for analysis classes.
`BasicAnalysis`	A basic analysis that extracts the data from the latest file matching the label
`Basic1DAnalysis`	Deprecated. Alias of `BasicAnalysis`
`Basic2DAnalysis`	A basic analysis that extracts the data from the latest file matching the label

Functions#

`flatten_lmfit_modelresult`(model)	Flatten an lmfit model result to a dictionary in order to be able to save
`lmfit_par_to_ufloat`(param)	Safe conversion of an `lmfit.parameter.Parameter` to
`check_lmfit`(→ str)	Check that lmfit was able to successfully return a valid fit, and give
`wrap_text`(…)	A text wrapping (braking over multiple lines) utility.
`analysis_steps_to_str`(→ str)	A utility for generating the docstring for the analysis steps.

Module Contents#

FIGURES_LRU_CACHE_SIZE = 8[source]#

class _FiguresMplCache[source]#

figs: dict[str, matplotlib.figure.Figure][source]#

axes: dict[str, matplotlib.axes.Axes][source]#

initialized: bool[source]#

settings[source]#

For convenience the analysis framework provides a set of global settings.

For available settings see BaseAnalysis. These can be overwritten for each instance of an analysis.

Examples

>>> from qblox_scheduler.analysis import base_analysis as ba
... ba.settings["mpl_dpi"] = 300  # set resolution of matplotlib figures

class AnalysisSteps[source]#

Bases: enum.Enum

An enumerate of the steps executed by the BaseAnalysis (and the default for subclasses).

The involved steps are:

AnalysisSteps.STEP_1_PROCESS_DATA (BaseAnalysis.process_data())
AnalysisSteps.STEP_2_RUN_FITTING (BaseAnalysis.run_fitting())
AnalysisSteps.STEP_3_ANALYZE_FIT_RESULTS (BaseAnalysis.analyze_fit_results())
AnalysisSteps.STEP_4_CREATE_FIGURES (BaseAnalysis.create_figures())
AnalysisSteps.STEP_5_ADJUST_FIGURES (BaseAnalysis.adjust_figures())
AnalysisSteps.STEP_6_SAVE_FIGURES (BaseAnalysis.save_figures())
AnalysisSteps.STEP_7_SAVE_QUANTITIES_OF_INTEREST (BaseAnalysis.save_quantities_of_interest())
AnalysisSteps.STEP_8_SAVE_PROCESSED_DATASET (BaseAnalysis.save_processed_dataset())
AnalysisSteps.STEP_9_SAVE_FIT_RESULTS (BaseAnalysis.save_fit_results())

A custom analysis flow (e.g. inserting new steps) can be created by implementing an object similar to this one and overriding the analysis_steps.

STEP_1_PROCESS_DATA = 'process_data'[source]#

STEP_2_RUN_FITTING = 'run_fitting'[source]#

STEP_3_ANALYZE_FIT_RESULTS = 'analyze_fit_results'[source]#

STEP_4_CREATE_FIGURES = 'create_figures'[source]#

STEP_5_ADJUST_FIGURES = 'adjust_figures'[source]#

STEP_6_SAVE_FIGURES = 'save_figures'[source]#

STEP_7_SAVE_QUANTITIES_OF_INTEREST = 'save_quantities_of_interest'[source]#

STEP_8_SAVE_PROCESSED_DATASET = 'save_processed_dataset'[source]#

STEP_9_SAVE_FIT_RESULTS = 'save_fit_results'[source]#

class AnalysisMeta[source]#

Bases: abc.ABCMeta

Metaclass, whose purpose is to avoid storing large amount of figure in memory.

By convention, analysis object stores figures in self.figs_mpl and self.axs_mpl dictionaries. This causes troubles for long-running operations, because figures are all in memory and eventually this uses all available memory of the PC. In order to avoid it, BaseAnalysis.create_figures() and its derivatives are patched so that all the figures are put in LRU cache and reconstructed upon request to BaseAnalysis.figs_mpl or BaseAnalysis.axs_mpl if they were removed from the cache.

Provided that analyses subclasses follow convention of figures being created in BaseAnalysis.create_figures(), this approach should solve the memory issue and preserve reverse compatibility with present code.

class BaseAnalysis(dataset: xarray.Dataset | None = None, tuid: quantify_core.data.types.TUID | str | None = None, label: str = '', settings_overwrite: dict | None = None, plot_figures: bool = True)[source]#

A template for analysis classes.

html_header_template = '<h1>{name}</h1><p style="font-family: monospace">TUID: {tuid}</p>'[source]#

_repr_html_()[source]#

An html representation of the analysis class.

Shows the name of the analysis and TUID as well as the (.svg) figures generated by this analysis.

logger[source]#

label = ''[source]#

tuid = None[source]#

settings_overwrite[source]#

dataset = None[source]#

dataset_processed[source]#

analysis_result[source]#

quantities_of_interest[source]#

fit_results[source]#

plot_figures = True[source]#

analysis_steps[source]#: Defines the steps of the analysis specified as an Enum. Can be overridden in a subclass in order to define a custom analysis flow. See AnalysisSteps for a template.

classmethod load_fit_result(tuid: quantify_core.data.types.TUID, fit_name: str) → lmfit.model.ModelResult[source]#

Load a saved lmfit.model.ModelResult object from file. For analyses that use custom fit functions, the cls.fit_function_definitions object must be defined in the subclass for that analysis.

Parameters:

tuid – The TUID reference of the saved analysis.
fit_name – The name of the fit result to be loaded.

Returns:

: The lmfit model result object.

property name[source]#: The name of the analysis, used in data saving.

static _get_analysis_dir(tuid: quantify_core.data.types.TUID, name: str, create_missing: bool = True)[source]#

Generate an analysis dir based on a given tuid and analysis class name.

Parameters:

tuid – TUID of the analysis dir.
name – The name of the analysis class.
create_missing – If True, create the analysis dir if it does not already exist.

property analysis_dir[source]#: Analysis dir based on the tuid of the analysis class instance. Will create a directory if it does not exist.

static _get_results_dir(analysis_dir: str, create_missing: bool = True)[source]#

Generate an results dir based on a given analysis dir path.

Parameters:

analysis_dir – The path of the analysis directory.
create_missing – If True, create the analysis dir if it does not already exist.

_analyses_figures_cache()[source]#

property results_dir[source]#: Analysis directory for this analysis. Will create a directory if it does not exist.

run() → typing_extensions.Self[source]#

Execute analysis.

This function is at the core of all analysis. It calls execute_analysis_steps() which executes all the methods defined in the.

First step of any analysis is always extracting data, that is not configurable. Errors in extract_data() are considered fatal for analysis. Later steps are configurable by overriding analysis_steps. Exceptions in these steps are logged and suppressed and analysis is considered partially successful.

This function is typically called right after instantiating an analysis class.

Implementing a custom analysis that requires user input

When implementing your own custom analysis you might need to pass in a few configuration arguments. That should be achieved by overriding this function as show below.

from qblox_scheduler.analysis.base_analysis import BaseAnalysis
from typing_extensions import Self

class MyAnalysis(BaseAnalysis):
    def run(self, optional_argument_one: float = 3.5e9) -> Self:
        # Save the value to be used in some step of the analysis
        self.optional_argument_one = optional_argument_one

        # Execute the analysis steps
        self.execute_analysis_steps()
        # Return the analysis object
        return self

    # ... other relevant methods ...

Returns:

: The instance of the analysis object so that run() returns an analysis object. You can initialize, run and assign it to a variable on a single line:, e.g. a_obj = MyAnalysis().run().

execute_analysis_steps()[source]#

Executes the methods corresponding to the analysis steps as defined by the analysis_steps.

Intended to be called by .run when creating a custom analysis that requires passing analysis configuration arguments to run().

get_flow() → tuple[source]#: Returns a tuple with the ordered methods to be called by run analysis. Only return the figures methods if self.plot_figures is True.

extract_data()[source]#

If no dataset is provided, populates .dataset with data from the experiment matching the tuid/label.

This method should be overwritten if an analysis does not relate to a single datafile.

process_data()[source]#

To be implemented by subclasses.

Should process, e.g., reshape, filter etc. the data before starting the analysis.

run_fitting()[source]#

To be implemented by subclasses.

Should create fitting model(s) and fit data to the model(s) adding the result to the .fit_results dictionary.

_add_fit_res_to_qoi()[source]#

analyze_fit_results()[source]#

To be implemented by subclasses.

Should analyze and process the .fit_results and add the quantities of interest to the .quantities_of_interest dictionary.

create_figures()[source]#

To be implemented by subclasses.

Should generate figures of interest. matplolib figures and axes objects should be added to the .figs_mpl and axs_mpl dictionaries., respectively.

adjust_figures()[source]#

Perform global adjustments after creating the figures but before saving them.

By default applies mpl_exclude_fig_titles and mpl_transparent_background from .settings_overwrite to any matplotlib figures in .figs_mpl.

Can be extended in a subclass for additional adjustments.

save_processed_dataset()[source]#: Saves a copy of the processed .dataset_processed in the analysis folder of the experiment.

save_quantities_of_interest()[source]#

Saves the .quantities_of_interest as a JSON file in the analysis directory.

The file is written using json.dump() with the qcodes.utils.NumpyJSONEncoder custom encoder.

save_fit_results()[source]#: Saves the lmfit.model.model_result objects for each fit in a sub-directory within the analysis directory.

save_figures()[source]#

Saves figures to disk. By default saves matplotlib figures.

Can be overridden or extended to make use of other plotting packages.

save_figures_mpl(close_figs: bool = True)[source]#

Saves all the matplotlib figures in the .figs_mpl dict.

Parameters:: close_figs – If True, closes matplotlib figures after saving.

display_figs_mpl()[source]#: Displays figures in .figs_mpl in all frontends.

adjust_ylim(ymin: float = None, ymax: float = None, ax_ids: list[str] = None) → None[source]#

Adjust the ylim of matplotlib figures generated by analysis object.

Parameters:

ymin – The bottom ylim in data coordinates. Passing None leaves the limit unchanged.
ymax – The top ylim in data coordinates. Passing None leaves the limit unchanged.
ax_ids – A list of ax_ids specifying what axes to adjust. Passing None results in all axes of an analysis object being adjusted.

adjust_xlim(xmin: float = None, xmax: float = None, ax_ids: list[str] = None) → None[source]#

Adjust the xlim of matplotlib figures generated by analysis object.

Parameters:

xmin – The bottom xlim in data coordinates. Passing None leaves the limit unchanged.
xmax – The top xlim in data coordinates. Passing None leaves the limit unchanged.
ax_ids – A list of ax_ids specifying what axes to adjust. Passing None results in all axes of an analysis object being adjusted.

adjust_clim(vmin: float, vmax: float, ax_ids: list[str] = None) → None[source]#

Adjust the clim of matplotlib figures generated by analysis object.

Parameters:

vmin – The bottom vlim in data coordinates. Passing None leaves the limit unchanged.
vmax – The top vlim in data coordinates. Passing None leaves the limit unchanged.
ax_ids – A list of ax_ids specifying what axes to adjust. Passing None results in all axes of an analysis object being adjusted.

adjust_cmap(cmap: matplotlib.colors.Colormap | str | None, ax_ids: list[str] = None)[source]#

Adjust the cmap of matplotlib figures generated by analysis object.

Parameters:

cmap – The colormap to set for the axis
ax_ids – A list of ax_ids specifying what axes to adjust. Passing None results in all axes of an analysis object being adjusted.

class BasicAnalysis(dataset: xarray.Dataset | None = None, tuid: quantify_core.data.types.TUID | str | None = None, label: str = '', settings_overwrite: dict | None = None, plot_figures: bool = True)[source]#

Bases: BaseAnalysis

A basic analysis that extracts the data from the latest file matching the label and plots and stores the data in the experiment container.

create_figures()[source]#: Creates a line plot x vs y for every data variable yi and coordinate xi in the dataset.

class Basic1DAnalysis(dataset: xarray.Dataset | None = None, tuid: quantify_core.data.types.TUID | str | None = None, label: str = '', settings_overwrite: dict | None = None, plot_figures: bool = True)[source]#

Bases: BasicAnalysis

Deprecated. Alias of BasicAnalysis for backwards compatibility.

run() → BaseAnalysis[source]#

Execute analysis.

This function is at the core of all analysis. It calls execute_analysis_steps() which executes all the methods defined in the.

First step of any analysis is always extracting data, that is not configurable. Errors in extract_data() are considered fatal for analysis. Later steps are configurable by overriding analysis_steps. Exceptions in these steps are logged and suppressed and analysis is considered partially successful.

This function is typically called right after instantiating an analysis class.

Implementing a custom analysis that requires user input

When implementing your own custom analysis you might need to pass in a few configuration arguments. That should be achieved by overriding this function as show below.

from qblox_scheduler.analysis.base_analysis import BaseAnalysis
from typing_extensions import Self

class MyAnalysis(BaseAnalysis):
    def run(self, optional_argument_one: float = 3.5e9) -> Self:
        # Save the value to be used in some step of the analysis
        self.optional_argument_one = optional_argument_one

        # Execute the analysis steps
        self.execute_analysis_steps()
        # Return the analysis object
        return self

    # ... other relevant methods ...

Returns:

: The instance of the analysis object so that run() returns an analysis object. You can initialize, run and assign it to a variable on a single line:, e.g. a_obj = MyAnalysis().run().

class Basic2DAnalysis(dataset: xarray.Dataset | None = None, tuid: quantify_core.data.types.TUID | str | None = None, label: str = '', settings_overwrite: dict | None = None, plot_figures: bool = True)[source]#

Bases: BaseAnalysis

A basic analysis that extracts the data from the latest file matching the label and plots and stores the data in the experiment container.

create_figures()[source]#

To be implemented by subclasses.

Should generate figures of interest. matplolib figures and axes objects should be added to the .figs_mpl and axs_mpl dictionaries., respectively.

flatten_lmfit_modelresult(model)[source]#

Flatten an lmfit model result to a dictionary in order to be able to save it to disk.

Notes

We use this method as opposed to save_modelresult() as the corresponding load_modelresult() cannot handle loading data with a custom fit function.

lmfit_par_to_ufloat(param: lmfit.parameter.Parameter)[source]#

Safe conversion of an lmfit.parameter.Parameter to uncertainties.ufloat(value, std_dev).

This function is intended to be used in custom analyses to avoid errors when an lmfit fails and the stderr is None.

Parameters:: param – The Parameter to be converted
Returns:: uncertainties.UFloat : An object representing the value and the uncertainty of the parameter.

check_lmfit(fit_res: lmfit.model.ModelResult) → str[source]#

Check that lmfit was able to successfully return a valid fit, and give a warning if not.

The function looks at lmfit’s success parameter, and also checks whether the fit was able to obtain valid error bars on the fitted parameters.

Parameters:

fit_res – The ModelResult object output by lmfit

Returns:

: A warning message if there is a problem with the fit.

wrap_text(text: str, width: int = 35, replace_whitespace: bool = True, **kwargs) → str[source]#

wrap_text(text: None, width: int = 35, replace_whitespace: bool = True, **kwargs) → None

A text wrapping (braking over multiple lines) utility.

Intended to be used with plot_textbox() in order to avoid too wide figure when, e.g., check_lmfit() fails and a warning message is generated.

For usage see, for example, source code of create_figures().

Parameters:

text – The text string to be wrapped over several lines.
width – Maximum line width in characters.
replace_whitespace – Passed to textwrap.wrap() and documented here.
kwargs – Any other keyword arguments to be passed to textwrap.wrap().

Returns:

: The wrapped text (or None if text is None).

analysis_steps_to_str(analysis_steps: enum.Enum, class_name: str = BaseAnalysis.__name__) → str[source]#

A utility for generating the docstring for the analysis steps.

Parameters:

analysis_steps – An Enum similar to qblox_scheduler.analysis.base_analysis.AnalysisSteps.
class_name – The class name that has the analysis_steps methods and for which the analysis_steps are intended.

Returns:

: A formatted string version of the analysis_steps and corresponding methods.