MasterCurve

class mastercurves.mc.MasterCurve(fixed_noise=0.04)

Class definition for a master curve, consisting of multiple data sets superimposed.

A MasterCurve object will contain all of the data used to construct a master curve, along with the coordinate transformations, parameters for coordinate transformations (such as shift factors), associated uncertainties, Gaussian process models, and transformed data.

Attributes:

xdata (list[array_like]): list whose elements are the independent coordinates for a data set at a given state

ydata (list[array_like]): list whose elements are the dependent coordinates for a data set at a given state

states (list[float]): list whose elements are the value of the state defining each data set

htransforms (list[Transform]): list whose elements are the coordinate transforms performed on the independent coordinate (i.e. horizontally)

hparam_names (list[string]): list whose elements are the names of the parameters for the horizontal transforms

hbounds (list[tuple]): list whose elements are the upper and lower bounds for the horizontal transformation parameters

hshared (list[bool]): list whose elements indicate whether the corresponding element of hparam_names is a parameter whose value is shared across all states (True) or takes on an independent value for each state (False)

hparams (list[list[float]]): list whose elements are the values of the horizontal transformation parameters at each state

huncertainties (list[float]): list whose elements are the uncertainties associated with the values in hparams

vtransforms (list[Transform]): list whose elements are the coordinate transforms performed on the dependent coordinate (i.e. vertically)

vparam_names (list[string]): list whose elements are the names of the parameters for the vertical transforms

vbounds (list[tuple]): list whose elements are the upper and lower bounds for the vertical transformation parameters

vshared (list[bool]): list whose elements indicate whether the corresponding element of vparam_names is a parameter whose value is shared across all states (True) or takes on an independent value for each state (False)

vparams (list[list[float]]): list whose elements are the values of the vertical transformation parameters at each state

vuncertainties (list[float]): list whose elements are the uncertainties associated with the values in vparams

kernel (sklearn.gaussian_process.kernels.Kernel): kernel function for the Gaussian process model

gps (list[sklearn.gaussian_process.GaussianProcessRegressor]): list whose elements are Gaussian process models for each state

xtransformed (list[array_like]): list whose elements are the transformed independent coordinates for a data set at a given state

ytransformed (list[array_like]): list whose elements are the transformed dependent coordinates for a data set at a given state

__init__(fixed_noise=0.04)

Initialize a MasterCurve object.

Args:

fixed_noise (float): the fixed noise level for the Gaussian process models, corresponding to experimental uncertainty not evident in the data. By default, the noise level is 0.04.

add_data(xdata_new, ydata_new, states_new)

Add a data set or data sets to the master curve.

Args:

xdata_new (array_like or list[array_like]): array(s) corresponding to the dependent coordinates for given states

ydata_new (array_like or list[array_like]): array(s) corresponding to the independent coordinates for given states

states_new (float or list[float]): values of the state parameter corresponding to the data in xdata_new and ydata_new

add_htransform(htransform)

Add a horizontal transformation (or series of sequential transformations) to the master curve.

Args:

htransform (Transform): object of a Transform class, which implements the coordinate transformation and stores information about transformation parameters

add_vtransform(vtransform)

Add a vertical transformation (or series of sequential transformations) to the master curve.

Args:

vtransform (Transform): object of a Transform class, which implements the coordinate transformation and stores information about transformation parameters

change_ref(ref_state, a_ref=1, b_ref=1)

Change the reference state for the master curve.

Args:

ref_state (float): the new reference state, which may or may not be one of the current states

a_ref (float): if ref_state is not a current state, must be provided. This is the new reference’s horizontal shift with respect to the current reference. Defaults to 1.

b_ref (float): if ref_state is not a current state, must be provided. This is the new reference’s vertical shift with respect to the current reference. Defaults to 1.

clear()

Clear the master curve’s data (useful for memory management).

hpopt(lamh=None, lamv=None, npoints=100, alpha=0.5, folds=10)

Perform hyperparameter optimization on the prior (regularization) using MCCV.

Args:

lamh (list[tuple[float]]): ranges (tuples) for the horizontal hyperparameter search. If not searching this parameter, then the entry should be None.

lamv (list[tuple[float]]): ranges (tuples) for the vertical hyperparameter search. If not searching this parameter, then the entry should be None.

npoints (int): number of grid points to search. Default is 100.

alpha (float): keep rate for MCCV. Default is 0.5.

folds (int): number of MCCV folds. Default is 10.

Returns:

lamh_opt (list[float]): optimal horizontal hyperparameters at each state

lamv_opt (list[float]): optimal vertical hyperparameters at each state

output_table(file=None)

Write a csv file with a table of all parameters (and return as a data frame).

Args:

file (string): (optional) path to the file to which the data frame will be written

Returns:

df (pandas.DataFrame): data frame containing the transformation parameters

plot(log=True, colormap=matplotlib.pyplot.cm.tab10, colorby='index')

Plot the data, GPs, and master curve.

Args:

log (bool): whether the data represents the logarithm of the measured quantity. Defaults to True.

colormap (matplotlib.colors.Colormap): colormap for plotting. Defaults to the tab10 colormap.

colorby (string): how to color the data. Options are index for coloring by index, or state for coloring by the value of the state. Defaults to index.

Returns:

fig1, ax1 (matplotlib.Figure and matplotlib.axes.Axes): the figure and axes objects displaying the raw (untransformed data)

fig2, ax2 (matplotlib.Figure and matplotlib.axes.Axes): the figure and axes objects displaying the untransformed data and GP models

fig3, ax3 (matplotlib.Figure and matplotlib.axes.Axes): the figure and axes objects displaying the superposed data (i.e. the master curve)

set_gp_kernel(kernel)

Set the kernel function for the Gaussian Processes used to fit the data.

Args:

kernel (sklearn.gaussian_process.kernels.Kernel): the (potentially composite) kernel function

superpose(lamh=None, lamv=None)

Optimize the transformations to superpose the data sets onto a single master curve.

Args:

lamh (list[float]): hyperparameters for the horizontal shifts, corresponding to each state in the master curve. Defaults to None, meaning a uniform (unregularized) prior.

lamv (list[float]): hyperparameters for the vertical shifts, corresponding to each state in the master curve. Defaults to None, meaning a uniform (unregularized) prior.

Returns:

loss_min (float): the minimum loss computed during superposition