FRET

The FRET submodule provides all the functionality to calculate distance and FRET distributions between a donor and an acceptor ACV cloud.

fretraj.fret.FRET_DA(acv1, acv2, R_DA=None, R0=54, n_dist=1000000, verbose=False)

Calculate the FRET efficiencies E for each donor acceptor distance

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• R_DA (ndarray, default=None) – ndarray of length n_dist containing distances between acv1 and acv2 (if None calculate on the fly)

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

ndarray – ndarray of shape 1 x n_dist or 2 x n_dist (if weights are included) containing FRET efficiencies between acv1 and acv2

Notes

The transfer efficiency E is given by

\[E = \frac{R_0^6}{R_0^6+R_\text{DA}^6}\]

fretraj.fret.R_DAE_to_Rmp(mean_R_DA_E)

Conversion function for <R_DA,E> to R_mp derived in Kalinin, Nat. Methods (2012)

Parameters:

mean_R_DA_E (float) – FRET averaged donor acceptor distance

Returns:

float – distance between the mean dye positions

Notes

The conversion function between \(\langle R_\text{DA}\rangle_E\) and \(R_\text{mp}\) is a third-order polynomial:

\[R_\text{mp} = 1.109\cdot 10^{-5}\cdot\langle R_\text{DA}\rangle_E^3 - 7.286\cdot 10^{-3}\cdot \langle R_\text{DA}\rangle_E^2 + 1.979\cdot\langle R_\text{DA}\rangle_E - 34.345\]

References

[3]

Kalinin, S. et al. “A toolkit and benchmark study for FRET-restrained high-precision structural modeling”, Nat. Methods 9, 1218–1225 (2012).

fretraj.fret.dist_attach(attach1_xyz, attach2_xyz)

Calculate the distance between the attachment sites

Parameters:

attach1_xyz, attach2_xyz (ndarray) – one-dimensional array of x-,y-,z-coordinates of the attachment points

Returns:

float – distance between the attachment sites

fretraj.fret.dist_mp(acv1, acv2)

Compute the distance between mean dye positions R_MP of two accessible contact volumes

Parameters:

acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

Returns:

float – distance between the mean dye positions of acv1 and acv2

fretraj.fret.dists_DA(acv1, acv2, n_dist=1000000, return_weights=True)

Compute a randomly subsampled donor-acceptor distance distribution for the two accessible volume clouds

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• n_dist (int, default=10E6) – number of distances to calculate

• return_weights (bool, default=True) – additional vector with weights

Returns:

ndarray – ndarray of shape 1 x n_dist or 2 x n_dist (if weights are included) containing distances between acv1 and acv2

fretraj.fret.dists_DA_ll(acv1, acv2, n_dist=1000000, return_weights=True)

Compute a randomly subsampled donor-acceptor distance distribution for the two accessible volume clouds

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• n_dist (int, default=10E6) – number of distances to calculate

• include_weights (bool, default=True) – additional vector with weights

Returns:

ndarray – ndarray of shape 1 x n_dist or 2 x n_dist (if weights are included) containing distances between acv1 and acv2

fretraj.fret.mean_FRET_DA(acv1, acv2, E_DA=None, R_DA=None, R0=54, n_dist=1000000, verbose=False)

Calculate the average FRET efficiency <E> between donor and acceptor cloud

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• E_DA (ndarray, default=None) – ndarray of length n_dist containing FRET efficiencies between acv1 and acv2 (if None calculate on the fly)

• R_DA (ndarray, default=None) – ndarray of length n_dist containing distances between acv1 and acv2 (if None calculate on the fly)

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

float – average FRET efficiency between donor and acceptor cloud

fretraj.fret.mean_FRET_DA_ll(acv1, acv2, R0=54, n_dist=1000000)

Calculate the average FRET efficiency <E> between donor and acceptor cloud using LabelLib

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

Returns:

float – average FRET efficiency between donor and acceptor cloud

fretraj.fret.mean_dist_DA(acv1, acv2, R_DA=None, n_dist=1000000, verbose=False)

Calculate the average donor-acceptor distance <R_DA> between donor and acceptor

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• R_DA (ndarray) – ndarray of length n_dist containing distances between acv1 and acv2

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool)

Returns:

float – average distance between donor and acceptor

fretraj.fret.mean_dist_DA_fromFRET(acv1, acv2, mean_E_DA=None, E_DA=None, R_DA=None, R0=54, n_dist=1000000, verbose=False)

Calculate the FRET averaged donor acceptor distance <R_DA>_E

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• mean_E_DA (float, default=None) – average FRET efficiency between donor and acceptor cloud (if None calculate on the fly)

• E_DA (ndarray, default=None) – ndarray of length n_dist containing FRET efficiencies between acv1 and acv2 (if None calculate on the fly)

• R_DA (ndarray, default=None) – ndarray of length n_dist containing distances between acv1 and acv2 (if None calculate on the fly)

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

float – FRET averaged donor acceptor distance

Examples

with known \(\langle E_\text{DA}\rangle\) (fastest)

>>> mean_dist_DA_fromFRET(acv1, acv2, mean_E_DA=mymean_E_DA)

with known \(E_\text{DA}\), i.e. \(\langle E_\text{DA}\rangle\) is calculated on-the-fly

>>> mean_dist_DA_fromFRET(acv1, acv2, E_DA=myE_DA)

with known \(R_\text{DA}\), i.e. \(E_\text{DA}\) and \(\langle E_\text{DA}\rangle\) are calculated on-the-fly

>>> mean_dist_DA_fromFRET(acv1, acv2, R_DA=myR_DA)

fretraj.fret.mean_dist_DA_ll(acv1, acv2, n_dist=1000000)

Calculate the average donor-acceptor distance <R_DA> between acv1 and acv2 using LabelLib

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• n_dist (int, default=10E6) – number of distances to calculate

Returns:

float – average distance between donor and acceptor

fretraj.fret.std_FRET_DA(acv1, acv2, E_DA=None, R_DA=None, R0=54, n_dist=1000000, verbose=False)

Calculate the standard deviation of the FRET efficiencies sigma_E

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• E_DA (ndarray, default=None) – ndarray of length n_dist containing FRET efficiencies between acv1 and acv2 (if None calculate on the fly)

• R_DA (ndarray, default=None) – ndarray of length n_dist containing distances between acv1 and acv2 (if None calculate on the fly)

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

float – standard deviation of the FRET efficiencies

fretraj.fret.std_dist_DA(acv1, acv2, R_DA=None, n_dist=1000000, verbose=False)

Calculate the standard deviation of the donor acceptor distances sigma_R_DA

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• R_DA (ndarray) – ndarray of length n_dist containing distances between acv1 and acv2

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

float – standard deviation of donor acceptor distances

fretraj.fret.std_dist_DA_fromFRET(acv1, acv2, mean_E_DA=None, sigma_E_DA=None, E_DA=None, R_DA=None, R0=54, n_dist=1000000, verbose=False)

Calculate the standard deviation of the FRET averaged donor acceptor distances sigma_R_DA_E by error propagation

Parameters:

• acv1, acv2 (fretraj.cloud.ACV) – donor and acceptor ACVs

• mean_E_DA (float, default=None) – average FRET efficiency between donor and acceptor cloud (if None calculate on the fly)

• sigma_E_DA (float, default=None) – standard deviation of the FRET efficiencies

• E_DA (ndarray, default=None) – ndarray of length n_dist containing FRET efficiencies between acv1 and acv2 (if None calculate on the fly)

• R_DA (ndarray, default=None) – ndarray of length n_dist containing distances between acv1 and acv2 (if None calculate on the fly)

• R0 (float, default=54) – Förster radius in Angstrom

• n_dist (int, default=10E6) – number of distances to calculate

• verbose (bool, default=False) – be verbose about calculation steps

Returns:

float – standard deviation of the FRET averaged donor acceptor distances