Python reference

This is an reference for the public python pinetree interface.

Model

class pinetree.Model(self: pinetree.core.Model, cell_volume: float)

Define a pinetree model.

Parameters:

cell_volume (float) – The volume, in liters, of the system being simulated.

Examples

>>> import pinetree.pinetree as pt
>>> sim = pt.Model(cell_volume=8e-16) # Approximate volume of E. coli cell
add_polymerase(self: pinetree.core.Model, name: str, footprint: int, speed: float, copy_number: int) → None

Add a polymerase to the model. There may be multiple types of polymerases in a model.

Note

Defining a polymerase with a footprint larger than that of the promoter it binds is not currently supported.

Parameters:

  • name (str) – Name of the polymerase which can be referred to in add_reaction() and add_promoter().

  • copy_number (int) – Initial number of copies of the polymerase

  • speed (int) – Speed, in base pairs per second, at which the polymerase transcribes

  • footprint (int) – Footprint, in base pairs, of the polymerase on the genome

add_polymerase_with_readthrough(self: pinetree.core.Model, name: str, footprint: int, speed: float, copy_number: int) → None

Add a polymerase with genome end readthrough to the model. This is used to simulate transcription of a circular genome.

Note

Defining a polymerase with a footprint larger than that of the promoter it binds is not currently supported.

Parameters:

  • name (str) – Name of the polymerase which can be referred to in add_reaction() and add_promoter().

  • copy_number (int) – Initial number of copies of the polymerase

  • speed (int) – Speed, in base pairs per second, at which the polymerase transcribes

  • footprint (int) – Footprint, in base pairs, of the polymerase on the genome

add_reaction(self: pinetree.core.Model, rate_constant: float, reactants: list[str], products: list[str]) → None

Define a reaction between species, which may include free ribosomes and polymerases.

Parameters:

  • rate_constant (float) – Macroscopic rate constant of the reaction. This will be converted into a stochastic mesoscopic rate constant automatically.

  • reactants (list) – List of reactants, which may be species, ribosomes, or polymerases

  • products (list) – List of products which may be species, ribosomes, or polymerases

Note

Reaction rate constants should be given as macroscopic rate constants, the same constants used in differential equation-based models. Pinetree will automatically convert these rate constants to mesoscopic constants required for a stochastic simulation.

Example

>>> coming soon
add_ribosome(self: pinetree.core.Model, footprint: int, speed: float, copy_number: int) → None

Add ribosomes to the model. There may only be a single type of ribosome.

Note

Defining ribosomes with a footprint larger than that of the promoter it binds is not currently supported.

Parameters:

  • copy_number (int) – Initial number of copies of free ribosomes

  • speed (double) – Mean speed, in base pairs per second, at which the ribosome translates. This speed will be scaled on a per site basis if translation weights are defined. (See Genome.AddWeights).

  • footprint (int) – Footprint, in base pairs, of the ribosome on RNA

add_species(self: pinetree.core.Model, name: str, copy_number: int) → None

Defines individual chemical species not specified by either add_ribosome() or add_polymerase().

Parameters:

  • name (str) – Name of chemical species which can be referred to in reactions added with add_reaction().

  • copy_number (int) – Initial number of copies of the chemical species

add_trna(self: pinetree.core.Model, codon_map: dict[str, list[str]], counts: dict[str, tuple[int, int]], rate_constants: dict[str, float]) → None

Simulate translation with dynamic tRNAs.

Note

This feature is currently experimental and may produce unexpected results.

Makes translation dependent on tRNA abundances, by modifing the underlying propensity calculation for ribosome movement (specifically, the movement propensity for each ribosome gets multiplied by the number of available charged tRNAs that correspond to its occupied codon). Rate constants for the tRNA re-charging reaction can be set for each tRNA species independently.

Adding dynamic tRNAs is likely most useful for simulating codon usage bias, or for modeling situations where tRNA pools are extremely uneven.

Warning

Simulations with tRNA dynamics turned on can be very slow.

Parameters:

  • codon_map (dict) – Specifies the codon:tRNA mapping (note that one codon can map to multple tRNAs)

  • counts (dict) – Initial charged and uncharged counts for all tRNA species, specified as tRNA_name: [<charged count>, <uncharged count>]

  • rate_constants (dict) – Charging rate constants for each tRNA species.

Examples

>>> sim = pt.Model(cell_volume=8e-16)
>>>
>>> tRNA_map = {"AAA": ["TTT", "TTG"], "TAT": ["ATA"]}
>>> tRNA_counts = {"TTT": [250, 0], "TTG": [50, 0], "ATA": [250, 0]}
>>> tRNA_rates = {"TTT": 100, "ATA": 100, "TTG": 10}
>>> sim.add_trna(tRNA_map, tRNA_counts, tRNA_rates)
register_genome(self: pinetree.core.Model, arg0: Genome) → None

Register a genome with the model.

Parameters:

genome (Genome) – a pinetree Genome object.

register_transcript(self: pinetree.core.Model, arg0: Transcript) → None

Register a genome-independent transcript with the model.

Parameters:

transcript (Transcript) – a pinetree Transcript object.

seed(self: pinetree.core.Model, arg0: int) → None

Set a seed for reproducible simulations.

Parameters:

seed (int) – a seed for the random number generator

simulate(self: pinetree.core.Model, time_limit: int, time_step: float, output: str = 'counts.tsv') → None

Run a gene expression simulation. Produces a tab separated file of protein and transcript counts at user-specified time intervals.

Parameters:

  • time_limit (int) – Simulated time, in seconds at which this simulation should stop executing reactions. Note that this simulated time and not real time. The real time that it takes for the simulation to complete depends on the number of reactions and species (genomes, transcripts, proteins, etc) in the system.

  • time_step (double) – Time interval, in seconds, that species counts are reported.

  • output (str) – Name of output file (default: counts.tsv).

Genome

class pinetree.Genome(self: pinetree.core.Genome, name: str, length: int, transcript_degradation_rate_ext: float = 0.0, rnase_speed: float = 0.0, rnase_footprint: int = 0, transcript_degradation_rate: float = 0.0)

Define a linear genome.

Parameters:

  • name (str) – Name of genome.

  • length (int) – Length of genome in base pairs.

  • transcript_degradation_rate_ext (float) – Unary binding rate constant for binding of RNases to the 5’-end of transcripts.

  • rnase_speed (flaot) – Mean speed at which RNase degrades transcript, in bases per second.

  • rnase_footprint (float) – Initial footprint of RNase on RNA.

  • transcript_degradation_rate (float) – Deprecated. Unary binding rate constant for binding of RNases to internal RNase sites. (See the add_rnase_site() method below for details.)

add_rnase_site(name, start, stop, rate)

Define an Rnase cleavage site.

Parameters:

  • name (string) – A unique identifier for this RNase cleavage site.

  • start (int) – Start position of RNase cleavage site.

  • stop (int) – Stop position of RNase cleavage site.

  • rate (float) – Binding rate constant between RNase and this cleavage site.

Note

The internal RNase binding rate constant can alternatively be supplied as an argument during Genome initialization (see Genome class description above). In this case, add_rnase_site() will only accept values for start and stop, and all rnase binding sites will be initialized with the same rate constant. Warning: This method is deprecated and may be removed in the future.

add_gene(self: pinetree.core.Genome, name: str, start: int, stop: int, rbs_start: int, rbs_stop: int, rbs_strength: float) → None

Define a gene. Genes may be defined in any order.

Note

Overlapping genes, or genes that overlap with ribosome binding sites, are supported as of release 0.3.0. If using an ealier version, specifing overlapping genes is not recommended, and could cause the program to crash.

Parameters:

  • name (str) – Name of gene. Name may be referenced by Genome.add_reaction.

  • start (int) – Start position of gene.

  • stop (int) – Stop position of gene.

  • rbs_start (int) – Start position of ribosome binding site. Generally positioned upstream of gene start.

  • rbs_stop (int) – Stop position of ribosome binding site.

  • rbs_strength (float) – Binding rate constant between ribosome and ribosome binding site.

add_mask(self: pinetree.core.Genome, start: int, interactions: list[str]) → None

Mask a portion of this Genome. This mask may correspond to a portion of the genome that has not yet entered the cell or is otherwise inaccessible. Also define which Polymerases are capabile of moving the Mask (e.g. an RNA polymerase that actively pulls the genome into the cell.)

Parameters:

  • start (int) – Start position of Mask. The Mask is assumed to extend to the end of the genome.

  • interactions (list) – List of Polymerase names capable of shifting the Mask backwards and revealing more of the genome.

add_promoter(self: pinetree.core.Genome, name: str, start: int, stop: int, interactions: dict[str, float]) → None

Define a promoter.

Parameters:

  • name (str) – Name of promoter.

  • start (int) – Start position of promoter.

  • stop (int) – Stop position of promoter.

  • interactions (dict) – Dictionary of binding rate constants for different Polymerases that this promoter interacts with.

Example

>>> genome.add_promoter(name="phi1", start=1, stop=10,
>>>                     interactions={'rnapol': 1e7})
add_sequence(self: pinetree.core.Genome, seq: str) → None

Define the nucleotide sequence for the genome being simulated.

Note

This is required for simulations with tRNAs.

Parameters:

seq (string) – The nucleotide sequence. This should be the same length as Genome.

add_terminator(self: pinetree.core.Genome, name: str, start: int, stop: int, efficiency: dict[str, float]) → None

Define a terminator.

Parameters:

  • name (str) – Name of terminator.

  • start (int) – Start position of terminator.

  • stop (int) – Stop position of terminator.

  • efficiency (dict) – Dictionary of termination efficiencies (between 0 and 1) for different Polymerases that this terminator interacts with. A value of 1.0 represents complete stop of transcription and removal of the Polymerase. A value of 0.0 means that the Polymerase will always read through the terminator and continue transcription.

Example

>>> genome.add_terminator(name="t1", start=50, stop=51,
>>>                       efficiency={'rnapol': 0.85})
add_weights(self: pinetree.core.Genome, weights: list[float]) → None

Add translation weights for this genome. Can be used to specify codon-specific translation speeds.

Note

Using weights in combination with tRNA tracking (with Model.add_trna) is not recommended. In the event that both are specified, the model will preferrentially try to use tRNA abundances to calculate ribosome speeds, essentially ignoring whatever weights is set to.

Parameters:

weights (list) – List of weights of same length as Genome. These weights are multiplied by the ribosome speed to calculate a final translation rate at every position in the genome.

Transcript

class pinetree.Transcript(self: pinetree.core.Transcript, name: str, length: int)

Define a linear transcript with one or more genes. These transcripts cannot be degraded.

Parameters:

  • name (str) – Name of transcript.

  • length (int) – Length of transcript in base pairs.

add_gene(self: pinetree.core.Transcript, name: str, start: int, stop: int, rbs_start: int, rbs_stop: int, rbs_strength: float) → None

Define a gene. Genes may be defined in any order.

Note

At this time, overlapping genes or genes that overlap with ribosome binding sites are not supported.

Parameters:

  • name (str) – Name of gene. Name may be referenced by Genome.add_reaction.

  • start (int) – Start position of gene.

  • stop (int) – Stop position of gene.

  • rbs_start (int) – Start position of ribosome binding site. Generally positioned upstream of gene start.

  • rbs_stop (int) – Stop position of ribosome binding site.

  • rbs_strength (float) – Binding rate constant between ribosome and ribosome binding site.

add_seq(self: pinetree.core.Transcript, seq: str) → None

Define a nucleotide sequence for this transcript. Note that this should be the DNA sequence corresponding to the parent gene(s) (not the transcribed RNA sequence).

Parameters:

seq (string) – The nucleotide sequence for this transcript. Should be the same length as Transcript.

add_weights(self: pinetree.core.Transcript, weights: list[float]) → None

Define position-specific translation speed weights. These may correspond, for example, codon-specific translation rates. See also Genome.add_weights.

Parameters:

weights (list) – List of weights of same length as Transcript. These weights are multiplied by the ribosome speed to calculate a final translation rate at every position in the genome.