itcsimlib.itc_experiment module

Core classes for handling simulated and empirical data.

class itcsimlib.itc_experiment.ITCExperimentBase(T, V0, injections, dQ, Cell, Syringe, skip=[], dQ_err=[], Q_dil=0.0, cellRef=None, syringeRef=None, title=None, units='J')

Bases: object

Provides the essential required elements of an ITC experiment.

chisq

If a fit has been generated, the reduced chi-squared goodness-of-fit value.

Type:float

T

The experimental temperature (in Kelvin).

Type:float

Concentrations

The concentrations of the components (in the cell) at each titration point

Type:list of dicts

Notes

Energies are stored in Joules internally, and then converted (if necessary) to the desired unit when retrieved by the user.

change_component_name(old_name, new_name)

Update the name of a component in the experiment to the specified one.

Parameters:

• old_name (string) – The name of the component in the experiment object to update
• new_name (string) – The new name of the component to use

Returns:

Return type:

None

Notes

Because syringe and cell components are referred to by name, problems can arise where the component is called by one name in the model, and another in the experiment. This method allows the user to update an experimental component by name to match the one used in the model, e.g. from the specific “Tryptophan” specified in the experiment file to the generic “Ligand” used in the model.

make_plot(residuals=True, hardcopy=False, hardcopydir='.', hardcopyprefix='', hardcopytype='png')

Generate a plot of the experimental data, and the fit if present.

Parameters:

• residuals (boolean) – Includes a plot of fit residuals if a fit is present.
• hardcopy (boolean) – Writes the plot to a file instead of displaying to screen.
• hardcopydir (string) – The directory to write the hardcopy to.
• hardcopyprefix (string) – A prefix to append to the experiment’s title when generating the output plot filename.
• hardcopytype (string) – The output format for the plot (availability is dependent upon what backends matplotlib was compiled with).

Returns:

Return type:

None

export_to_file(path, units='cal', full=False)

Export the attributes of the experiment to a file.

Parameters:

• path (string) – The filesystem path to write the output to.
• units (string) – The units to use in the export, must be either “J” for Joules (the default), or “cal” for calories.

Returns:

Return type:

None

Notes

Most instruments (for historical reasons) report binding enthalpies in calories. Thus, this is the default behavior for this method.

get_chisq(Q, writeback=False)

Calculate the goodness-of-fit between the provided data and the experimental data.

Parameters:

• Q (list of floats) – The predicted total heat at each injection point.
• writeback (boolean) – Update the experiment’s simulated heat attribute (dQ_fit) with the provided Qs, as well as the chisq value?

Returns:

The goodness of the fit, as a reduced chi-square or as a sum-of-squares if a experimental error in dQ was not provided.

Return type:

float

class itcsimlib.itc_experiment.ITCExperiment(spline_pts=7, spline_order=1, *args, **kwargs)

Bases: itcsimlib.itc_experiment.ITCExperimentBase

Provides splining for empirical ITC data.

spline

The smoothed spline (if any) to the experimental enthalpies, in Joules.

Type:list of floats

class itcsimlib.itc_experiment.ITCExperimentSynthetic(injections, noise=None, *args, **kwargs)

Bases: itcsimlib.itc_experiment.ITCExperimentBase

Provides the ability to save simulated data for display or re-fitting.

noise

The standard deviation (in percent) of normally-distributed noise to add to the pure simulated total evolved heat.

Type:float

initialized

A flag that is set once the class’s dQ_fit attribute has been set (see notes).

Type:boolean

Notes

The first time the get_chisq() method of this class is called, the “experimental” dQ attribute is populated with the per-injection heats simulated by the model (+ the amount of specified noise). Subsequent calls will return the actual reduced chi-square difference between the experiment’s calculated dQ and the model predictions, as expected.

If noise is set to 0 (or None), then the get_chisq() method of this class will always return 1.0, as without realistic noise, the reduced chisquare is meaningless.

get_chisq(Q, writeback)

Monkeypatches the parent ITCExperimentBase’s get_chisq() class method to update the class’s dQ_exp attribute the first time the method is called.

Parameters:

• Q (list of floats) – The predicted total heat at each injection point.
• writeback (boolean) – Update the experiment’s simulated heat attribute (dQ_fit) with the provided Qs?

Returns:

The goodness of the fit, as a reduced chi-square, unless the class’s noise attribute is zero or none in which case 1.0 is returned (see class notes).

Return type:

float