Usage guide (based on results_tg.ipynb)

This section documents the practical workflow used in src/results_tg.ipynb.

Minimal workflow

  1. Import the class:

from tg_analysis import TGAnalysis

  1. Define analysis mode and target fitted parameter:

mode = "constant_I"  # or "constant_E"
param_name = "tau"

  1. Define the JSON metadata file:

json_path = "external_files/parameters_CoOx12.json"

  1. Create the analysis object:

analysis = TGAnalysis(json_path)

  1. Inspect phase-space coverage (energy vs intensity):

analysis.plot_phase_space(errors_bool=True)

  1. Select scans according to mode:

if mode == "constant_E":
    params_scan = {"E": 63.6, "I": "all"}
else:
    params_scan = {"E": "all", "I": 2.0}
analysis.get_data_scan(params_scan)

  1. Fit models and extract parameters:

model_idxs = 2
analysis.get_fit_parameters(
    model_idxs=model_idxs,
    initial_guess_bool=True,
    bounds=True,
)

  1. Plot fit results:

analysis.plot_fits()
# Optional: decomposition into analytic components
# analysis.plot_fits(components_bool=True, save_path="../report/figures/fits_components.png")
if mode == "constant_E":
    analysis.plot_params_vs_intensity(param_name=param_name, errors_bool=False)
else:
    analysis.plot_params_vs_energy(param_name=param_name, errors_bool=False)

  1. Use stacked plots for detailed inspection:

analysis.plot_stacked_signals(
    limits_time=(0.0, 0.7),
    limits_signal=(0.01, 0.09),
    ylog_scale=True,
    plot_ind=[3],
    data_over_fit=True,
)

  1. Compare fit behavior across model configurations:

models_config = [
    {"model_idxs": 1, "initial_guess_bool": True, "bounds": True, "label_model": "Model 1", "color": "blue"},
    {"model_idxs": 2, "initial_guess_bool": True, "bounds": True, "label_model": "Model 2", "color": "red"},
    {"model_idxs": 3, "initial_guess_bool": True, "bounds": True, "label_model": "Model 3", "color": "green"},
]
analysis.plot_params_all_models(
    models_config,
    param_name=param_name,
    mode=mode,
    errors_bool=False,
    save_path="../report/figures/example_all_models.png",
)

mode must match how scans were selected: "constant_I" (parameter vs energy) or "constant_E" (parameter vs intensity).

Batch export (notebook)

results_tg.ipynb includes a loop over modes, models, and parameter names so you can regenerate report figures (fits, stacked signals, per-parameter plots, and optional plot_params_all_models overlays). Parameter names depend on the model (for example Model 1: amp1, t0, tau, sigma, ampoff, r2; Model 2: amp1, t0, tau, sigma, ampoff, amp2, tau2, r2; Model 3: amp1, amp2, amp3, t0, tau, tau2, tau3, sigma, r2). Adjust paths and models_config filters if a parameter exists only for some models.

What each block does in practice

  • TGAnalysis(json_path) loads metadata and builds df_scans with all ScanXXX entries.

  • get_data_scan(...) reads .mat files from main_path, applies optional time filtering, subtracts baseline, and normalizes each TG trace by its integral.

  • get_fit_parameters(...) runs curve_fit scan by scan and stores values + uncertainties in params_fit for each parameter.

  • plot_fits() compares measured data vs fitted curves and reports \(\chi^2/\mathrm{dof}\) and \(R^2\); use components_bool=True for dashed component curves when diagnosing multi-term models.

  • plot_params_vs_energy(...) overlays absorbance references and any selected fitted parameter when using constant-intensity mode.

  • plot_params_vs_intensity(...) plots fitted parameters against intensity when using constant-energy mode.

  • plot_params_all_models(...) compares one fitted parameter across multiple model configurations with explicit scan mode.

  • plot_stacked_signals(...) compares experimental traces and fitted curves in stacked panels with fit-centered time shifts.