API reference¶

This module provides the ForceInference class, which uses the Rouse model to infer forces in chromatin pulling experiments.

Units: once calibrated (using MSD data), the code works with physical units. We use s, μm, pN.

class rousepull.ForceInference(t, x=None, Gamma=None, tR=None, alpha=0.5, shift=1)¶

Inference for a single trajectory x(t).

Parameters:

t ((N,) array) – sampling times in seconds, i.e. the times associated with the observations x.
x ((N, ...) array) – trajectory in μm. x[0] should be the equilibrium position of the locus (i.e. the math assumes that the locus is in equilibrium at the start of the trajectory). x can have multiple dimensions; the first one is assumed to be time and consequently should match t.
Gamma (float) – MSD prefactor, used for calibration. Should have units μm^2/s^alpha.
tR (Rouse time of a finite tether on one side. If None (default), both) – tethers will be infinite. Mathematically this of course simply means tR = inf. So far, a finite tether is implemented only for alpha = 0.5.
alpha (float in (0, 1)) – Scaling exponent of the MSD, i.e. this controls viscoelasticity of the medium. So far this is implemented by tweaking the formulas, so no guarantees on correctness for any alpha != 0.5. That being said, doesn’t look too bad.
s (float) – relative shift of the force switches (see Notes).

t, x

like input

Type:: array

M, Minv

the constitutive matrix M and its inverse, such that x = M.f and f = Minv.x.

Type:: (N, N) array

fpoly¶

the inferred force profile (after running populate())

Type:: (N,) array

tf¶

precise positions of the switches in the force profile, including beginning and end points.

Type:: (N+1,) array

xf¶

interpolated displacement at tf. Mostly used to calculate vAt.

Type:: (N+1,) array

vAt¶

estimate for locus velocity at the observation times. This is estimated as the velocity over the corresponding constant-force time window and thus depends on s: vAt = Δxf / Δtf.

Type:: (N,) array

Notes

The inference should always give f[0] = 0, by construction.

We assume that x(t) is sampled at discrete times t[i], giving x[i] := x(t[i]), such that the locus is in equilibrium / at rest at x[0] before the experiment. The force profile is assumed to be piecewise constant, such that f[i] is the force acting over the half-open interval ( t[i-1], t[i] ].

Generalizing the logic above, we allow for a shift s of the force profile relative to the observation times, such that the switches in the force do not necessarily have to coincide with the observation times. This parameter is mostly intended to check that the ultimate conclusions drawn from the inferred forces do not depend on where exactly the switches are assumed to be (in which case the assumption of a piecewise constant force would be questionable in the first place). An overview over the different discretizations then looks as follows:

t:        |     |     |     |     |     |
x:        0     1     2     3     4     5
f:     __0__|--1--|--2--|--3--|__4__|--5--
shift:      '-s-'

See also the Quickstart example for an illustration with (dummy) data.

updateM(tR=None)¶

Calculate the matrix M and its inverse.

The expected trajectory x[i] given a force profile f[i] is given by x = M.f, i.e. we can calculate the force from the observed trajectory as f = M\x.

Parameters:: tR (float, optional) – finite tether Rouse time

populate(x=None, returnf=False)¶

Populate this object with inference results.

This is basically a wrapper for self._infer, just that it also calculates some other stuff that could be useful, like velocities.

Parameters:

x ((N,) array, optional) – the trajectory to use, if not specified in self.x
returnf (bool, optional) – whether to return the output or just store internally (in self.fpoly).

Returns:

f ((N,) array) – inferred force profile, in pN; same as self.fpoly and only returned if returnf == True.

difMagnetic(fmagnetic)¶

Calculate the “unexplained force” as self.funex.

Parameters:: fmagnetic ((N,) array) – total magnetic pull force

covTrajectory()¶

Covariance matrix for the trajectory, for fixed x[0].

This is given by

S(t, t') = 1/2*(MSD(t) + MSD(t') - MSD(|Δt|)) .

Returns:: S ((N, N) array)

covForce()¶

Covariance matrix for the force.

From covariance of the trajectory, this is simple Gaussian error propagation:

S_force = M^{-1} @ S @ M^{-T} .

Returns:: S_force ((N, N) array)

computeFdrag(density, mode=0, ix=1, returnFdrag=False, returnTrajectories=False)¶

Calculate additional force exerted on the locus due to dragging.

Parameters:

density ((N,) array) – the local density at the position of the locus. This is basically just a local proportionality factor.
mode (int) –
specifies the model to use. Implemented so far are

0 = sticky chromatin

1 = two-sided glove

2 = one-sided glove
ix (int or other index, optional) – if self.x is multidimensional, this should be an index such that x[:, ix] gives a 1D trace to work with.
returnFdrag (bool, optional) – whether to return the dragging force or just store it internally in self.fdrag.
returnTrajectories (bool, optional) – whether to return the trajectories of the N virtual particles

Returns:

Fdrag ((N,) array) – the dragging force, in pN. Only returned if returnFdrag == True.