Quick Reference Lists

Running Sequences

`matipo.sequence.Sequence`([file_path, ...])	A class for running pulse sequence programs, managing 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.par`	Current parameters as an immutable `namedtuple`.
`matipo.sequence.Sequence.data`	Data as a 1D numpy array of complex values
`matipo.sequence.Sequence.data_map`	Data as a map (dict)
`matipo.sequence.Sequence.data_count`	Completed acquisition count as a map (dict)

Pulse Sequence Programming Libraries

`matipo.hardware.sequence_inst.SequencerTop`(index)	Timing Controller.
`matipo.hardware.sequence_inst.RFTX`(index)	RF Transmit Controller.
`matipo.hardware.sequence_inst.ACQ`(index)	RF Receive Acquisition Controller.
`matipo.hardware.sequence_inst.GRAD`(index)	Gradient Controller.
`matipo.hardware.sequence_inst.SHIM`(index)	Shim Controller.
`matipo.hardware.sequence_inst.GPO`(index)	General Purpose Output Controller.
`matipo.util.pulseshape`
`matipo.util.etl.sequence_format`(n_ETL, ...)
`matipo.sequence.ParDef`(name, dtype, default, ...)	Parameter Definition class for pulse sequence programs
`matipo.sequence.floatarray`(v)

System Control

`matipo.system_api.SystemAPI`([device_address])	Provides General System Control.
`matipo.system_api.SystemAPI.reset`()	Resets the pulse sequence driver.
`matipo.system_api.SystemAPI.poweroff`()	Powers the system off cleanly.
`matipo.system_api.SystemAPI.get_input_calibration`()	Returns hardware input calibration value.
`matipo.system_api.SystemAPI.set_input_calibration`(value)	Sets hardware input calibration value.

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`

Utility Libraries

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

Full Reference

Sequence Class

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

A class for running pulse sequence programs, managing parameters, and reading back data.

Attributes:

data: Data as a 1D numpy array of complex values
data_count: Completed acquisition count as a map (dict)
data_map: Data as a map (dict)
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, device_address=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 of acquisition ID (acqid). Multiple acquisitions with the same ID will be averaged.

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

property data_count

Completed acquisition count as a map (dict)

Keys are acquisition IDs, and values are the number of acquisitions completed and averaged together with that ID.

property data_map

Data as a map (dict)

Keys are acquisition IDs, and values are the averaged data from all acquisitions with that ID as a numpy array.

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:

elapsed: elapsed time (float).
total: total time to run (float).

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

Pulse Program Commands

class matipo.hardware.sequence_inst.SequencerTop(index)

Timing Controller. Top level of sequencer hierarchy.

Each attribute contains a tuple of peripheral controllers of that type.

Attributes:

txtuple: Tuple of all RF transmit (RFTX) peripherals.
rxtuple: Tuple of all RF receive (ACQ) peripherals.
gradtuple: Tuple of all gradient control (GRAD) peripherals.
shimtuple: Tuple of all shim control (SHIM) peripherals.
gpotuple: Tuple of all general purpose output (GPO) peripherals.

Methods

wait:	Wait for a delay time
join:	Join multiple sequence commands into a single command

static join(cmds)

Join multiple sequence commands into a single command.

Parameters:

cmdslist: list of commands to join.
Returns: `bytes`, pulse sequence command bytecode.

wait(t)

Wait for a delay time.

Any commands given to child peripherals will be queued and begin simultaneously on the next wait delay.

Parameters:

tfloat: delay time in seconds

class matipo.hardware.sequence_inst.ACQ(index)

RF Receive Acquisition Controller.

acquire(acqid, length)

Start an acquisition.

Parameters:

acqidint: ID to associate with this acquisition. Acquisitions with the same ID will be aggregated and must have the same length.
lengthint: Number of samples to acquire.

dwelltime(dwelltime)

Update receive data decimation rate.

Parameters:

dwelltimefloat: Dwell time (sample spacing) in seconds.

freq(freq)

Update receive frequency.

Parameters:

freqfloat: Frequency in Hz.

mode(raw=False, flatfilter=True)

Update acquisition filtering options.

Parameters:

rawbool, default False

False: data will be demodulated and decimated to the desired dwell time.
True: data from the ADC will be recorded directly (no DSP).

flatfilterbool, default True

False: data will only be decimated with a fast settling CIC filter.
True: data will also post-filtered to compensate for the CIC filter’s rolloff, resulting in a flat frequency response, but slow settling time.

This setting has no effect when raw mode is enabled.

phase(phase)

Update receive phase.

Parameters:

phasefloat: Phase in Degrees.

class matipo.hardware.sequence_inst.GPO(index)

General Purpose Output Controller.

clear(mask)

Clear selected GPOs LOW, other GPOs will be unaffected.

Parameters:

maskint: Bitmask of GPOs to clear LOW.

set(mask)

Set selected GPOs HIGH, other GPOs will be unaffected.

Parameters:

maskint: Bitmask of GPOs to set HIGH.

write(value)

Write state of all GPOs

Parameters:

valueint: Bit pattern to write to GPO register.

class matipo.hardware.sequence_inst.GRAD(index)

Gradient Controller.

aux(value)

Update auxiliary DAC output (4th gradient channel).

Parameters:

valuefloat: Aux. DAC amplitude, in the interval [-1, 1].

vec(x, y, z)

Update the gradient output vector.

Parameters:

xfloat: X gradient amplitude, in the interval [-1, 1].
yfloat: Y gradient amplitude, in the interval [-1, 1].
zfloat: Z gradient amplitude, in the interval [-1, 1].

class matipo.hardware.sequence_inst.RFTX(index)

RF Transmit Controller.

amp(amp)

Update transmit amplitude.

Parameters:

ampfloat: Amplitude ratio, in the interval [-1, 1]. Negative amplitude may be used to invert phase.

disable(): Disable RF output.

enable(): Enable RF output.

freq(freq)

Update transmit frequency.

Parameters:

freqfloat: Frequency in Hz.

phase(phase)

Update transmit phase.

Parameters:

phasefloat: Phase in Degrees.

set_enable(enable)

Set whether RF output is enabled using boolean.

Parameters:

enablebool: RF enable state.

class matipo.hardware.sequence_inst.SHIM(index)

Shim Controller.

set(channel, value)

Update a single shim channel.

Parameters:

channelint: Shim channel, in the range [0, 15].
valuefloat: Shim amplitude, in the interval [-1, 1].

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)

class matipo.sequence.ParDef(name, dtype, default, **kwargs): Parameter Definition class for pulse sequence programs

matipo.sequence.floatarray(v)

System Control Functions

class matipo.system_api.SystemAPI(device_address=None)

Provides General System Control.

Methods

`get_input_calibration`()	Returns hardware input calibration value.
`poweroff`()	Powers the system off cleanly.
`reset`()	Resets the pulse sequence driver.
`set_input_calibration`(value)	Sets hardware input calibration value.

tempctrl_enable_PID
tempctrl_get_config
tempctrl_get_history
tempctrl_get_pwm_duty
tempctrl_get_pwm_history
tempctrl_get_temperature
tempctrl_set_PID
tempctrl_set_pwm_override
tempctrl_set_pwm_period
tempctrl_setpoint

get_input_calibration() → float: Returns hardware input calibration value.

poweroff() → None: Powers the system off cleanly.

reset() → None: Resets the pulse sequence driver.

set_input_calibration(value: float) → None: Sets hardware input calibration value.

tempctrl_enable_PID(pwm=0)

tempctrl_get_config()

tempctrl_get_history(sensor=0)

tempctrl_get_pwm_duty(pwm=0)

tempctrl_get_pwm_history(pwm=0)

tempctrl_get_temperature(sensor=0)

tempctrl_set_PID(pwm=0, sensor=0, KP=None, KI=None, KD=None)

tempctrl_set_pwm_override(pwm=0, duty=0)

tempctrl_set_pwm_period(pwm=0, period=1)

tempctrl_setpoint(temp)

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()