Create your own sequence analsysis - josalggui/MaRGE GitHub Wiki

Sequence Analysis Template Guide

This guide explains how to use and customize the Python Sequence Analysis Template for processing and visualizing sequence data stored in .mat files.

Overview

The sequence analysis template is designed to:

  • Load raw sequence data from a .mat file
  • Print input parameters (if available)
  • Perform custom signal analysis
  • Return:
    • A dictionary of numerical results (output_dict)
    • A list of plotting instructions (outputs)

The template is intentionally modular so it can be reused across different sequences with minimal changes.

Script Location and Naming Convention

When creating a new sequence analysis script, both the file name and function name must match the sequence name used in the corresponding sequence configuration.

Required Location

All sequence analysis scripts must be located in marge/recon.

Scripts placed outside this directory will not be detected by the reconstruction pipeline.

Required Naming Rule

The script name must exactly match the seqName value selected in the sequence definition.

For example:

  • If seqName = SpinEcho

    • Script file name: SpinEcho.py
    • Function name: SpinEcho(raw_data_path=None)

  • If seqName = GradientEcho

    • Script file name: GradientEcho.py
    • Function name: GradientEcho(raw_data_path=None)

This one-to-one mapping is required for automatic execution.

Parameters

  • raw_data_path (str)
    Path to the .mat file containing the raw sequence data.

Returns

  • output_dict (dict)
    Stores derived numerical values, metrics, or metadata.

  • outputs (list)
    List of plotting dictionaries used by the visualization framework.

Code Structure

The template is organized into clearly defined sections:

  1. Safety check
  2. Data loading
  3. Input parameter printing
  4. Variable extraction
  5. Analysis
  6. Plot generation
  7. Return values

Each section is marked with comments to make customization easy.

Customization Guide

1. Load Custom Variables

Modify this section to match your sequence. Load only the variables required for your specific analysis and remove unused fields to keep the code clean and readable.

data = mat_data["data_decimated"][0]
n_points = mat_data["nPoints"].item()
bw = mat_data["bw_MHz"].item()
n_repetitions = mat_data["nRepetitions"].item()

2. Add Analysis Logic

This section contains sequence-specific signal processing. Typical analysis tasks may include:

  • Signal-to-noise ratio (SNR) computation
  • Peak detection
  • FFT or spectral analysis
  • Averaging across repetitions

Store all derived numerical results in the output dictionary so they can be reused or logged later.

t_vector = np.linspace(
    0,
    n_points * n_repetitions / bw,
    n_points * n_repetitions

output_dict["max_signal"] = np.max(np.abs(data))
output_dict["mean_signal"] = np.mean(np.abs(data))

)

3. Customize Plots

Plots are defined as dictionaries that describe how data should be visualized.

result_1 = {
    "widget": "curve",
    "xData": t_vector,
    "yData": [np.abs(data)],
    "xLabel": "Time (ms)",
    "yLabel": "Amplitude (mV)",
    "title": "My Custom Sequence",
    "legend": ["abs"],
    "row": 0,
    "col": 0
}

When customizing plots, you can:

  • Add multiple plots
  • Arrange plots using rows and columns
  • Plot different signal representations (magnitude, real, imaginary, phase, etc.)

Append all plot definitions to the outputs list.

Adding Multiple Plots

outputs = [result_1, result_2, result_3]

Multiple plots can be returned by appending additional plot dictionaries to the outputs list. Each plot must define its own position using row and column indices.

Best Practices

  • Keep analysis logic separate from plotting
  • Store only numerical results in the output dictionary
  • Use clear and descriptive titles and axis labels
  • Clone the template for each new sequence

Executing Sequence Analysis Standalone

The sequence analysis can be run in Standalone mode directly using the run_recon function. This allows automatic detection of the sequence from the .mat file and generates plots without needing additional plotting calls.

Example:

from marge.recon import run_recon

output_dict, output = run_recon(
    raw_data_path="../experiments/acquisitions/Example/2025.05.29.16.42/Example/None/mat/Noise.2025.05.29.16.42.11.897.mat",
    mode="Standalone"
)

Key Points:

  • run_recon reads the seqName field from the .mat file and executes the corresponding sequence-specific function.
  • If mode="Standalone", plots are automatically displayed using Matplotlib.
  • If a printer object is provided, plots are sent to it instead of being shown.
  • Returns output_dict and output for further programmatic use.

Summary

This template provides a consistent and extensible framework for sequence analysis:

  • Minimal boilerplate code for rapid development
  • Safe handling of optional inputs and missing data
  • Flexible plotting system supporting curves and images
  • Easy reuse and integration across multiple experiments
  • Supports Standalone mode for immediate visualization

Use this template as a foundation and extend it with sequence-specific analysis and plotting logic.