fitting.AMARES - MNUtils

fitting.AMARES

Attributes¶

Name	Description
`DEFAULT_BATCH_FIT_PARAMS`
`DEFAULT_FIT_PARAMS`
`DEFAULT_INIT_PARAMS`
`DEFAULT_PLOT_PARAMS`

Classes¶

Name	Description
FitResults	Container for extracted pyAMARES batch fitting results.

FitResults¶

fitting.AMARES.FitResults(badfit_ids, goodness_of_fit, combined_fit_results)

Container for extracted pyAMARES batch fitting results.

Attributes¶

Name	Description
`badfit_ids`
`combined_fit_results`
`goodness_of_fit`

Functions¶

Name	Description
add_colored_table_to_plot	Add a colored table beneath the given axis in the plot.
extract_from_fit_results	Extract goodness-of-fit metrics and combined fit parameters from batch fit results.
fit_multiple_fids	Batch-fit multiple FIDs in parallel using the pyAMARES library.
fit_single_fid	Fit a single FID using the pyAMARES fitting library.
load_extracted_results	Load extracted fitting results from an HDF5 file.
multiindex_to_priorknowledge	Convert a MultiIndex prior-knowledge DataFrame back into a raw DataFrame.
plot_amares_fitting	Plot an AMARES fitting result, optionally with a parameter table.
priorknowledge_to_multiindex	Convert a prior-knowledge DataFrame into a MultiIndex DataFrame.
save_extracted_results	Save the extracted fitting results to an HDF5 file.

add_colored_table_to_plot¶

fitting.AMARES.add_colored_table_to_plot(table_ax, table, sig=3)

Add a colored table beneath the given axis in the plot.

Parameters¶

Name	Type	Description	Default
table_ax	matplotlib.axes.Axes	The axis to which the table will be added.	required
table	pandas.DataFrame	The table data to be displayed, with a 2-level MultiIndex column (parameter, value_type).	required
sig	int	The number of significant digits to round the table values to. Defaults to 3.	`3`

Returns¶

Name	Type	Description
	matplotlib.axes.Axes	The axis the table was added to.

extract_from_fit_results¶

fitting.AMARES.extract_from_fit_results(
    fit_results,
    bad_fit_chisqr_threshold=-1.0,
    ppm_offset=DEFAULT_INIT_PARAMS['ppm_offset'],
    index_key='voxel_id',
    index_values=None,
)

Extract goodness-of-fit metrics and combined fit parameters from batch fit results.

Parameters¶

Name	Type	Description	Default
fit_results	list of tuple	Per-voxel results as returned by `fit_multiple_fids`, each a `(DataFrame, MinimizerResult)` tuple.	required
bad_fit_chisqr_threshold	float	Chi-squared threshold above which a fit is flagged as bad. If negative (default), it is set to 3x the median chi-squared.	`-1.0`
ppm_offset	float	Offset subtracted from the fitted chemical shift values. Defaults to `DEFAULT_INIT_PARAMS["ppm_offset"]`.	`DEFAULT_INIT_PARAMS['ppm_offset']`
index_key	str	Name used for the voxel index in the returned DataFrames. Defaults to “voxel_id”.	`'voxel_id'`
index_values	list or pandas.Index	Values to use for the voxel index. Must match the length of `fit_results` if provided. Defaults to a range index.	`None`

Returns¶

Name	Type	Description
	FitResults	The bad fit ids, goodness-of-fit metrics, and combined fit results.

fit_multiple_fids¶

fitting.AMARES.fit_multiple_fids(
    fids,
    batch_fitting_params=None,
    init_params=None,
    batch_fitting_obj=None,
    raw_header=None,
)

Batch-fit multiple FIDs in parallel using the pyAMARES library.

Initializes a batch fitting object from the average FID of the highest SNR voxels, then applies parallel fitting to every input FID.

Parameters¶

Name	Type	Description	Default
fids	ndarray or xarray.DataArray	The input FIDs (time-domain signals) to be fitted. Expected shape is `(n_signals, n_points)`.	required
batch_fitting_params	dict	Parameters for batch fitting, merged over `DEFAULT_BATCH_FIT_PARAMS`.	`None`
init_params	dict	Initial parameters for fitting, merged over `DEFAULT_INIT_PARAMS`.	`None`
batch_fitting_obj	optional	A pre-initialized batch fitting object to reuse instead of creating a new one.	`None`
raw_header	dict	Raw header information passed to the initial single-FID fit.	`None`

Returns¶

Name	Type	Description
	list[tuple]	The fitting results for each FID, each including the fitted parameters and other relevant information.

Notes¶

The batch fitting object is initialized using the average FID of the 10 highest-SNR voxels (or fewer if there are fewer than 10 FIDs). pyAMARES.run_parallel_fitting_with_progress performs the parallel fitting with a progress indicator.

fit_single_fid¶

fitting.AMARES.fit_single_fid(
    fid,
    init_params,
    fit_params=None,
    raw_header=None,
    filter_by_ppm=None,
)

Fit a single FID using the pyAMARES fitting library.

Parameters¶

Name	Type	Description	Default
fid	ndarray or xarray.DataArray	The input FID (time-domain signal) to be fitted.	required
init_params	dict	Initial parameters for fitting. Must include `priorknowledgefile`, `MHz`, `sw`, and `deadtime` (directly or via `raw_header`).	required
fit_params	dict	Fitting parameters, merged over `DEFAULT_FIT_PARAMS`.	`None`
raw_header	dict	Raw scanner header, used to derive `MHz`/`sw`/`deadtime` defaults.	`None`
filter_by_ppm	tuple[float, float]	If given, restrict fitting to this ppm range.	`None`

Returns¶

Name	Type	Description
	pyAMARES fit result	The fitted FID result object.

Raises¶

Name	Type	Description
	ValueError	If a required field (`priorknowledgefile`, `MHz`, `sw`, `deadtime`) is missing from the merged init parameters.

load_extracted_results¶

fitting.AMARES.load_extracted_results(path)

Load extracted fitting results from an HDF5 file.

Parameters¶

Name	Type	Description	Default
path	str or Path	The file path from which the results will be loaded.	required

Returns¶

Name	Type	Description
	tuple[FitResults, dict]	The loaded fitting results, and a dictionary of user attributes stored alongside them.

Raises¶

Name	Type	Description
	(FileNotFoundError, KeyError, OSError, ValueError)	If reading the HDF5 file fails.

multiindex_to_priorknowledge¶

fitting.AMARES.multiindex_to_priorknowledge(pk_df, group_order=None)

Convert a MultiIndex prior-knowledge DataFrame back into a raw DataFrame.

Parameters¶

Name	Type	Description	Default
pk_df	pandas.DataFrame	The MultiIndex prior-knowledge DataFrame.	required
group_order	list of str	Section headers to group and sort by. Defaults to `["Initial Values", "Bounds"]`.	`None`

Returns¶

Name	Type	Description
	pandas.DataFrame	The flattened, sorted DataFrame.

plot_amares_fitting¶

fitting.AMARES.plot_amares_fitting(
    result,
    title=None,
    fig_kwargs=None,
    ax_kwargs=None,
    autophase=DEFAULT_PLOT_PARAMS['ifphase'],
    add_table=False,
)

Plot an AMARES fitting result, optionally with a parameter table.

Parameters¶

Name	Type	Description	Default
result	pyAMARES fit result	The result object containing the fitting parameters and data.	required
title	str	The title of the plot. Defaults to “AMARES Fitting Result”.	`None`
fig_kwargs	dict	Additional keyword arguments for `plt.subplots`.	`None`
ax_kwargs	dict	Additional keyword arguments applied to the main axes via `ax.set`.	`None`
autophase	bool	Whether to apply autophase to the data. Defaults to `DEFAULT_PLOT_PARAMS["ifphase"]`.	`DEFAULT_PLOT_PARAMS['ifphase']`
add_table	bool	Whether to add a parameter table beneath the plot. Defaults to False.	`False`

Returns¶

Name	Type	Description
	matplotlib.figure.Figure	The combined figure.

priorknowledge_to_multiindex¶

fitting.AMARES.priorknowledge_to_multiindex(pk_df, sections=None)

Convert a prior-knowledge DataFrame into a MultiIndex DataFrame.

Parameters¶

Name	Type	Description	Default
pk_df	pandas.DataFrame	The prior-knowledge DataFrame.	required
sections	list of str	Section headers to group by. Defaults to `["Initial Values", "Bounds"]`.	`None`

Returns¶

Name	Type	Description
	pandas.DataFrame	The DataFrame reindexed with a `(Group, Index)` MultiIndex.

save_extracted_results¶

fitting.AMARES.save_extracted_results(
    path,
    fit_results,
    attributes_to_add=None,
    additional_datasets=None,
    prepend_datetime=False,
    move_old=True,
)

Save the extracted fitting results to an HDF5 file.

Parameters¶

Name	Type	Description	Default
path	str or Path	The file path where the results will be saved. Forced to a `.h5` suffix if it doesn’t already end in `.h5`/`.hdf5`.	required
fit_results	FitResults	The fitting results to save (badfit IDs, goodness-of-fit metrics, and combined fit results).	required
attributes_to_add	dict[str, str or int]	Additional attributes to add to the HDF5 file.	`None`
additional_datasets	dict[str, ndarray]	Additional datasets to write into the HDF5 file.	`None`
prepend_datetime	bool	Whether to prepend the current datetime to the filename.	`False`
move_old	bool	Whether to move any existing file with the same stem into an “old” subfolder first. Defaults to True.	`True`

Returns¶

Name	Type	Description
	Path	The path to the saved file.

Raises¶

Name	Type	Description
	FileExistsError	If the target path already exists (after any datetime prefix).
	(OSError, KeyError, ValueError)	If writing the HDF5 file fails.