varvamp 0.3__py3-none-any.whl

varvamp/__init__.py

@@ -0,0 +1,3 @@
+"""Tool to design amplicons for highly variable virusgenomes"""
+_program = "varvamp"
+__version__ = "0.3"

varvamp/__main__.py

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+from varvamp import command
+
+if __name__ == '__main__':
+    command.main()

varvamp/command.py

@@ -0,0 +1,263 @@
+"""
+main workflow
+"""
+
+# BUILT-INS
+import sys
+import os
+import time
+import argparse
+
+# varVAMP
+from . import _program
+from varvamp import __version__
+from varvamp.scripts import logging
+from varvamp.scripts import alignment
+from varvamp.scripts import config
+from varvamp.scripts import consensus
+from varvamp.scripts import conserved
+from varvamp.scripts import primers
+from varvamp.scripts import reporting
+from varvamp.scripts import scheme
+
+
+# DEFs
+def get_args(sysargs):
+    """
+    arg parsing for varvamp
+    """
+    parser = argparse.ArgumentParser(
+        prog=_program,
+        description='varvamp: variable virus amplicon design',
+        usage='''varvamp <alignment> <output dir> [options]''')
+
+    parser.add_argument(
+        "input",
+        nargs=2,
+        help="alignment file and dir to write results"
+    )
+    parser.add_argument(
+        "-ol",
+        "--opt-length",
+        help="optimal length of the amplicons",
+        type=int,
+        default=config.AMPLICON_OPT_LENGTH
+    )
+    parser.add_argument(
+        "-ml",
+        "--max-length",
+        help="max length of the amplicons",
+        type=int,
+        default=config.AMPLICON_MAX_LENGTH
+    )
+    parser.add_argument(
+        "-o",
+        "--overlap",
+        type=float,
+        default=config.AMPLICON_MIN_OVERLAP,
+        help="min overlap of the amplicons"
+    )
+    parser.add_argument(
+        "-t",
+        "--threshold",
+        type=float,
+        default=config.FREQUENCY_THRESHOLD,
+        help="threshold for nucleotides in alignment to be considered conserved"
+    )
+    parser.add_argument(
+        "-a",
+        "--allowed-ambiguous",
+        type=int,
+        default=config.PRIMER_ALLOWED_N_AMB,
+        help="number of ambiguous characters that are allowed within a primer"
+    )
+    parser.add_argument(
+        "--console",
+        action=argparse.BooleanOptionalAction,
+        default=True,
+        help="show varvamp console output"
+    )
+    parser.add_argument(
+        "-v",
+        "--version",
+        action='version',
+        version=f"varvamp {__version__}"
+    )
+
+    if len(sysargs) < 1:
+        parser.print_help()
+        sys.exit(-1)
+    else:
+        return parser.parse_args(sysargs)
+
+
+def main(sysargs=sys.argv[1:]):
+    """
+    main varvamp workflow
+    """
+    # start varVAMP
+    args = get_args(sysargs)
+    if not args.console:
+        sys.stdout = open(os.devnull, 'w')
+    start_time = time.process_time()
+    results_dir, data_dir, log_file = logging.create_dir_structure(args.input[1])
+    logging.raise_arg_errors(args, log_file)
+    logging.varvamp_progress(log_file)
+    # config check
+    logging.confirm_config(args, log_file)
+    logging.varvamp_progress(
+        log_file,
+        progress=0.1,
+        job="Checking config.",
+        progress_text="config file passed"
+    )
+    # preprocess and clean alignment of gaps
+    alignment_cleaned, gaps_to_mask = alignment.process_alignment(
+        args.input[0],
+        args.threshold
+    )
+    logging.varvamp_progress(
+        log_file,
+        progress=0.2,
+        job="Preprocessing alignment and cleaning gaps.",
+        progress_text=f"{len(gaps_to_mask)} gaps with {alignment.calculate_total_masked_gaps(gaps_to_mask)} nucleotides"
+    )
+    # create consensus sequences
+    majority_consensus, ambiguous_consensus = consensus.create_consensus(
+        alignment_cleaned,
+        args.threshold
+    )
+    logging.varvamp_progress(
+        log_file,
+        progress=0.3,
+        job="Creating consensus sequences.",
+        progress_text=f"length of the consensus is {len(majority_consensus)} nt"
+    )
+    # generate conserved region list
+    conserved_regions = conserved.find_regions(
+        ambiguous_consensus,
+        args.allowed_ambiguous
+    )
+    if not conserved_regions:
+        logging.raise_error(
+            "nothing conserved. Lower the threshold!",
+            log_file,
+            exit=True
+        )
+    logging.varvamp_progress(
+        log_file,
+        progress=0.4,
+        job="Finding conserved regions.",
+        progress_text=f"{conserved.mean(conserved_regions, majority_consensus)} % conserved"
+    )
+    # produce kmers for all conserved regions
+    kmers = conserved.produce_kmers(
+        conserved_regions,
+        majority_consensus
+    )
+    logging.varvamp_progress(
+        log_file,
+        progress=0.5,
+        job="Digesting into kmers.",
+        progress_text=f"{len(kmers)} kmers"
+    )
+    # find potential primers
+    left_primer_candidates, right_primer_candidates = primers.find_primers(
+        kmers,
+        ambiguous_consensus,
+        alignment_cleaned
+    )
+    for type, primer_candidates in [("+", left_primer_candidates), ("-", right_primer_candidates)]:
+        if not primer_candidates:
+            logging.raise_error(
+                f"no {type} primers found.\n",
+                log_file,
+                exit=True
+            )
+    logging.varvamp_progress(
+        log_file,
+        progress=0.6,
+        job="Filtering for primers.",
+        progress_text=f"{len(left_primer_candidates)} fw and {len(right_primer_candidates)} rw potential primers"
+    )
+    # find best primers and create primer dict
+    all_primers = primers.find_best_primers(left_primer_candidates, right_primer_candidates)
+    logging.varvamp_progress(
+        log_file,
+        progress=0.7,
+        job="Considering only high scoring primers.",
+        progress_text=f"{len(all_primers['+'])} fw and {len(all_primers['-'])} rw primers"
+    )
+    # find all possible amplicons
+    amplicons = scheme.find_amplicons(
+        all_primers,
+        args.opt_length,
+        args.max_length
+    )
+    if not amplicons:
+        logging.raise_error(
+            "no amplicons found. Increase the max "
+            "amplicon length or lower threshold!\n",
+            log_file,
+            exit=True
+        )
+    amplicon_graph = scheme.create_amplicon_graph(amplicons, args.overlap)
+    logging.varvamp_progress(
+        log_file,
+        progress=0.8,
+        job="Finding potential amplicons.",
+        progress_text=str(len(amplicons)) + " potential amplicons"
+    )
+    # search for amplicon scheme
+    coverage, amplicon_scheme = scheme.find_best_covering_scheme(
+        amplicons,
+        amplicon_graph,
+        all_primers
+    )
+    dimers_not_solved = scheme.check_and_solve_heterodimers(
+        amplicon_scheme,
+        left_primer_candidates,
+        right_primer_candidates,
+        all_primers)
+    if dimers_not_solved:
+        logging.raise_error(
+            f"varVAMP found {len(dimers_not_solved)} primer dimers without replacements. Check the dimer file and perform the PCR for incomaptible amplicons in a sperate reaction.",
+            log_file
+        )
+        reporting.write_dimers(dir, dimers_not_solved)
+    percent_coverage = round(coverage/len(ambiguous_consensus)*100, 2)
+    logging.varvamp_progress(
+        log_file,
+        progress=0.9,
+        job="Creating amplicon scheme.",
+        progress_text=f"{percent_coverage} % total coverage with {len(amplicon_scheme[0]) + len(amplicon_scheme[1])} amplicons"
+    )
+    if percent_coverage < 70:
+        logging.raise_error(
+            "coverage < 70 %. Possible solutions:\n"
+            "\t - lower threshold\n"
+            "\t - increase amplicons lengths\n"
+            "\t - increase number of ambiguous nucleotides\n"
+            "\t - relax primer settings (not recommended)\n",
+            log_file
+        )
+    # write files
+    reporting.write_alignment(data_dir, alignment_cleaned)
+    reporting.write_fasta(data_dir, "majority_consensus", majority_consensus)
+    reporting.write_fasta(results_dir, "ambiguous_consensus", ambiguous_consensus)
+    reporting.write_conserved_to_bed(conserved_regions, data_dir)
+    reporting.write_all_primers(data_dir, all_primers)
+    reporting.write_scheme_to_files(
+        results_dir,
+        amplicon_scheme,
+        ambiguous_consensus
+    )
+    reporting.varvamp_plot(
+        results_dir,
+        args.threshold,
+        alignment_cleaned,
+        conserved_regions,
+        all_primers,
+        amplicon_scheme,
+    )
+    logging.varvamp_progress(log_file, progress=1, start_time=start_time)

varvamp/scripts/alignment.py

@@ -0,0 +1,223 @@
+"""
+alignment preprocessing
+"""
+
+# BUILT-INS
+import re
+
+# LIBS
+from Bio import AlignIO
+from Bio.Seq import Seq
+
+
+def read_alignment(alignment_path):
+    """
+    read alignment with AlignIO and
+    convert to list of lists
+    """
+    alignment_list = []
+
+    for sequence in AlignIO.read(alignment_path, "fasta"):
+        alignment_list.append([sequence.id, str(sequence.seq)])
+
+    return alignment_list
+
+
+def preprocess(alignment):
+    """
+    force nucleotides to lower and
+    back transcripe if its RNA
+    """
+    preprocessed_alignment = []
+
+    for sequence in alignment:
+        seq = Seq(sequence[1])
+        seq = seq.lower()
+        if "u" in seq:
+            seq = seq.back_transcribe()
+        preprocessed_alignment.append([sequence[0], str(seq)])
+
+    return preprocessed_alignment
+
+
+def find_gaps_in_alignment(alignment):
+    """
+    find all gaps for each sequence in alignment
+    """
+    all_gaps = []
+
+    for seq in alignment:
+        # find all gaps for all sequences with regular expression -{min}
+        all_gaps.append(
+            [(gap.start(0), gap.end(0)-1) for gap in re.finditer(
+                "-{1,}", seq[1])]
+            )
+
+    return all_gaps
+
+
+def find_unique_gaps(all_gaps):
+    """
+    get all unique gaps
+    """
+    result = list(set(gaps for gap_list in all_gaps for gaps in gap_list))
+    return result
+
+
+def find_internal_gaps(unique_gaps, gap):
+    """
+    find all unique gaps that
+    lie within the current gap
+    """
+    overlapping_gaps = []
+
+    if gap[1] - gap[0] == 0:
+        # if the gap length = 1 there are
+        # no overlapping gaps
+        overlapping_gaps = [gap]
+    else:
+        # for each unique gap check if the intersection with the
+        # gap is the same as the unique gap -> internal gap of
+        # the current gap
+        for unique_gap in unique_gaps:
+            unique_set = set(range(unique_gap[0], unique_gap[1]))
+            current_range = range(gap[0], gap[1])
+            intersection = unique_set.intersection(current_range)
+            if not intersection:
+                continue
+            if min(intersection) == unique_gap[0] and max(intersection)+1 == unique_gap[1]:
+                overlapping_gaps.append(unique_gap)
+
+    return overlapping_gaps
+
+
+def create_gap_dictionary(unique_gaps, all_gaps):
+    """
+    creates a dictionary with gap counts.
+    counts also all overlapping gaps per gap.
+    """
+
+    gap_dict = {}
+
+    for gap_list in all_gaps:
+        for gap in gap_list:
+            overlapping_gaps = find_internal_gaps(unique_gaps, gap)
+            for overlapping_gap in overlapping_gaps:
+                if overlapping_gap in gap_dict:
+                    gap_dict[overlapping_gap] += 1
+                else:
+                    gap_dict[overlapping_gap] = 1
+
+    return gap_dict
+
+
+def find_gaps_to_mask(gap_dict, cutoff):
+    """
+    filters gaps for their freq cutoff.
+    condenses final gaps if there is
+    an overlap.
+    """
+    gaps_to_mask = []
+    potential_gaps = []
+
+    # check for each region if it is covered
+    # by enough sequences
+    for gap in gap_dict:
+        if gap_dict[gap] > cutoff:
+            potential_gaps.append(gap)
+
+    # sort by start and stop
+    potential_gaps = sorted(potential_gaps)
+
+    # get the min and max of overlapping gaps
+    opened_region = []
+    gaps_to_mask = []
+    for i, region in enumerate(potential_gaps):
+        region = list(region)
+        if opened_region:
+            # write the opened region if the start of the current region
+            # > opened_region[stop] and the last still opened region
+            if region[0] > opened_region[1] or i == len(potential_gaps)-1:
+                gaps_to_mask.append(opened_region)
+                opened_region = region
+            else:
+                # 1 case: same start and further stop -> new stop
+                if region[0] == opened_region[0]:
+                    opened_region[1] = region[1]
+                # 2 case: further start and further stop -> new stop
+                if region[0] > opened_region[0] and region[1] > opened_region[1]:
+                    opened_region[1] = region[1]
+        else:
+            opened_region = region
+
+    return gaps_to_mask
+
+
+def clean_gaps(alignment, gaps_to_mask):
+    """
+    clean an alignment of large common deletions.
+    """
+    cleaned_alignment = []
+
+    for sequence in alignment:
+        start = 0
+        masked_seq = str()
+        for region in gaps_to_mask:
+            stop = region[0]
+            masked_seq_temp = sequence[1][start:stop]
+            # check if the deletion is at the start
+            if len(masked_seq_temp) != 0:
+                masked_seq = (masked_seq + "N" + masked_seq_temp)
+            start = region[1]+1
+        if max(gaps_to_mask)[1] < len(sequence[1])-1:
+            # append the last gaps if it is not
+            # the end of the sequence
+            start = max(gaps_to_mask)[1]
+            stop = len(sequence[1])-1
+            masked_seq_temp = sequence[1][start:stop]
+            masked_seq = (masked_seq + "N" + masked_seq_temp)
+        else:
+            # append the mask to the end of the seq
+            masked_seq = masked_seq + "N"
+
+        cleaned_alignment.append([sequence[0], masked_seq])
+
+    return cleaned_alignment
+
+
+def process_alignment(alignment_path, threshold):
+    """
+    proprocesses alignment and cleans gaps
+    """
+    alignment = read_alignment(alignment_path)
+    gap_cutoff = len(alignment)*(1-threshold)
+
+    alignment_preprocessed = preprocess(alignment)
+    all_gaps = find_gaps_in_alignment(alignment_preprocessed)
+    unique_gaps = find_unique_gaps(all_gaps)
+
+    if unique_gaps:
+        gap_dic = create_gap_dictionary(unique_gaps, all_gaps)
+        gaps_to_mask = find_gaps_to_mask(gap_dic, gap_cutoff)
+        alignment_cleaned = clean_gaps(
+            alignment_preprocessed, gaps_to_mask
+        )
+    else:
+        gaps_to_mask = []
+        alignment_cleaned = alignment_preprocessed
+
+    return alignment_cleaned, gaps_to_mask
+
+
+def calculate_total_masked_gaps(gaps_to_mask):
+    """
+    calculates the cummulative length of gaps
+    that were masked.
+    """
+    if gaps_to_mask:
+        sum_gaps = 0
+        for region in gaps_to_mask:
+            sum_gaps += region[1] - region[0] + 1
+        return sum_gaps
+    else:
+        return 0

varvamp/scripts/config.py

@@ -0,0 +1,59 @@
+"""
+This contains all varVAMP parameters. Options that can be adjusted by arguments
+are FREQUENCY_THRESHOLD, PRIMER_ALLOWED_N_AMB, AMPLICON_MIN_OVERLAP, AMPLICON_OPT_LENGTH,
+AMPLICON_MAX_LENGTH.
+"""
+
+# CAN BE CHANGED
+
+# alignment and consensus creation threshold
+FREQUENCY_THRESHOLD = 0.9  # freq at which a nucleotide is considered conserved
+PRIMER_ALLOWED_N_AMB = 4  # allowed number of ambiguous chars in primer
+
+# basic primer parameters
+PRIMER_TMP = (57, 63, 60)  # temperatur (min, max, opt)
+PRIMER_GC_RANGE = (40, 60, 50)  # gc (min, max, opt)
+PRIMER_SIZES = (17, 27, 20)  # size (min, max, opt)
+PRIMER_MAX_POLYX = 4  # max number of polyx repeats
+PRIMER_MAX_DINUC_REPEATS = 4  # max number of dinucleotide repeats
+PRIMER_HAIRPIN = 47  # max melting temp for secondary structures
+PRIMER_MAX_GC_END = 3  # max GCs in the last 5 bases of the primer
+PRIMER_GC_CLAMP = 1  # min number of GC nucleotides at the very 3' end
+PRIMER_MIN_3_WITHOUT_AMB = 2  # min len of 3' without ambiguous charaters
+PRIMER_MAX_DIMER_TMP = 47  # max melting temp for dimers (homo- or heterodimers)
+
+# PCR parameters
+PCR_MV_CONC = 50  # monovalent cations mM
+PCR_DV_CONC = 2  # divalent cations mM
+PCR_DNTP_CONC = 0.8  # dntp concentration mM
+PCR_DNA_CONC = 50  # primer concentration nM
+
+# multipliers for primer base penalties
+PRIMER_TM_PENALTY = 2  # temperature penalty
+PRIMER_GC_PENALTY = 0.2  # gc penalty
+PRIMER_SIZE_PENALTY = 0.5  # size penalty
+PRIMER_MAX_BASE_PENALTY = 8  # max base penalty for a primer
+PRIMER_3_PENALTY = (10, 10, 10)  # penalties for 3' mismatches
+PRIMER_PERMUTATION_PENALTY = 0.1  # penalty for the number of permutations
+
+# amplicon settings
+AMPLICON_MIN_OVERLAP = 100
+AMPLICON_OPT_LENGTH = 1000
+AMPLICON_MAX_LENGTH = 2000
+
+# DO NOT CHANGE
+# nucleotide definitions
+nucs = set("atcg")
+ambig_nucs = {
+    "r": ["a", "g"],
+    "y": ["c", "t"],
+    "s": ["g", "c"],
+    "w": ["a", "t"],
+    "k": ["g", "t"],
+    "m": ["a", "c"],
+    "b": ["c", "g", "t"],
+    "d": ["a", "g", "t"],
+    "h": ["a", "c", "t"],
+    "v": ["a", "c", "g"],
+    "n": ["a", "c", "g", "t"]
+}

varvamp/scripts/consensus.py

@@ -0,0 +1,111 @@
+"""
+consensus creation
+"""
+
+# BUILT-INS
+import collections
+
+# varVAMP
+from varvamp.scripts import config
+
+
+def determine_nucleotide_counts(alignment, idx):
+    """
+    count the number of each nucleotides at
+    an idx of the alignment. return sorted dic.
+    handels ambiguous nucleotides in sequences.
+    also handels gaps.
+    """
+    nucleotide_list = []
+
+    # get all nucleotides
+    for sequence in alignment:
+        nucleotide_list.append(sequence[1][idx])
+    # count occurences of nucleotides
+    counter = dict(collections.Counter(nucleotide_list))
+    # get permutations of an ambiguous nucleotide
+    to_delete = []
+    temp_dict = {}
+    for nucleotide in counter:
+        if nucleotide in config.ambig_nucs:
+            to_delete.append(nucleotide)
+            permutations = config.ambig_nucs[nucleotide]
+            adjusted_freq = 1/len(permutations)
+            for permutation in permutations:
+                if permutation in temp_dict:
+                    temp_dict[permutation] += adjusted_freq
+                else:
+                    temp_dict[permutation] = adjusted_freq
+        if nucleotide == "-":
+            to_delete.append(nucleotide)
+
+    # drop ambiguous entrys and add adjusted freqs to
+    if to_delete:
+        for i in to_delete:
+            counter.pop(i)
+        for nucleotide in temp_dict:
+            if nucleotide in counter:
+                counter[nucleotide] += temp_dict[nucleotide]
+            else:
+                counter[nucleotide] = temp_dict[nucleotide]
+
+    return dict(sorted(counter.items(), key=lambda x: x[1], reverse=True))
+
+
+def get_consensus_nucleotides(nucleotide_counts, consensus_cutoff):
+    """
+    get a list of nucleotides for the consensus seq
+    """
+    n = 0
+
+    consensus_nucleotides = []
+    for nuc in nucleotide_counts:
+        n += nucleotide_counts[nuc]
+        consensus_nucleotides.append(nuc)
+        if n >= consensus_cutoff:
+            break
+
+    return consensus_nucleotides
+
+
+def get_ambiguous_char(nucleotides):
+    """
+    get ambiguous char from a list of nucleotides
+    """
+    for ambiguous, permutations in config.ambig_nucs.items():
+        if set(permutations) == set(nucleotides):
+            return ambiguous
+
+
+def create_consensus(alignment, threshold):
+    """
+    build a majority sequence and a sequence that
+    has ambiguous chars as determined by the freq
+    threshold.
+    """
+
+    # ini the consensus seq
+    ambiguous_consensus = str()
+    majority_consensus = str()
+
+    # define consensus cut-off
+    consensus_cutoff = len(alignment)*threshold
+    # define length of the consensus from the first seq in alignment
+    length_consensus = len(alignment[0][1])
+
+    # built consensus sequences
+    for idx in range(length_consensus):
+        nucleotide_counts = determine_nucleotide_counts(alignment, idx)
+        consensus_nucleotide = get_consensus_nucleotides(
+            nucleotide_counts,
+            consensus_cutoff
+        )
+        if len(consensus_nucleotide) > 1:
+            amb_consensus_nucleotide = get_ambiguous_char(consensus_nucleotide)
+            ambiguous_consensus = ambiguous_consensus + amb_consensus_nucleotide
+        else:
+            ambiguous_consensus = ambiguous_consensus + consensus_nucleotide[0]
+
+        majority_consensus = majority_consensus + consensus_nucleotide[0]
+
+    return majority_consensus, ambiguous_consensus