crisprzip.kinetics module

Simulate the kinetics of R-loop formation by a CRISPR(-like) endonuclease.

Bases: Searcher

Searcher with only protein contribution to the energy landscapes.

The BareSearcher has no built-in energy contributions from nucleic acid; its energy parameters are only due to the nonspecific interactions between the protein and the target DNA. The difference between the Searcher and BareSearcher values of the on_target_landscape and mismatch_penalties attributes are due to nucleic acid interactions as determined in the nucleic_acid module.

bind_guide_rna(protospacer: str, weight: float | Tuple[float, float] = None) → GuidedSearcher: Create a GuidedSearcher object.

classmethod from_searcher(searcher, protospacer: str, weight: float | Tuple[float, float] = None, *args, **kwargs) → BareSearcher

Generate object from default Searcher

Subtracts the nearest-neighbour hybridization energies from the definition of a ‘normal’ Searcher. Averages over the penalties due to single point mutations to find the difference with the original mm_penalties variable.

Parameters:

searcher (Searcher) – Object to be transformed.
protospacer (str) –
Full sequence of the protospacer/on-target. Can be provided in 3 formats:
- 20 nts: 5’-target-3’. All nucleotides should be specified.
- 23 nts: 5’-target-PAM-3’. The PAM should be specified or
  provided as ‘NGG’.
- 24 nts: 5’-upstream_nt-target-PAM-3’. The upstream_nt can be
  specified or provided as ‘N’.
weight (float or tuple [float], optional) – Optional weighing of the DNA opening energy and RNA duplex energy. If None (default), no weighing is applied. If float, both DNA and RNA energies are multiplied by the weight parameter. If tuple of two `float`s, the first value is used as a multiplier for the DNA opening energy, and the second is used as a multiplier for the RNA-DNA hybridization energy.
*args – Additional positional arguments, passed on to the constructor.
**kwargs – Additional keyword arguments, passed on to the constructor.

Returns:

bare_searcher – New instance of the BareSearcher class.

Return type:

BareSearcher

probe_sequence(protospacer: str, target_seq: str, weight: float | Tuple[float, float] = None) → SearcherSequenceComplex: Instantiate a SearcherSequenceComplex.

probe_target(target_mismatches: MismatchPattern) → SearcherTargetComplex: Prohibited, see BareSearcher.probe_sequence.

to_searcher(protospacer: str, weight: float | Tuple[float, float] = None) → Searcher

Turn BareSearcher into default Searcher.

Add the nearest-neighbour hybridization energies to BareSearcher energy parameters to retrieve a ‘normal’ Searcher object with effective landscape and (average) mismatch penalties.

Parameters:

protospacer (str) –
Full sequence of the protospacer/on-target. Can be provided in 3 formats:
- 20 nts: 5’-target-3’. All nucleotides should be specified.
- 23 nts: 5’-target-PAM-3’. The PAM should be specified or
  provided as ‘NGG’.
- 24 nts: 5’-upstream_nt-target-PAM-3’. The upstream_nt can be
  specified or provided as ‘N’.
weight (float or tuple [float], optional) – Optional weighing of the DNA opening energy and RNA duplex energy. If None (default), no weighing is applied. If float, both DNA and RNA energies are multiplied by the weight parameter. If tuple of two `float`s, the first value is used as a multiplier for the DNA opening energy, and the second is used as a multiplier for the RNA-DNA hybridization energy.

Returns:

searcher – New instance of the Searcher class.

Return type:

Searcher

class crisprzip.kinetics.GuidedSearcher(on_target_landscape: ndarray, mismatch_penalties: ndarray, internal_rates: dict, protospacer: str, weight: float | Tuple[float, float] = None, *args, **kwargs)

Bases: BareSearcher

BareSearcher with predefined protospacer/gRNA.

probe_sequence(target_seq: str, weight: float | Tuple[float, float] = None, *args, **kwargs) → SearcherSequenceComplex: Instantiate a SearcherSequenceComplex.

set_on_target(protospacer: str) → None: Set the on-target sequence.

to_bare_searcher() → BareSearcher: Turn GuidedSearcher into default BareSearcher.

to_searcher(*args, **kwargs) → Searcher: Turn GuidedSearcher into default Searcher.

Bases: object

A (CRISPR-associated) RNA-guided endonuclease.

guide_length

Length of the nucleic acid guide N (in bp)

Type:: int

on_target_landscape

Contains the hybridization energies of the intermediate R-loop states on an on-target, relative to the PAM energy.

Type:: numpy.ndarray, (N,)

mismatch_penalties

Contains the energetic penalties associated with a mismatch at a particular R-loop position.

Type:: numpy.ndarray, (N,)

internal_rates

Specifies the internal (=context-independent) rates in the model:

"k_off": PAM-unbinding rate in s⁻¹ (float).
"k_f": Forward rate in s⁻¹ (float).
"k_clv": Cleavage rate in s⁻¹ (float).

Type:: dict [str, float]

pam_detection

If true, the landscape includes a PAM recognition state. True by default.

Type:: bool, optional

calculate_solution_energy(k_on): Given an on-rate, returns the effective free energy of the solution state (under the assumption of detailed balance)

get_forward_rate_array(k_on: float, dead=False) → ndarray: Turn the forward rate dictionary into proper array.

probe_target(target_mismatches: MismatchPattern) → SearcherTargetComplex: Form a SearcherTargetComplex by binding a target with mismatch pattern target_mismatches.

class crisprzip.kinetics.SearcherSequenceComplex(on_target_landscape: ndarray, mismatch_penalties: ndarray, internal_rates: dict, protospacer: str, target_seq: str, weight: float | Tuple[float, float] = None, *args, **kwargs)

Bases: GuidedSearcher, SearcherTargetComplex

An RNA-guided endonuclease bound to a particular (off-)target sequence.

The SearcherSequenceComplex is like a SearcherTargetComplex, but with sequence-specific nucleic acid contributions. The most important difference is how it calculates its off_target_landscape, the sum of all energetic contributions: protein landscape, protein penalties, DNA opening energy and RNA-DNA hybridization energy.

class crisprzip.kinetics.SearcherTargetComplex(on_target_landscape: ndarray, mismatch_penalties: ndarray, internal_rates: dict, target_mismatches: MismatchPattern, *args, **kwargs)

Bases: Searcher

An RNA-guided endonuclease bound to a particular (off-)target.

target_mismatches

Positions of mismatches in the guide-target hybrid, with entries 0 (matches) and 1 (mismatches).

Type:: numpy.ndarray, (N,)

off_target_landscape

Hybridization energies of the intermediate R-loop states on the current off-target.

Type:: numpy.ndarray, (N,)

get_bound_fraction(time: float | ndarray, on_rate: float | ndarray, pam_inclusion: float = 1.0) → ndarray

Get the fraction of bound targets after a specified time.

This calculation assuming that searcher is catalytically dead/inactive.

Parameters:

time (float or numpy.ndarray, (M,)) – Times at which the master equation is evaluated.
on_rate (float or numpy.ndarray (M,)) – Rate (Hz) with which the searcher binds the target from solution.
pam_inclusion (float, optional) – Contribution of the PAM state to the bound fraction. When 1.0 (default), all PAM-bound searchers contribute to the bound fraction, when 0.0, nothing does.

Returns:

cleaved_fraction – Fraction of targets that is expected to be bound after time and with binding rates on_rate.

Return type:

float or numpy.ndarray (M,)

get_cleaved_fraction(time: float | ndarray, on_rate: float) → ndarray

Get the fraction of cleaved targets after a specified time.

Parameters:

time (float or numpy.ndarray, (M,)) – Times at which the cleaved fraction is calculated
on_rate (float) – Rate (Hz) with which the searcher binds the target from solution.

Returns:

cleaved_fraction – Fraction of targets that is expected to be cleaved at time.

Return type:

float or numpy.ndarray (M,)

get_rate_matrix(on_rate: float, dead=False) → ndarray: Set up the rate matrix describing the master equation.

solve_master_equation(initial_condition: ndarray, time: float | ndarray, on_rate: float | ndarray, dead=False, rebinding=True, mode='fast') → ndarray

Calculate the occupancy of the landscape over time.

Calculates how the occupancy of the landscape states evolves by evaluating the master equation. Absorbing states (solution and cleaved state) are explicitly incorporated. Can vary either time or on_rate but not both.

Parameters:

initial_condition (numpy.ndarray, (N+3,)) – Vector showing the initial occupancy on the hybridization landscape. Should sum to 1.
time (float or numpy.ndarray, (M,)) – Times at which the master equation is evaluated.
on_rate (float or numpy.ndarray (M,)) – Rate (Hz) with which the searcher binds the target from solution.
dead (bool, optional) – If True, cleavage rate is set to zero to simulate the catalytically inactive dCas9 variant.
rebinding (bool, optional) – If True, on-rate is left intact, if False, on-rate is set to zero and solution state becomes absorbing.
mode ({'fast', 'iterative'}, optional) – If ‘fast’ (default), uses Numba implementation to do fast matrix exponentiation. If ‘iterative’, uses the (~20x slower) iterative procedure. Whenever the fast implementation fails, falls back to the iterative.

Returns:

landscape_occupancy – Occupancy of the landscape states for specified time and on_rate.

Return type:

numpy.ndarray, (N+3,) or (N+3, M)

crisprzip.kinetics.load_landscape(parameter_set: str)

Load a parameter set describing the landscape energies for a Searcher

Parameters:: parameter_set (str) – Specifies which parameter set to load. This can be one of the default parameter sets, distributed along with crisprzip: - sequence_params: for sequence-specific kinetics - average_params: for average kinetics - average_params_legacy: for average kinetics according to Eslami-Mossalam et al. (2021) Alternatively, one can provide a path to a JSON-file that describes the parameter set. See the Notes for the requirements for the structure of such a file.
Returns:: searcher_obj – An instance of the Searcher or one of its subclasses.
Return type:: Searcher or BareSearcher

Notes

JSON files containing parameter sets for Searcher objects should contain at least the following keys: - searcher_class, corresponding to a class in crisprzip.kinetics; - param_values, with (at least) the arguments for object instantiation,

on_target_landscape

mismatch_penalties

internal_rates.