Merge branch 'main' into fix/vcf_context_managers

docs/overview.md

@@ -47,39 +47,7 @@ using the [`OffTargetDetector`][prymer.offtarget.offtarget_detector.OffTargetDet
 
 The remaining primers may then be used with the 
 [`build_primer_pairs()`][prymer.api.picking.build_primer_pairs] method to build primer pairs
-from all combinations of the left and right primers.
-The produced primer pairs are scored in a manner similar to Primer3 using the [`score()`][prymer.api.picking.score] method.
-The [`FilterParams`][prymer.api.picking.FilteringParams] class is used to provide parameters for scoring.
-
-Next, the [`pick_top_primer_pairs()`][prymer.api.picking.pick_top_primer_pairs] method is used to select up to
-a maximum number of primer pairs.  The primer pairs are selected in the order of lowest penalty (highest score).  As
-part of this process, each primer pair must:
-
-1. Have an amplicon in the desired size range (see [`is_acceptable_primer_pair`][prymer.api.picking.is_acceptable_primer_pair]).
-2. Have an amplicon melting temperature in the desired range (see [`is_acceptable_primer_pair`][prymer.api.picking.is_acceptable_primer_pair]).
-3. Not have too many off-targets (see [`OffTargetDetector.check_one()`][prymer.offtarget.offtarget_detector.OffTargetDetector.check_one]).
-4. Not have primer pairs that overlap too much (see [`check_primer_overlap()`][prymer.api.picking.check_primer_overlap]).
-5. Not form a dimer with a melting temperature above a specified threshold (see the [`max_dimer_tm` attribute in `FilterParams`][prymer.api.picking.FilteringParams]).
-
-Checking for dimers may be performed using the [`NtThermoAlign`][prymer.ntthal.NtThermoAlign] command line executable,
-and can be passed to [`pick_top_primer_pairs()`][prymer.api.picking.pick_top_primer_pairs] as follows:
-
-```python
-from prymer.ntthal import NtThermoAlign
-from prymer.api.picking import FilteringParams, pick_top_primer_pairs
-params = FilteringParams(...)
-dimer_checker = NtThermoAlign()
-pick_top_primer_pairs(
-    is_dimer_tm_ok=lambda s1, s2: (
-        dimer_checker.duplex_tm(s1=s1, s2=s2) <= params.max_dimer_tm
-    ),
-    ...
-)
-
-```
-
-For convenience, the [`build_and_pick_primer_pairs()`][prymer.api.picking.build_and_pick_primer_pairs] method combines
-both the [`build_primer_pairs()`][prymer.api.picking.build_primer_pairs] and 
-[`pick_top_primer_pairs()`][prymer.api.picking.pick_top_primer_pairs] methods in single invocation.
-
-The resulting primer pairs may be further examined.
+from all combinations of the left and right primers that are within acceptable amplicon size and tm ranges.
+Optionally, if a `max_heterodimer_tm` is provided, primer pairs will be screened to ensure that the left and right
+primers do not dimerize with a Tm greater than the one provided.
+The produced primer pairs are scored in a manner similar to Primer3 using the [`score()`][prymer.api.picking.score] method.

prymer/api/__init__.py

@@ -3,10 +3,7 @@
 from prymer.api.minoptmax import MinOptMax
 from prymer.api.oligo import Oligo
 from prymer.api.oligo_like import OligoLike
-from prymer.api.picking import FilteringParams
-from prymer.api.picking import build_and_pick_primer_pairs
 from prymer.api.picking import build_primer_pairs
-from prymer.api.picking import pick_top_primer_pairs
 from prymer.api.primer_pair import PrimerPair
 from prymer.api.span import BedLikeCoords
 from prymer.api.span import Span
@@ -23,10 +20,7 @@
     "ClusteredIntervals",
     "cluster_intervals",
     "MinOptMax",
-    "FilteringParams",
     "build_primer_pairs",
-    "pick_top_primer_pairs",
-    "build_and_pick_primer_pairs",
     "OligoLike",
     "Oligo",
     "PrimerPair",

prymer/api/oligo.py

@@ -83,24 +83,49 @@
 class Oligo(OligoLike, Metric["Oligo"]):
     """Stores the properties of the designed oligo.
 
-    Oligos can include both single primer and internal probe designs. The penalty score of the
-    design is emitted by Primer3 and controlled by the corresponding design parameters.
-    The penalty for a primer is set by the combination of `PrimerAndAmpliconParameters` and
-    `PrimerWeights`, whereas a probe penalty is set by `ProbeParameters` and `ProbeWeights`.
+    Oligos can include both single primer and internal probe designs. Primer3 emits information
+    about the specific properties of a primer and/or probe, including the base sequence,
+    melting temperature (tm), and score.
+
+    The penalty score of the design is emitted by Primer3 and controlled by the corresponding
+    design parameters. The penalty for a primer is set by the combination of
+    `PrimerAndAmpliconParameters` and `PrimerWeights`.
+    A probe penalty is set by `ProbeParameters` and `ProbeWeights`.
+
+    The span of an `Oligo` object represents the mapping of the oligo
+    to the genome. `Oligo` objects can optionally have a `tail` sequence to prepend to the 5' end
+    of the primer or probe, as well as a `name` for downstream record keeping.
+
+    `Oligo` objects can also store thermodynamic characteristics of primer and/or probe
+    design. These include the calculated melting temperatures of the most stable hairpin structure,
+    self-, and end- complementarity. These values can be emitted by Primer3.
+
+    These thermodynamic characteristics are meant to quantify how likely it is the primer or probe
+    will bind to itself (e.g., instead of the target DNA). A melting temperature close to or greater
+    than the intended melting temperature for target binding indicates the primer or probe is
+    likely to form stable hairpins or dimers, leading to reduced efficiency of the reaction.
 
     Attributes:
         tm: the calculated melting temperature of the oligo
         penalty: the penalty or score for the oligo
         span: the mapping of the primer to the genome
+        name: an optional name to use for the primer
+        tm_homodimer: calculated melting temperature that represents
+            the tendency of an oligo to bind to itself (self-complementarity)
+        tm_3p_anchored_homodimer: calculated melting temperature that represents
+            the tendency of a primer to bind to the 3'-END of an identical primer
+        tm_secondary_structure: calculated melting temperature of the oligo hairpin structure
         bases: the base sequence of the oligo (excluding any tail)
         tail: an optional tail sequence to put on the 5' end of the primer
-        name: an optional name to use for the primer
 
     """
 
     tm: float
     penalty: float
     span: Span
+    tm_homodimer: Optional[float] = None
+    tm_3p_anchored_homodimer: Optional[float] = None
+    tm_secondary_structure: Optional[float] = None
     bases: Optional[str] = None
     tail: Optional[str] = None