storing

Classes that store constraint force data as work or force time traces.

The resulting force or work sets are needed for further analysis.

WorkSet(velocity, resolution=1, verbose=False)

Bases: TransformerMixin, BaseEstimator

Class for managing constraint work data.

Parameters:

• velocity (Float) –

  Pulling velocity in nm/ps.

• resolution (Int, default: 1 ) –

  Striding to reduce work time trace.

• verbose (bool, default: False ) –

  Enables verbose mode.

Attributes:

• work_ –

  Constraint work time traces, in kJ/mol.

• names_ –

  Constraint force file names corresponding to work time traces.

• time_ –

  Time trace corresponding to the work, in ps.

• position_ –

  Positions time trace, product of time trace and velocity, in nm.

Examples:

>>> # Load some file names listed in 'filenames'
>>> import numpy as np
>>> from dcTMD.storing import WorkSet
>>> work_set = WorkSet(velocity=0.001, resolution=1)
>>> work_set.fit(filenames)  # noqa: F821
Loading & integrating force files: 100%|████| X/X [XX:XX<00:00,  X.XX/it]
WorkSet(velocity=0.001)
>>> work_set.work_.shape
(N_trajectories_, len(time_))

>>> # Reduce work by selecting some trajectories via their indices,
>>> # for example the first three, and receive a new WorkSet instance
>>> indices = np.array([0, 1, 2])
>>> reduced_set = work_set.reduce(indices)
>>> reduced_set.work_.shape
(3, len(time_))

Initialize WorkSet class.

Source code in src/dcTMD/storing.py

@beartype
def __init__(
    self,
    velocity: Float,
    resolution: Int = 1,
    verbose: bool = False,
) -> None:
    """Initialize WorkSet class."""
    self.velocity = velocity
    self.resolution = resolution
    self.verbose = verbose

fit(X, y=None)

Load constraint force files and calculate work time traces.

Parameters:

• X (ArrayLikeStr) –

  File names of constraint force files to be read in and integrated.

• y (Optional[ndarray], default: None ) –

  Not used, present for scikit API consistency by convention.

Returns:

• self –

  Fitted estimator.

Source code in src/dcTMD/storing.py

@beartype
def fit(
    self,
    X: ArrayLikeStr,  # noqa: WPS111 N803
    y: Optional[np.ndarray] = None,  # noqa: WPS111
):
    """
    Load constraint force files and calculate work time traces.

    Parameters
    ----------
    X :
        File names of constraint force files to be read in and integrated.
    y :
        Not used, present for scikit API consistency by convention.

    Returns
    -------
    self:
        Fitted estimator.
    """
    self.X = X  # noqa: WPS111 N803
    # read a test file for the time trace
    _get_time_from_testfile(self)
    # fill arrays with data
    self._fill_work()
    return self

transform(X, y=None)

Return work set.

Source code in src/dcTMD/storing.py

@beartype
def transform(self, X, y=None) -> Float2DArray:  # noqa: WPS111 N803
    """Return work set."""
    return self.work_

reduce(indices)

Reduce work set to a chosen subset and return new instance.

Parameters:

• indices (Index1DArray) –

  Indices corresponding to the work trajectories that are kept in the work set.

Returns:

• self –

  Instance of WorkSet.

Source code in src/dcTMD/storing.py

@beartype
def reduce(self, indices: Index1DArray):
    """
    Reduce work set to a chosen subset and return new instance.

    Parameters
    ----------
    indices :
        Indices corresponding to the work trajectories that are kept in the
        work set.

    Returns
    -------
    self :
        Instance of WorkSet.
    """
    import copy
    reduced_work_set = copy.deepcopy(self)
    reduced_work_set.work_ = reduced_work_set.work_[indices]
    reduced_work_set.names_ = reduced_work_set.names_[indices]
    return reduced_work_set

ForceSet(velocity, resolution=1, verbose=False)

Bases: TransformerMixin, BaseEstimator

Class for managing constraint force data.

Parameters:

• velocity (Float) –

  Pulling velocity in nm/ps.

• resolution (Int, default: 1 ) –

  Striding to reduce work time trace. This parameter is only added for compatibility with WorkSet

• verbose (bool, default: False ) –

  Enables verbose mode.

Attributes:

• force_ –

  Constraint force time traces, in kJ/mol.

• names_ –

  Constraint force file names corresponding to force time traces.

• time_ –

  Time trace corresponding to the force, in ps.

• position_ –

  Positions time trace, product of time trace and velocity, in nm.

Examples:

>>> # Load some file names listed in 'filenames'
>>> import numpy as np  # noqa: F401
>>> from dcTMD.storing import ForceSet
>>> filenames = np.loadtxt('my_filenames.txt')
>>> force_set = ForceSet(velocity=0.001, resolution=1)
>>> force_set.fit(filenames)
Loading force files: 100%|████| X/X [XX:XX<00:00,  X.XX/it]
ForceSet(velocity=0.001)
>>> force_set.work_.shape
(N_trajectories_, len(time_))

Initialize WorkSet class.

Source code in src/dcTMD/storing.py

@beartype
def __init__(
    self,
    velocity: Float,
    resolution: Int = 1,
    verbose: bool = False,
) -> None:
    """Initialize WorkSet class."""
    self.velocity = velocity
    self.resolution = resolution
    self.verbose = verbose

fit(X, y=None)

Load constraint force files.

Parameters:

• X (ArrayLikeStr) –

  File names of constraint force files to be read in.

• y (Optional[ndarray], default: None ) –

  Not used, present for scikit API consistency by convention.

Returns:

• self –

  Fitted estimator.

Source code in src/dcTMD/storing.py

@beartype
def fit(
    self,
    X: ArrayLikeStr,  # noqa: WPS111 N803
    y: Optional[np.ndarray] = None,  # noqa: WPS111
):
    """
    Load constraint force files.

    Parameters
    ----------
    X :
        File names of constraint force files to be read in.
    y :
        Not used, present for scikit API consistency by convention.

    Returns
    -------
    self:
        Fitted estimator.
    """
    self.X = X  # noqa: WPS111 N803
    # read a test file for the time trace
    _get_time_from_testfile(self)
    # fill arrays with data
    self._fill_force()
    self.integrate()
    return self

transform(X, y=None)

Return force set.

Source code in src/dcTMD/storing.py

@beartype
def transform(self, X, y=None) -> Float2DArray:  # noqa: WPS111 N803
    """Return force set."""
    return self.force_

integrate()

Integrate forces.

Source code in src/dcTMD/storing.py

@beartype
def integrate(self) -> None:
    """Integrate forces."""
    self.work_ = _integrate_force(self, self.force_)[::self.resolution]

save(filename, classobject)

Save a class object: a data handler or an estimator.

Parameters:

• filename (Str) –

  File name to which classobject is saved.

• classobject –

  Instance of the data handler, i.e. a WorkSet or ForceSet instance, or of an estimator, i.e. a WorkEstimator or ForceEstimator instance.

Examples:

>>> # Save Estimators and data handlers. Here: WorkSet.
>>> # Save a WorkSet instance named work_set and load it again:
>>> from dcTMD.storing import save, load
>>> save(work_set, 'my_workset.joblib')  # noqa: F821
>>> my_workset = load('my_workset.joblib')

Source code in src/dcTMD/storing.py

@beartype
def save(
    filename: Str,
    classobject,
) -> None:
    """
    Save a class object: a data handler or an estimator.

    Parameters
    ----------
    filename :
        File name to which classobject is saved.
    classobject :
        Instance of the data handler, i.e. a WorkSet or ForceSet instance, or
        of an estimator, i.e. a WorkEstimator or ForceEstimator instance.

    Examples
    --------
    >>> # Save Estimators and data handlers. Here: WorkSet.
    >>> # Save a WorkSet instance named work_set and load it again:
    >>> from dcTMD.storing import save, load
    >>> save(work_set, 'my_workset.joblib')  # noqa: F821
    >>> my_workset = load('my_workset.joblib')
    """
    joblib.dump(classobject, filename)

load(filename)

Load a data handler or an estimator.

Parameters:

• filename (Str) –

  Name of the file containing the data handler.

Returns:

• handler ( Any ) –

  Loaded class object.

Examples:

>>> # Loads estimators and data handlers. Here: WorkSet.
>>> # Save a WorkSet instance named work_set and load it again:
>>> from dcTMD.storing import save, load
>>> save(work_set, 'my_workset.joblib')  # noqa: F821
>>> my_workset = load('my_workset.joblib')

Source code in src/dcTMD/storing.py

@beartype
def load(
    filename: Str,
) -> Any:
    """
    Load a data handler or an estimator.

    Parameters
    ----------
    filename :
        Name of the file containing the data handler.

    Returns
    -------
    handler:
        Loaded class object.

    Examples
    --------
    >>> # Loads estimators and data handlers. Here: WorkSet.
    >>> # Save a WorkSet instance named work_set and load it again:
    >>> from dcTMD.storing import save, load
    >>> save(work_set, 'my_workset.joblib')  # noqa: F821
    >>> my_workset = load('my_workset.joblib')
    """
    return joblib.load(filename)