The ihm.flr Python module

Classes to handle fluorescence data. The classes roughly correspond to categories in the FLR dictionary. See the top level FLRData class for more information.

class ihm.flr.Probe(probe_list_entry=None, probe_descriptor=None)

Defines a fluorescent probe.

This class is not in the FLR dictionary, but it collects all the information connected by the probe_ids.

Parameters:

• probe_list_entry (ProbeList) – A probe list object.
• probe_descriptor (ProbeDescriptor) – A probe descriptor.

class ihm.flr.ProbeDescriptor(reactive_probe_chem_descriptor, chromophore_chem_descriptor, chromophore_center_atom=None)

Collects the chemical descriptors for a fluorescent probe.

This includes the chemical descriptor of the reactive probe and the chromophore.

Parameters:

• reactive_probe_chem_descriptor (ihm.ChemDescriptor) – The chemical descriptor for the reactive probe.
• chromophore_chem_descriptor (ihm.ChemDescriptor) – The chemical descriptor of the chromophore.
• chromophore_center_atom – The atom describing the center of the chromophore.

class ihm.flr.ProbeList(chromophore_name, reactive_probe_flag=False, reactive_probe_name=None, probe_origin=None, probe_link_type=None)

Store the chromophore name, whether there is a reactive probe available, the origin of the probe and the type of linkage of the probe.

Parameters:

• chromophore_name (str) – The name of the chromophore.
• reactive_probe_flag (bool) – Flag to indicate whether a reactive probe is given.
• reactive_probe_name (str) – The name of the reactive probe.
• probe_origin (str) – The origin of the probe (intrinsic or extrinsic).
• probe_link_type (str) – The type of linkage for the probe (covalent or ligand).

class ihm.flr.SampleProbeDetails(sample, probe, fluorophore_type='unspecified', poly_probe_position=None, description=None)

Connects a probe to a sample.

Parameters:

• sample (Sample) – The sample.
• probe (Probe) – A probe that is attached to the sample.
• fluorophore_type (str) – The type of the fluorophore (donor, acceptor, or unspecified).
• poly_probe_position (PolyProbePosition) – The position on the polymer where the dye is attached to.
• description (str) – A description of the sample-probe-connection.

class ihm.flr.PolyProbeConjugate(sample_probe, chem_descriptor, ambiguous_stoichiometry=False, probe_stoichiometry=None)

Describes the conjugate of polymer residue and probe (including possible linker)

Parameters:

• sample_probe (SampleProbeDetails) – The SampleProbeDetails object to which the conjugate is related.
• chem_descriptor (ihm.ChemDescriptor) – The chemical descriptor of the conjugate of polymer residue and probe.
• ambiguous_stoichiometry (bool) – Flag whether the labeling is ambiguous.
• probe_stoichiometry (float) – The stoichiometry of the ambiguous labeling.

class ihm.flr.PolyProbePosition(resatom, mutation_flag=False, modification_flag=False, auth_name=None, mutated_chem_comp_id=None, modified_chem_descriptor=None)

Describes a position on the polymer used for attaching the probe.

This class combines Poly_probe_position, Poly_probe_position_modified, and Poly_probe_position_mutated from the FLR dictionary.

Parameters:

• resatom (ihm.Residue or ihm.Atom) – The residue or atom that the probe is attached to.
• mutation_flag (bool) – Flag whether the residue was mutated (e.g. a Cys mutation).
• modification_flag (bool) – Flag whether the residue was modified (e.g. replacement of a residue with a labeled residue in case of nucleic acids).
• auth_name (str) – An author-given name for the position.
• mutated_chem_comp_id – The chemical component ID of the mutated residue.
• modified_chem_descriptor (ihm.ChemDescriptor) – The chemical descriptor of the modified residue.

class ihm.flr.Sample(entity_assembly, num_of_probes, condition, description=None, details=None, solvent_phase=None)

Sample corresponds to a measurement.

Parameters:

• entity_assembly (EntityAssembly) – The assembly of the entities that was measured.
• num_of_probes (int) – The number of probes in the sample.
• condition (SampleCondition) – The sample conditions for the Sample.
• description (str) – A description of the sample.
• details (str) – Details about the sample.
• solvent_phase – The solvent phase of the sample (liquid, vitrified, or other).

class ihm.flr.EntityAssembly(entity=None, num_copies=0)

The assembly of the entities that are in the system.

Parameters:

• entity (Entity) – The entity to add.
• num_copies – The number of copies for the entity in the assembly.

class ihm.flr.SampleCondition(details=None)

Description of the sample conditions.

Currently this is only text, but will be extended in the future.

Parameters:details (str) – Description of the sample conditions.

class ihm.flr.Experiment(instrument=None, inst_setting=None, exp_condition=None, sample=None, details=None)

The Experiment collects combinations of instrument, experimental settings and sample.

Parameters:

• instrument (Instrument) – The instrument.
• inst_setting (InstSetting) – The instrument setting.
• exp_condition (ExpCondition) – The experimental conditions.
• sample (Sample) – The sample.
• details – Details on the experiment.

add_entry(instrument, inst_setting, exp_condition, sample, details=None)

Entries to the experiment object can also be added one by one.

contains(instrument, inst_setting, exp_condition, sample)

Checks whether a combination of Instrument, InstSetting, ExpCondition, Sample is already included in the experiment object.

get_entry_by_index(index)

Returns the combination of Instrument, InstSetting, ExpCondition, Sample, and details for a given index.

class ihm.flr.Instrument(details=None)

Description of the Instrument used for the measurements.

Currently this is only text, but will be extended in the future.

Parameters:details – Description of the instrument used for the measurements.

class ihm.flr.InstSetting(details=None)

Description of the instrument settings.

Currently this is only text, but will be extended in the future.

Parameters:details (str) – Description of the instrument settings used for the measurement (e.g. laser power or size of observation volume in case of confocal measurements).

class ihm.flr.ExpCondition(details=None)

Description of the experimental conditions.

• Currently this is only text, but will be extended in the future.*

Parameters:details (str) – Description of the experimental conditions (e.g. the temperature at which the experiment was carried out).

class ihm.flr.FRETAnalysis(experiment, sample_probe_1, sample_probe_2, forster_radius, type, calibration_parameters=None, lifetime_fit_model=None, ref_measurement_group=None, method_name=None, details=None, chi_square_reduced=None, donor_only_fraction=None, dataset=None, external_file=None, software=None)

An analysis of FRET data that was performed.

Parameters:

• experiment (Experiment) – The Experiment object for this FRET analysis.
• sample_probe_1 (SampleProbeDetails) – The combination of sample and probe for the first probe.
• sample_probe_2 (SampleProbeDetails) – The combination of sample and probe for the second probe.
• forster_radius (FRETForsterRadius.) – The Förster radius object for this FRET analysis.
• type (str) – The type of the FRET analysis (intensity-based or lifetime-based).
• calibration_parameters (FRETCalibrationParameters) – The calibration parameters used for this analysis (only in case of intensity-based analyses).
• lifetime_fit_model (LifetimeFitModel) – The fit model used in case of lifetime-based analyses.
• ref_measurement_group (LifetimeRefMeasurementGroup) – The group of reference measurements in case of lifetime-based analyses.
• method_name (str) – The method used for the analysis.
• chi_square_reduced (float) – The chi-square reduced as a quality measure for the fit.
• donor_only_fraction (float) – The donor-only fraction.
• dataset (ihm.dataset.Dataset) – The dataset used.
• external_file – The external file that contains (results of) the analysis.
• software (ihm.Software) – The software used for the analysis.

class ihm.flr.LifetimeFitModel(name, description, external_file=None, citation=None)

A lifetime-fit model used for lifetime-based analysis.

Parameters:

• name (str) – The name of the fit model.
• description (str) – A description of the fit model.
• external_file – An external file that contains additional information on the fit model.
• citation (ihm.Citation) – A citation for the fit model.

class ihm.flr.RefMeasurementGroup(details=None)

A Group containing reference measurements for lifetime-based analysis.

Parameters:details (str) – Details on the Group of reference measurements.

add_ref_measurement(ref_measurement)

Add a lifetime reference measurement to a ref_measurement_group.

class ihm.flr.RefMeasurement(ref_sample_probe, details=None, list_of_lifetimes=None)

A reference measurement for lifetime-based analysis.

Parameters:

• ref_sample_probe (SampleProbeDetails) – The combination of sample and probe used for the reference measurement.
• details (str) – Details on the measurement.
• list_of_lifetimes (List of RefMeasurementLifetime) – A list of the results from the reference measurement.

add_lifetime(lifetime)

Add a lifetime to the list_of_lifetimes.

class ihm.flr.RefMeasurementLifetime(species_fraction, lifetime, species_name=None)

Lifetime for a species in a reference measurement. :param float species_fraction: The species-fraction for the

respective lifetime.

Parameters:

• lifetime (float) – The lifetime (in ns).
• species_name (str) – A name for the species.

class ihm.flr.FRETDistanceRestraintGroup

A collection of FRET distance restraints that are used together.

add_distance_restraint(distance_restraint)

Add a distance restraint to a distance_restraint_group

class ihm.flr.FRETDistanceRestraint(sample_probe_1, sample_probe_2, analysis, distance, distance_error_plus=0.0, distance_error_minus=0.0, distance_type=None, state=None, population_fraction=0.0, peak_assignment=None)

A distance restraint from FRET.

Parameters:

• sample_probe_1 (SampleProbeDetails) – The combination of sample and probe for the first probe.
• sample_probe_2 (SampleProbeDetails) – The combination of sample and probe for the second probe.
• analysis (FRETAnalysis) – The FRET analysis from which the distance restraint originated.
• distance (float) – The distance of the restraint.
• distance_error_plus (float) – The (absolute, e.g. in Angstrom) error in the upper direction, such that upper boundary = distance + distance_error_plus.
• distance_error_minus (float) – The (absolute, e.g. in Angstrom) error in the lower direction, such that lower boundary = distance + distance_error_minus.
• distance_type (str) – The type of distance (<R_DA>, <R_DA>_E, or R_mp).
• state (ihm.model.State) – The state the distance restraints is connected to. Important for multi-state models.
• population_fraction (float) – The population fraction of the state in case of multi-state models.
• peak_assignment (PeakAssignment) – The method how a peak was assigned.

class ihm.flr.FRETForsterRadius(donor_probe, acceptor_probe, forster_radius, reduced_forster_radius=None)

The FRET Förster radius between two probes.

Parameters:

• donor_probe (Probe) – The donor probe.
• acceptor_probe (Probe) – The acceptor probe.
• forster_radius (float) – The Förster radius between the two probes.
• reduced_forster_radius (float) – The reduced Förster radius between the two probes.

class ihm.flr.FRETCalibrationParameters(phi_acceptor=None, alpha=None, alpha_sd=None, gg_gr_ratio=None, beta=None, gamma=None, delta=None, a_b=None)

The calibration parameter from the FRET measurements. For the definitions of the parameters see Hellenkamp et al. Nat. Methods 2018.

Parameters:

• phi_acceptor (float) – The quantum yield of the acceptor.
• alpha (float) – The alpha parameter.
• alpha_sd (float) – The standard deviation of the alpha parameter.
• gg_gr_ratio (float) – The ratio of the green and red detection efficiencies.
• beta (float) – The beta parameter.
• gamma (float) – The gamma parameter.
• delta (float) – The delta parameter.
• a_b (float) – The fraction of bright molecules.

class ihm.flr.PeakAssignment(method_name, details=None)

The method of peak assignment in case of multiple peaks, e.g. by population.

Parameters:

• method_name (str) – The method used for peak assignment.
• details (str) – The details of the peak assignment procedure.

class ihm.flr.FRETModelQuality(model, chi_square_reduced, dataset_group, method, details=None)

The quality measure for a Model based on FRET data.

Parameters:

• model (ihm.model.Model) – The model being described.
• chi_square_reduced – The quality of the model in terms of chi_square_reduced based on the Distance restraints used for the modeling.
• dataset_group (ihm.dataset.DatasetGroup) – The group of datasets that was used for the quality estimation.
• method – The method used for judging the model quality.
• details (str) – Details on the model quality.

class ihm.flr.FRETModelDistance(restraint, model, distance, distance_deviation=None)

The distance in a model for a certain distance restraint.

Parameters:

• restraint (FRETDistanceRestraint) – The Distance restraint.
• model (ihm.model.Model) – The model the distance applies to.
• distance – The distance obtained for the distance restraint in the current model.
• distance_deviation – The deviation of the distance in the model compared to the value of the distance restraint.

class ihm.flr.FPSModeling(protocol, restraint_group, global_parameter, probe_modeling_method, details=None)

Collect the modeling parameters for different steps of FPS, e.g. Docking, Refinement, or Error estimation.

Parameters:

• protocol (ihm.protocol.Protocol) – The modeling protocol to which the FPS modeling step belongs.
• restraint_group (FRETDistanceRestraintGroup) – The restraint group used for the modeling.
• global_parameter (FPSGlobalParameters) – The global FPS parameters used.
• probe_modeling_method (str) – either “AV” or “MPP”.
• details (str) – Details on the FPS modeling.

class ihm.flr.FPSGlobalParameters(forster_radius, conversion_function_polynom_order, repetition, av_grid_rel, av_min_grid_a, av_allowed_sphere, av_search_nodes, av_e_samples_k, sim_viscosity_adjustment, sim_dt_adjustment, sim_max_iter_k, sim_max_force, sim_clash_tolerance_a, sim_reciprocal_kt, sim_clash_potential, convergence_e, convergence_k, convergence_f, convergence_t, optimized_distances='All')

The global parameters in the FPS program.

For a description of the parameters, see also the FPS manual.

Parameters:

• forster_radius (float) – The Förster radius used in the FPS program.
• conversion_function_polynom_order (int) – Order of the polynom for the conversion function between Rmp and <RDA>E.
• repetition (int) – The number of repetitions.
• av_grid_rel (float) – The AV grid spacing relative to the smallest dye or linker dimension.
• av_min_grid_a (float) – The minimal AV grid spacing in Angstrom.
• av_allowed_sphere (float) – The allowed sphere radius.
• av_search_nodes (int) – Number of neighboring positions to be scanned for clashes.
• av_e_samples_k (float) – The number of samples for calculation of E (in thousand).
• sim_viscosity_adjustment (float) – Daming rate during docking and refinement.
• sim_dt_adjustment (float) – Time step during simulation.
• sim_max_iter_k (float) – Maximal number of iterations (in thousand).
• sim_max_force (float) – Maximal force.
• sim_clash_tolerance_a (float) – Clash tolerance in Angstrom.
• sim_reciprocal_kt (float) – reciprocal kT.
• sim_clash_potential (str) – The clash potential.
• convergence_e (float) – Convergence criterion E.
• convergence_k (float) – Convergence criterion K.
• convergence_f (float) – Convergence criterion F.
• convergence_t (float) – Convergence criterion T.
• optimized_distances (str) – Which distances are optimized?

class ihm.flr.FPSAVModeling(fps_modeling, sample_probe, parameter)

FPS modeling using AV. This object connects the FPS_modeling step, the sample_probe and the respective AV parameters.

Parameters:

• fps_modeling (FPSModeling) – The FPS modeling ID.
• sample_probe (SampleProbeDetails) – The Sample probe ID.
• parameter (FPSAVParameter) – The FPS AV parameters used.

class ihm.flr.FPSAVParameter(num_linker_atoms, linker_length, linker_width, probe_radius_1, probe_radius_2=None, probe_radius_3=None)

The AV parameters used for the modeling using FPS.

Parameters:

• num_linker_atoms (int) – The number of atoms in the linker.
• linker_length (float) – The length of the linker in Angstrom.
• linker_width (float) – The width of the linker in Angstrom.
• probe_radius_1 (float) – The first radius of the probe.
• probe_radius_2 (float) – If AV3 is used, the second radius of the probe.
• probe_radius_3 (float) – If AV3 is used, the third radius of the probe.

class ihm.flr.FPSMPPModeling(fps_modeling, mpp, mpp_atom_position_group)

Maps the FPSModeling object to a mean probe position and connects it to the reference coordinate system.

Parameters:

• fps_modeling (FPSModeling) – The FPS modeling object.
• mpp (FPSMeanProbePosition) – The ID of the mean probe position.
• mpp_atom_position_group (FPSMPPAtomPositionGroup) –

class ihm.flr.FPSMeanProbePosition(sample_probe, x, y, z)

The mean probe position of an AV, which can be used instead of an AV.

It is usually not recommended to use this. Use AVs instead. The coordinates are with respect to a reference coordinate system defined by FPSMPPAtomPositionGroup.

Parameters:

• sample_probe (SampleProbeDetails) – The Sample probe.
• x (float) – The x-coordinate of the mean probe position.
• y (float) – The y-coordinate of the mean probe position.
• z (float) – The z-coordinate of the mean probe position.

class ihm.flr.FPSMPPAtomPositionGroup

A group of atom positions used to define the coordinate system of a mean probe position. Not part of the FLR dictionary.

class ihm.flr.FPSMPPAtomPosition(atom, x, y, z)

An atom used to describe the coordinate system for a mean probe position

Parameters:

• atom (ihm.Atom) – The atom being described.
• x (float) – The x-coordinate of the atom.
• y (float) – The y-coordinate of the atom.
• z (float) – The z-coordinate of the atom.

class ihm.flr.FLRData

A collection of the fluorescence data to be added to the system.

Instances of this class are generally added to flr_data.

distance_restraint_groups = None

All groups of FRET distance restraints. See FRETDistanceRestraintGroup.

fps_modeling = None

All modeling objects. See FPSAVModeling and FPSMPPModeling.

fret_model_distances = None

All distances in models for distance restraints. See FRETModelDistance.

fret_model_qualities = None

All quality measures for models based on FRET data. See FRETModelQuality.

poly_probe_conjugates = None

All conjugates of polymer residue and probe. See PolyProbeConjugate.