Document assembly assumptions: exact-match and monotonic coverage (#158)

Add module docstrings to assembly.py and variant_sequence.py documenting
that the assembly requires exact sequence matches (breaks with long-read
error rates) and that coverage trimming assumes monotonic decay (breaks
with splice-junction reads).

Add a note to README's Sequencing Recommendations section.

Fixes #150

Author: iskandr

README.md

@@ -389,3 +389,11 @@ considers reads that overlap a variant. With 100bp reads you will be able to ass
 at most 199bp of sequence around a somatic single nucleotide variant, and consequently 
 only be to determine 66 amino acids from the protein sequence. If you disable the cDNA 
 assembly algorithm then a 100bp read will only be able to determine 33 amino acids.
+
+**Note on long-read and error-prone data:** Isovar's cDNA assembly algorithm requires 
+exact sequence matches when detecting overlaps between reads. This is well-suited for 
+Illumina short reads (~0.1% error rate) but will produce fragmented or incomplete 
+assemblies with long-read technologies (PacBio, Oxford Nanopore) that have higher 
+indel error rates. The coverage-trimming step also assumes that read coverage decreases 
+monotonically away from the variant locus, which may not hold for reads spanning 
+splice junctions.

isovar/__init__.py

@@ -10,7 +10,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "1.4.14"
+__version__ = "1.4.15"
 
 
 from .allele_read import AlleleRead

isovar/assembly.py

@@ -10,6 +10,26 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+Greedy overlap assembly of VariantSequence objects.
+
+This module assembles short cDNA sequences (centered on a variant locus) into
+longer contiguous sequences by iteratively merging pairs with the largest
+overlaps.
+
+Assumptions / limitations:
+
+- **Exact sequence match**: overlap detection requires exact prefix/suffix
+  containment (str.endswith / str.startswith). A single sequencing error in
+  the flanking sequence prevents a merge. This is suitable for Illumina
+  short reads (~0.1% error rate) but will produce fragmented assemblies
+  with long-read technologies (PacBio/ONT, ~5-10% indel error rate).
+
+- **Shared alt allele**: all input VariantSequence objects must carry the
+  same alt allele string. Reads with different alleles at the variant locus
+  should be separated before assembly.
+"""
+
 from collections import defaultdict
 
 from .default_parameters import MIN_VARIANT_SEQUENCE_ASSEMBLY_OVERLAP_SIZE

isovar/variant_sequence.py

@@ -10,6 +10,19 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+VariantSequence represents an assembled cDNA sequence containing a mutation.
+
+Note on coverage trimming: trim_by_coverage() assumes that read coverage
+drops off monotonically away from the variant locus. This is generally true
+for short Illumina reads centered on a variant, but can be violated by
+reads spanning splice junctions or by uneven fragment sizes, which may
+create coverage "valleys". When the assumption fails, the trimmed interval
+may include positions with sub-threshold coverage (if the valley is
+interior) or the entire sequence may be discarded (if a variant base falls
+below the threshold).
+"""
+
 import numpy as np