utils

Utils submodule.

gaussfilter_friction(friction, pos, sigma, mode='nearest')

Smoothes friction with a gaussian kernel and 'nearest' borders.

Parameters:

• friction (1d np.array) –

  Array that contains the friction.

• pos (1d np.array) –

  Positions corresponding to entries in friction array in nm.

• sigma (float) –

  Standard deviation of gaussian kernel in nm.

• mode (Str, default: 'nearest' ) –

  options: ‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’ The mode parameter determines how the input array is extended beyond its boundaries. Default is ‘reflect’. Behavior for each option see scipy.ndimage.gaussian_filter1d

Returns:

• 1d np.array –

  Smoothed friction.

Source code in src/dcTMD/utils/_smoothing.py

@beartype
def gaussfilter_friction(
    friction: Float1DArray,
    pos: Float1DArray,
    sigma: Float,
    mode: Str = 'nearest',
) -> Float1DArray:
    """
    Smoothes friction with a gaussian kernel and 'nearest' borders.

    Parameters
    ----------
    friction : 1d np.array
        Array that contains the friction.
    pos : 1d np.array
        Positions corresponding to entries in friction array in nm.
    sigma : float
        Standard deviation of gaussian kernel in nm.
    mode:
        options: ‘reflect’, ‘constant’, ‘nearest’, ‘mirror’, ‘wrap’
        The mode parameter determines how the input array is
        extended beyond its boundaries. Default is ‘reflect’.
        Behavior for each option see scipy.ndimage.gaussian_filter1d

    Returns
    -------
    1d np.array
        Smoothed friction.
    """
    from scipy.ndimage import gaussian_filter1d
    delta_x = pos[1] - pos[0]
    blur = np.ceil(sigma / delta_x).astype(int)
    return gaussian_filter1d(friction, sigma=blur, mode=mode)

bootstrapping(estimator, func, descriptor, verbose=False)

Perform a bootstrapping error analysis.

The bootstrapping error analysis is performed using a given function func by drawing random work trajectories from the estimator's WorkSet instance with replacement. The quantity of interest is then calculated for the new sample and stored in quantity_resampled. This process is repeated n_resamples times, which is a key of the descriptor dictionary. The random number generator can be fed a seed, the second key of the descriptor which is optional. Thirdly, a mode must be in the descriptor, which can either be the string 'std' for a standard distribution of the resampled quantitity or a number in the interval [0, 1) which yields confidence intervals instead.

Parameters:

• estimator –

  Instance of a WorkEstimator.

• func (Callable) –

  Function which takes a WorkSet instance as single argument and returns the the quantitity for which the bootstrapping error analysis is performed.

• descriptor (dict) –

  Dictionary of the estimator which provides mode, n_resampled and seed as keys.

• verbose (Optional[bool], default: False ) –

  Enables verbose mode.

Returns:

• s_quantity –

  Estimated error for the quantity returned by func.

• quantity_resampled –

  Quantities returned by func for the resampled work trajectories.

Source code in src/dcTMD/utils/_bootstrapping.py

@beartype
def bootstrapping(
    estimator,
    func: Callable,
    descriptor: dict,
    verbose: Optional[bool] = False,
):
    """
    Perform a bootstrapping error analysis.

    The bootstrapping error analysis is performed using a given function `func`
    by drawing random work trajectories from the `estimator`'s WorkSet
    instance with replacement. The quantity of interest is then calculated for
    the new sample and stored in `quantity_resampled`. This process is repeated
    `n_resamples` times, which is a key of the `descriptor` dictionary. The
    random number generator can be fed a `seed`, the second key of the
    `descriptor` which is optional. Thirdly, a `mode` must be in the
    `descriptor`, which can either be the string 'std' for a standard
    distribution of the resampled quantitity or a number in the interval [0, 1)
    which yields confidence intervals instead.

    Parameters
    ----------
    estimator :
        Instance of a WorkEstimator.
    func :
        Function which takes a WorkSet instance as single argument and returns
        the the quantitity for which the bootstrapping error analysis is
        performed.
    descriptor :
        Dictionary of the estimator which provides `mode`, `n_resampled`
        and `seed` as keys.
    verbose :
        Enables verbose mode.

    Returns
    -------
    s_quantity :
        Estimated error for the quantity returned by `func`.
    quantity_resampled :
        Quantities returned by `func` for the resampled work trajectories.
    """
    import tqdm

    # Set up an array in which the resampled quantities are saved.
    # How many quantities are returned by func? If a tuple is returned,
    # use its length. Else, only one quantitity is returned, thus len_of_return
    # is 1.
    n_traj, length_data = np.shape(estimator.work_set.work_)
    probe_return = func(estimator.work_set.work_)
    if isinstance(probe_return, tuple):
        len_of_return = len(probe_return)
    else:
        len_of_return = 1
    quantity_resampled = np.empty((
        descriptor['n_resamples'],
        len_of_return,
        length_data,
    ))
    # Initialize RNG.
    rng = np.random.default_rng(descriptor['seed'])
    desc = 'Bootstrapping progress'
    for idx in tqdm.tqdm(range(descriptor['n_resamples']), desc=desc):
        # Draw random work time traces
        random_indices = rng.integers(0, n_traj, n_traj)
        work_set_resampled = estimator.work_set.work_[random_indices]

        # Calculate and save the relevant statistic
        quantity = func(work_set_resampled)
        quantity_resampled[idx] = quantity
    # There are now boostrapped quantities in the '_resampled' variables.
    # We are interested in the element-wise distributions and thus
    # calculate (1) the standard distribution of the resampled quantity
    # at all points or (2) confidence intervals.
    if verbose:
        print('Finished resampling, starting reduction.')
    s_quantity = _bootstrap_reducer(
        descriptor,
        quantity_resampled,
    )
    s_quantity = np.array(s_quantity)
    # The distributions of the '_resampled' variables must be inspected
    # and are thus also returned.
    return s_quantity, quantity_resampled