Quick Reference Lists

Running Sequences

`matipo.sequence.Sequence`([file_path])	A class for running pulse sequence programs, keeping track of parameters, and reading back data.
`matipo.sequence.Sequence.setpar`([name, value])	Set one or more parameters.
`matipo.sequence.Sequence.loadpar`(file_path)	Load parameters from a yaml file.
`matipo.sequence.Sequence.savepar`(file_path)	Save parameters to a yaml file.
`matipo.sequence.Sequence.run`([progress_handler])	Run the pulse sequence program.
`matipo.sequence.Sequence.abort`()	Abort the sequence run.
`matipo.sequence.Sequence.data`	Data as a 1D numpy array of complex values
`matipo.sequence.Sequence.par`	Current parameters as an immutable `namedtuple`.

System Control

`matipo.system_api.reset`()
`matipo.system_api.tempctrl_get_pars`()
`matipo.system_api.tempctrl_set_pars`([...])
`matipo.system_api.tempctrl_get_history`([...])
`matipo.system_api.tempctrl_amp_off`()
`matipo.system_api.tempctrl_amp_on`()
`matipo.system_api.gpo_write`(value)
`matipo.system_api.gpo_set`(mask)
`matipo.system_api.gpo_clear`(mask)
`matipo.system_api.pwm_set`(period, width)
`matipo.system_api.pwm_start`()
`matipo.system_api.pwm_stop`()

Utility Libraries

`matipo.util.autophase`
`matipo.util.decimation`
`matipo.util.fft`
`matipo.util.ilt`
`matipo.util.dashboardapp`
`matipo.util.plots`
`matipo.util.stepper`
`matipo.util.etl.deinterlace`(data, n_ETL, ...)
`matipo.util.iomux`

Experiment Library

`matipo.experiment.BaseExperiment`([title, ...])	Base class for experiments that handles running the pulse sequence and plotting the results.
`matipo.experiment.plots`
`matipo.experiment.models`

Pulse Sequence Programming Libraries

`matipo.hardware.sequence_inst`
`matipo.datalayout`
`matipo.util.pulseshape`
`matipo.util.etl.sequence_format`(n_ETL, ...)

Full Reference

Sequence Class

class matipo.sequence.Sequence(file_path=None)

A class for running pulse sequence programs, keeping track of parameters, and reading back data.

Attributes:

data: Data as a 1D numpy array of complex values
par: Current parameters as an immutable namedtuple.

Methods

`abort`()	Abort the sequence run.
`fetch_data`()	Fetch data
`loadpar`(file_path)	Load parameters from a yaml file.
`run`([progress_handler])	Run the pulse sequence program.
`savepar`(file_path)	Save parameters to a yaml file.
`setpar`([name, value])	Set one or more parameters.

__init__(file_path=None)

Parameters:

file_pathstr: The path of the pulse sequence program python file

abort(): Abort the sequence run.

property data

Data as a 1D numpy array of complex values

Data from multiple acquisitions are concatenated in order. If the sequence has scan averaging the layout is the same as if only a single scan was run.

Data may be read before the sequence has finished to get partial data. To ensure full data, read after run() has finished.

async fetch_data()

Fetch data

Returns: Data, same format as data property.

Data will be incomplete if fetched before the sequence run has finished.

loadpar(file_path: str)

Load parameters from a yaml file.

Parameters:

file_pathstr: The absolute path of the source file

property par: Current parameters as an immutable namedtuple. Use setpar to modify parameters.

async run(progress_handler=None)

Run the pulse sequence program.

Returns: Data, same as data property.

Parameters:

progress_handlercallable, optional

Progress handler function that will be called whenever there is new progress with two positional arguments:

progress: current progress (int).
limit: maximum progress when finished (int).

Must return quickly.

savepar(file_path: str)

Save parameters to a yaml file.

Parameters:

file_pathstr: The absolute path of the destination file

setpar(name=None, value=None, **kwargs)

Set one or more parameters.

Parameter names which do not exist in the pulse sequence will be ignored.

Parameters:

namestr, optional: The name of the parameter to set.
valuetype varies with parameter, optional: The value of the parameter to set.
`**kwargs`: Set parameters using key=value pairs.

Sequence Parameter Definition Class

class matipo.sequence_common.ParDef(name, dtype, default, **kwargs)

Parameter Definition class for pulse sequence programs

__init__(name, dtype, default, **kwargs)

Parameters:

namestr: The name of the parameter, should be a valid python variable name
dtype: The data type of the parameter, may be a numpy.dtype or a python primitive or a constructor function for a user-defined type.
default: The default value of the parameter
minoptional
maxoptional
descriptionstr, optional
unitstr, optional unit definition which: can be used by GUI for display and automatic conversion

Sequence Hardware Option Type

class matipo.sequence_common.Options(amp_enabled, rx_gain)

Sequence Hardware Options namedtuple

Methods

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

System Control Functions

class matipo.system_api.StatusMonitor(on_data)

Methods

close

close()

matipo.system_api.fan_set(*args, **kwargs)

matipo.system_api.fan_start(*args, **kwargs)

matipo.system_api.fan_stop(*args, **kwargs)

matipo.system_api.gpo_clear(mask)

matipo.system_api.gpo_set(mask)

matipo.system_api.gpo_write(value)

matipo.system_api.notsupported_decorator(func)

matipo.system_api.pwm_set(period, width)

matipo.system_api.pwm_start()

matipo.system_api.pwm_stop()

matipo.system_api.reset() → None

matipo.system_api.tempctrl_amp_off()

matipo.system_api.tempctrl_amp_on()

matipo.system_api.tempctrl_get_history(sensor_num=0)

matipo.system_api.tempctrl_get_pars()

matipo.system_api.tempctrl_set_pars(setpoint=None, P=None, I=None)

IO Multiplex Control

matipo.util.iomux.disable_seq_gpo(mask): Set GPO Outputs to be controlled by the OS.

matipo.util.iomux.enable_seq_gpo(mask): Set GPO Outputs to be controlled by the pulse sequence.

Data Processing Utilities

matipo.util.autophase.autophase(y, t0=0, dwelltime=1, fast=False)

matipo.util.autophase.get_phase(y, t0=0, dwelltime=1)

matipo.util.decimation.decimate(data, dec, axis=0)

matipo.util.fft.fft_reconstruction(kdata, gaussian_blur=0, upscale_factor=1)

matipo.util.fft.get_freq_spectrum(signal, dwell_time)

matipo.util.ilt.CPMG_T2_spectrum(T2, t_echo, data, alpha=1, **kwargs)

CPMG_T2_spectrum: Calculate T2 spectrum from CPMG data

Parameters:

T2float array: T2 values for the output spectrum
t_echofloat or float array: scalar echo spacing or array of echo times (seconds)
datafloat or complex float array: array of CPMG data, shape (number of echos). The real part after autophasing will be used if complex.

matipo.util.ilt.IRCPMG_T1T2_spectrum(T1, T2, t_inv, t_echo, data, alpha=1, **kwargs)

IRCPMG_T1T2_spectrum: Calculate T1-T2 spectrum from Inversion Recovery CPMG data

Parameters:

T1float array: T1 values for the output spectrum
T2float array: T2 values for the output spectrum
t_invfloat array: inversion times (seconds)
t_echofloat or float array: scalar echo spacing or array of echo times (seconds)
data2D float or complex float array: 2D array of IRCPMG data, shape (number of inversion times, number of echos). The real part after autophasing will be used if complex.

matipo.util.ilt.IR_T1_spectrum(T1, t_inv, data, alpha=1, **kwargs)

IR_T1_spectrum: Calculate T1 spectrum from Inversion Recovery data

Parameters:

T1float array: T1 values for the output spectrum
t_invfloat array: inversion times (seconds)
datafloat or complex float array: array of IR data, shape (number of inversion times). The real part after autophasing will be used if complex.

matipo.util.etl.deinterlace(data, n_ETL, n_phase_1, n_phase_2, n_samples)

Experiment Building Tools

class matipo.experiment.BaseExperiment(title=None, seq=None, inputs={}, plots={}, enable_runloop=False, enable_progressbar=True, enable_partialplot=False, auto_save_default=False, partialplot_cooldown=1.0, progress_cooldown=1.0, workspace='default', state_id='', default_par_files=None)

Base class for experiments that handles running the pulse sequence and plotting the results.

Attributes:

seqSequence: Must override. Sequence that will be run by default run() method.
plotsdict: Should override. Dictionary of plot objects with a figure attribute and update() function.
inputsdict: Should override. Dictionary of input widgets. If the key matches a pulse sequence parameter it will be automatically loaded when the experiment is run. The auto_inputs function may be used to generate these inputs automatically from a pulse sequence.
titlestring: May override.
enable_runloopbool: May override. Enables Run Loop button.
enable_progressbarbool: May override. Enables progress bar.
enable_partialplotbool: May override. Enables plotting partial data on progress event.
partialplot_cooldownfloat: Minimum time in seconds between plot updates. Used to prevent slow plot update functions slowing the experiment down.
progress_cooldownfloat: Minimum time in seconds between progress bar updates. Workaround for panel performance issues.
default_par_fileslist of str: May override. List of default parameter files to be automatically loaded. Inputs or update_par() will override these defaults if they set the same parameter.
workspacestr: May override. Sets name of directory that data/state is automatically saved into.
state_idstr: May override. Set to a unique string to avoid sharing state files with other instances of the same experiment.
auto_save_default: bool: May override to enable auto save by default.

Methods

`setup`()	Should override to change attributes and perform initialisation.
`update_plots`([final])	May override to update plots.
`update_par`()	May override to set sequence parameter values before the sequence is run.
`run`([progress_handler])	May override to change run process.
`abort`()	May override to change abort process.
`layout_title`()	May override.
`layout_plots`()	May override.
`layout_controls`()	May override.
`layout_app`()	Returns panel object containing the whole experiment GUI.

abort(): May override to change abort process. Aborts the experiment.

layout_app()

Returns panel object containing the whole experiment GUI.

Optionally override to change overall layout.

layout_controls(): May override. Returns panel object containing the run/abort/save/log widgets.

layout_inputs(): May override. Returns panel object containing the input widgets.

layout_plots(): May override. Returns panel object containing the plot widgets.

layout_title()

May override. Returns panel object containing the title.

Optionally override to change the title formatting.

load(filepath)

Loads saved data and parameters from hdf5 file.

Optionally override to change load logic.

load_state(): Load state from file

async run(progress_handler=None)

May override to change run process. Runs the experiment.

Parameters:

progress_handler(progress, limit)callable, optional

Progress handler function that should be called whenever there is new progress with two positional arguments:

progress: current progress value (int).
limit: maximum progress value when finished (int).

When overriding, `progress_handler` may be passed on to the sequence run method:

`self.seq.run(progress_handler=progress_handler)` or used directly to indicate progress.

save()

Saves the sequence data and parameters to hdf5 file.

Returns path to file that was saved.

Optionally override to change save logic.

property save_filepath: Provides filepath to save data to.

save_state(): Save state to file

schedule_update_plots(final=False): Schedule a plot update from non-async code

setup()

Should override to change attributes and perform initialisation.

Will be called once on experiment instatiation.

property state: Retrieve state of widgets and plots

property state_filepath: Provides filepath to preserve state.

timestamp(): Returns current timestamp in string format

update_par()

May override to set sequence parameter values before the sequence is run.

Will be called once before the run method is called, after parameters are loaded from default files and set from inputs.

async update_plots(final=False)

May override to update plots. Will be called after every run or progress event.

Parameters:

finalbool: True if the run() method has finished executing, False if update_plots is being triggered by a progress update.

class matipo.experiment.plots.ComplexDataLinePlot(show_magnitude=False, show_complex=True, figure_opts={})

property state: Return plot state

update(x, y): Update the plot with x, y data arrays x: array of real values y: array of complex values

view()

class matipo.experiment.plots.Image1DPlot(**kwargs)

static process(seqdata, t_dw, g_read_mag, dec=4, gamma_bar=42577478.0)

update(seqdata, t_dw, g_read_mag, dec=4, gamma_bar=42577478.0): Update the plot with sequence data, dwell time, and read gradient magnitude

class matipo.experiment.plots.ImagePlot(figure_opts={}, image_opts={})

property state: Return plot state

update(imdata, fov_x=1, fov_y=1): Update the plot

class matipo.experiment.plots.LinePlot(figure_opts={}, line_opts={}, color_palette=['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'], legend_opts={})

property state: Return plot state

update(data)

Update the plot with a data dict, e.g.:

data = dict(: label_1=dict(x=[0], y=[0]), label_2=dict(x=[0], y=[0])

)

class matipo.experiment.plots.ScatterPlot(figure_opts={}, scatter_opts={}, color_palette=['#1f77b4', '#ff7f0e', '#2ca02c', '#d62728', '#9467bd', '#8c564b', '#e377c2', '#7f7f7f', '#bcbd22', '#17becf'], marker_palette=['circle', 'square', 'triangle', 'diamond', 'star', 'plus', 'hex'], legend_opts={})

property state: Return plot state

update(data)

Update the plot with a data dict, e.g.:

data = dict(: label_1=dict(x=[0], y=[0]), label_2=dict(x=[0], y=[0])

)

class matipo.experiment.plots.SignalPlot(**kwargs)

static process(seqdata, t_dw)

update(seqdata, t_dw): Update the plot with sequence data and dwell time

class matipo.experiment.plots.SpectrumPlot(**kwargs)

static process(seqdata, t_dw, t0=0, fast=False)

update(seqdata, t_dw, t0=0, fast=False): Update the plot with sequence data and dwell time

class matipo.experiment.plots.WobblePlot(figure_opts={})

property state: Return plot state

update(seqdata, f, f_bw, n_samples): Update the plot

matipo.experiment.models.FixedPrecisionTickFormatter(n=6)

matipo.experiment.models.SIHoverFormatter()

matipo.experiment.models.SITickFormatter()

Dashboard App Utilities

class matipo.util.dashboardapp.DashboardApp(document, sequence, autoplot_period=1.0, enable_progressbar=True, enable_run_loop=False, enable_autoplot=True)

Methods

abort
load
main
replot
run
save
set_progress
set_status

abort()

load(file_path)

main()

replot(fast=False)

async run()

save(file_path)

set_progress(p, l)

set_status(status)

class matipo.util.dashboardapp.ScaledInput(input, scale)

Methods

`count`(value, /)	Return number of occurrences of value.
`index`(value[, start, stop])	Return first index of value.

input: Alias for field number 0

scale: Alias for field number 1

class matipo.util.plots.ComplexPlot(x=[], y=[], show_magnitude=False, show_complex=True, **kwargs)

Methods

update_data

update_data(x, y)

class matipo.util.plots.ImagePlot(imdata=None, dw=1, dh=1, title='', sizing_mode='stretch_width', **kwargs)

Methods

update_axis_labels
update_data

update_axis_labels(x_axis_label, y_axis_label)

update_data(imdata, dw=1, dh=1, x=0, y=0)

class matipo.util.plots.SharedXPlot(x=[], ys={}, **kwargs)

bokeh figure with multiple lines sharing x data

Methods

update

update(x, ys)

class matipo.util.plots.UpdatableLinePlot(title='')

Methods

update_line

update_line(name, x, y)

class matipo.util.plots.WobblePlot(x=[], y=[], freq=0, **kwargs)

Methods

update_data

update_data(x, y, freq)

matipo.util.plots.get_SI_hover_formatter()

matipo.util.plots.get_SI_tick_formatter()

Stepper Motor Control

matipo.util.stepper.disable(): Power off stepper driver

matipo.util.stepper.enable(): Power on stepper driver

matipo.util.stepper.setdirection(direction): Set step direction, True: CW, False: CCW

matipo.util.stepper.setperiod(period): Set time between steps in seconds

matipo.util.stepper.setspeed(speed): Set speed in steps/second

matipo.util.stepper.start(): Start stepping

matipo.util.stepper.stop(): Stop stepping

Pulse Program Commands

matipo.hardware.sequence_inst.acquire(freq, phase, dw, samples)

matipo.hardware.sequence_inst.end()

matipo.hardware.sequence_inst.gpo_clear(mask)

matipo.hardware.sequence_inst.gpo_set(mask)

matipo.hardware.sequence_inst.gradient(x, y, z)

matipo.hardware.sequence_inst.init(amp_enable, rx_gain)

matipo.hardware.sequence_inst.pulse_blank()

matipo.hardware.sequence_inst.pulse_end()

matipo.hardware.sequence_inst.pulse_start(freq, phase, amp)

matipo.hardware.sequence_inst.pulse_unblank()

matipo.hardware.sequence_inst.pulse_update(freq, phase, amp)

matipo.hardware.sequence_inst.shim(x, y, z, z2, zx, xy, zy, x2y2)

matipo.hardware.sequence_inst.wait(time)

matipo.hardware.sequence_inst.wait_for_trigger()

Pulse Program Data Layout Definition

class matipo.datalayout.Acquisition(n_samples, t_dw)

n_samples: Alias for field number 0

t_dw: Alias for field number 1

class matipo.datalayout.List(child_list)

get_index()

process_data(data_in, data_out)

class matipo.datalayout.Repetitions(n, child)

get_index()

process_data(data_in, data_out)

class matipo.datalayout.Scans(n, child)

get_index()

process_data(data_in, data_out)

Pulse Program Utilities

matipo.util.pulseshape.calc_soft_pulse(pulse_width, pulse_bandwidth, flip_angle=90, N_max=256, spacing_min=1e-06)

matipo.util.etl.sequence_format(n_ETL, n_phase_1, n_phase_2)