Skip to content

Latest commit

 

History

History
473 lines (319 loc) · 19.5 KB

qexperiment_usage.md

File metadata and controls

473 lines (319 loc) · 19.5 KB
Raw

Usage of qexperiment module

PCR simulation

Simulate PCR (Polymerase Chain Reaction) on a given DNA template using specific primers.

pcr(template, fw, rv, bindnum=16, mismatch=1, endlength=3, return_template=False, product=None, product=None, process_description=None, pn=None, pd=None)

Parameters

  • template: QUEEN object
    DNA template to be amplified.

  • fw: QUEEN object or str
    Forward primer. Can be a QUEEN object or a string.

  • rv: QUEEN object or str
    Reverse primer. Can be a QUEEN object or a string.

  • bindnum: int, optional
    Minimum binding nucleotides for a primer. Default is 16.

  • mismatch: int, optional
    Maximum mismatches allowed in primer binding. Default is 1.

  • endlength: int, optional
    Length of primer's end region for binding consideration. Default is 3.

  • add_primerbind bool, optional
    If True, add DNAfeature on the primer binding regions in the template DNA.

  • tm_func function, optional Function to calculate the melting temperature of the primer pair. As str specfication, you can select "Breslauer" and "SantaLucia". Default is "SantaLucia".
    Also, as built-in algorithms, QUEEN.qexperiment.Tm_NN(). This function is implemented based on the Bio.SeqUtils.MeltingTemp.Tm_NN(), so the all parameters of Bio.SeqUtils.MeltingTemp.Tm_NN(), excluding seq and c_seq, can be acceptable.

  • return_tm : bool, optional If True, tm values of the primer pair are also returned.
    The tm values will be calculated based on thier biding region excluding adaptor regions.

  • product str, optional
    Product name.

  • process_name or pn: str, optional
    Brief label for the pcr process. Default is "PCR".

  • process_description or pd: str, optional
    Additional process description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • QUEEN object if return_tm is False, Otherwise QUEEN object, (tm_fw, tm_rv) Returns the PCR product (amplicon) as a QUEEN object. If return_tm is True, the Tm values of the given primer pair is also returned.

Example Usage

>>> template = QUEEN("example_dna_sequence")
>>> forward_primer = "xxxxxxxxx"
>>> reverse_primer = "xxxxxxxxx"
>>> pcr_product = pcr(template, forward_primer, reverse_primer)

Digestion simulation

Simulate DNA digestion using restriction enzymes and optionally perform size selection.

digestion(dna, *cutsites, size_selection=None, requirement=None, product=None, process_name=None, process_description=None, pn=None, pd=None)

Parameters

  • dna: QUEEN object
    DNA sequence to be digested.

  • cutsites: Cutsite or str
    Restriction enzymes for digestion.

  • size_selection: "min", "max", "label:*", "!label:*", or tuple of int, optional Criteria for fragment selection. If "min" is provided, the minimum fragment of the digested fragments would be returned.
    If "max" is provided, the maximum fragment of the digested fragments would be returned.
    If "label:{feature_of_interest}" is provided, the unique fragment holding the DNAfeature with feature_of_interest in "qualifer:label" would be returned. If multiple fragments holding the specified feature are detected, a error will be raised.
    If "!label:{feature_of_interest}" is provided, the unique fragment not holding the DNAfeature with feature_of_interest in "qualifer:label" would be returned. If multiple not fragments holding the specified feature are detected, a error will be raised. If a tuple value is provided, The tuple (min_size, max_size) specifies the size range for filtering the resulting fragments. If multiple fragments holding the are detected in the specified range, a error will be raised.
    If None, no filtering is done. Default is None.

  • product: str, optional
    Product name.

  • process_name or pn: str, optional
    Brief label for the digestion process. Default is "Digestion".

  • process_description or pd (str, optional)
    Additional process description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • list of QUEEN objects or QUEEN object If selection is None, return list of QUEEN objects composed of the digested fragments.
    Otherwise, return a specific fragment filling the specified condition.

Example Usage

>>> dna_sequence = QUEEN("example_dna_sequence")
>>> fragments = digestion(dna_sequence, cs.lib["BamHI"], cutsite["AgeI"], size_selection=(100, 1000))

DNA Ligation Simulation

Simulate the ligation of DNA fragments into unique or multiple constructs.

ligation(*fragments, unique=True, follow_order=False, product=None, process_name=None, process_description=None, pn=None, pd=None):

Parameters

  • fragments: list of QUEEN object
    DNA fragments to be ligated.

  • unique: bool, optional
    Whether to return only a unique construct. Default is True.

  • follow_order : bool, optional If True, a ligation reaction will be simulated along with the given order of fragments.
    Default is False.

  • product: str, optional
    Product name.

  • process_name or pn: str, optional
    Brief label for the ligation process. Default is "Ligation".

  • process_description or pd :str, optional
    Additional process description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • ｀QUEEN object｀ or list of QUEEN objects
    Construct(s) resulted from ligation.
    If unique is True and only one construct is possible, returns that construct as a QUEEN object.
    If unique is False, returns a list of all possible assembled constructs as QUEEN objects.
    If no constructs are possible, returns an empty list or None.

Example Usage

>>> fragment1 = QUEEN("dna_fragment_1")
>>> fragment2 = QUEEN("dna_fragment_2")
>>> assembled_product = ligation(fragment1, fragment2, unique=True)

Notes

The function attempts all permutations and orientations of the given fragments for ligation.
If unique is set to True, it validates the uniqueness of the assembled product.
The function handles situations where the assembly is not possible or results in multiple products.

Homology-Based DNA Assembly Simulation

Simulate DNA assembly using homology for various assembly modes.

homology_based_assembly(*fragments, mode="gibson", homology_length=20, unique=True, follow_order=None, product=None, process_name=None, process_description=None, pn=None, pd=None)

Parameters

  • fragments: QUEEN object
    DNA fragments for assembly.

  • mode: str, optional
    Assembly mode. Valid options are "gibson", "infusion", anb "overlappcr". Default is "gibson".

  • homology_length: int, optional
    Required homology length. Default is 20.

  • unique: bool, optional
    Return only a unique construct. Default is True.

  • follow_order : bool, optional If True, a ligation reaction will be simulated along with the given order of fragments. If the number of given fragments is larger than 4, default is True. Otherwise, False.

  • product: str, optional
    Product name.

  • process_name or pn: str, optional
    Brief label for the homology_based_assembly process. If mode is "gibson", default is "Gibson Assembly". If mode is "infusion", default is "In-Fusion Assembly".

  • process_description or pd: str, optional
    Additional description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • QUEEN object or list of QUEEN object
    Construct(s) resulted from assembly.
    If unique is True and only one construct is possible, returns that construct as a QUEEN object.
    If unique is False, returns a list of all possible assembled constructs as QUEEN objects.
    If no constructs are possible, returns an empty list or None.

Example Usage

>>> fragment1 = QUEEN("dna_fragment_1")
>>> fragment2 = QUEEN("dna_fragment_2")
>>> assembled_product = homology_based_assembly(fragment1, fragment2, mode="gibson", unique=True)

Notes

The function considers different assembly modes, each with its specific requirements for fragment or ientation and homology lengths. It handles permutations and orientations of the given fragments.

DNA Annealing Simulation

Simulate the annealing of two single-stranded DNA molecules based on homology.

annealing(ssdna1, ssdna2, homology_length=4, product=None, process_name=None, process_description=None, pn=None, pd=None)

Parameters

  • ssdna1 & ssdna2: QUEEN object
    Single-stranded DNAs for annealing.

  • homology_length: int, optional
    Required homology length. Default is 4.

  • product: str, optional
    Product name.

  • process_name or pn: str, optional
    Brief label for the annealing process. Default is "Annealing".

  • process_description or pd: str, optional
    Additional description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • QUEEN object
    Double-stranded DNA molecule after annealing.

Example Usage

>>> ssdna1 = QUEEN("ATCG")
>>> ssdna2 = QUEEN("CGAT")
>>> dsdna = annealing(ssdna1, ssdna2)

Gateway Reaction Simulation

Simulates a gateway reaction of two DNA molecules. For now, basic BP and LR reactions are available.

gateway_reaction(destination, entry, mode="BP", product=None, process_name=None, process_description=None, pn=None, pd=None)

Parameters

  • destination : QUEEN object The destination QUEEN object holding the backbone DNA molecule.

  • entry : QUEEN object The entry QUEEN object holding the insert DNA molecule.

  • mode: str, tuple, or list The mode of the reaction, can be "BP" or "LR". Default is "BP". For executing a custom BP or LR reaction, please speicy [B1 or L1 sequence, B1 or L2 sequence, P1 or R1 sequnce, P2 or R2 sequnece]` along with the QUEEN's cutsite format."

  • process_name or pn: str, optional
    Brief label for the annealing process. Default is "Gateway Reaction".

  • process_description or pd: str, optional
    Additional description.

  • pn str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • QUEEN object The QUEEN object representing the result of the gateway reaction process.

Golden Gate Assembly Simulation

Simulates a Golden Gate Assembly.

goldengate_assembly(destination, entry, cutsite=None, product=None, process_name=None, process_description=None, pn=None, pd=None, **kwargs)

Parameters

  • destination : QUEEN object The destination QUEEN object holding the backbone DNA molecule.

  • entry : list of QUEEN objects The entry QUEEN object(s) holding the insert DNA molecules.

  • cutsite : Cutsite or str The restriction enzyme site used for this reaction.

  • process_name : str, optional Brief label for the gateway reaction process. Default is "Golden Gate Assembly".

  • process_description : str, optional Additional description for the gateway reaction process.

  • pn : str, optional Alias for process_name.

  • pd : str, optional Alias for process_description.

Returns

  • QUEEN object The QUEEN object representing the result of the Golden Gate Assembly.

Primer Design for PCR Amplification

Design forward and reverse primers for PCR amplification of a target region, allowing for the introduction of specific mutations, checking primer specificity, and meeting additional user-defined requirements. If a list of templates and targets is specified, a batch process will be executed for each template and target. In that case, the other parameters except for adapter_mode can also be specified as a list of appropriate class objects. However, each list should be the same length as the list of templates.

primerdesign(template, target, fw_primer=None, rv_primer=None, fw_margin=0, rv_margin=0, target_tm=60.0, tm_func=None, primer_length=(16, 25), design_num=1, fw_adapter=None, rv_adapter=None, adapter_mode="standard", homology_length=20, nonspecific_limit=3, auto_adjust=1, requirement=None, fw_name="fw_primer", rv_name="rv_primer")

Parameters

  • template: QUEEN object of list of QUEEN objects. The QUEEN object to serve as the PCR template. If a list of templates is specified, appropriate primer pairs will be designed for each template.

  • target: QUEEN object of list of QUEEN objects. The sub-region in the template QUEEN object that needs to be included in the amplicon. If a list of targets is specified, the lengths should be the same, and each element should correspond to the template list.

  • fw_primer: ssDNA QUEEN object or list of ssDNA QUEEN object, optional A specific forward primer sequence.
    If provided, this sequence will be used as the forward primer.

  • rv_primer: ssDNA QUEEN object or list of ssDNA QUEEN object, optional A specific reverse primer sequence.
    If provided, this sequence will be used as the reverse primer.

  • fw_margin & rv_margin: int or list of int, optional
    Margins for primer design around the target region.

  • target_tm: float or list of float, optional
    Desired primer Tm. Default is 60.0 °C.

  • tm_func: str, function or list of str/func, optional Function to calculate the melting temperature of the primer pair. As str specfication, you can select "Breslauer" or "br" and "SantaLucia" or "sa". Default is "SantaLucia". Also, as built-in algorithms, QUEEN.qexperiment.Tm_NN(). This function is implemented based on the Bio.SeqUtils.MeltingTemp.Tm_NN(), so the all parameters of Bio.SeqUtils.MeltingTemp.Tm_NN(), excluding seq and c_seq, can be acceptable.

  • primer_length: tuple of int pair or list of int pairs, optional A tuple (min_size, max_size) specifying the primer length. Default is (16, 25).

  • design_num: int or list of int, optional Number of primer pairs to design. Default is 1.

  • adapter_mode: "standard", "gibson", "infusion", "overlappcr", "RE", or "BP". Default is "standard".
    The mode value specifies the the format of fw_adapter and rv_adapter. In batch process mode, this value should be common for all processes

  • fw_adapter ssDNA QUEEN object or str, optional
    If mode is "standard", the value must be a QUEEN object or a str object representing a DNA sequence. The sequence will be added at the beginning of any forward primers designed.
    If the mode is "gibson", "infusion", or "overlappcr", the value must be a dsDNA QUEEN object or None. If the value is None and the target is specified as a list of QUEEN objects, the QUEEN object immediately preceding the target used for the current primer design will be automatically specified. The adapter sequence overlapping the specified QUEEN object will be automatically designed and prepended to the forward primer. If mode is "RE", the value must be a Cutsite object or a str object representing a restriction enzyme (RE) site. The adapter sequence including the specified RE site will be added at the beginning of the forward primers. If mode is "BP", the value must be "attB1" or "attB2". The specified attB site will be added at the beginning of the forward primers. Currently, "attB1" and "attB2" are specified as follows:

    • attB1: GGGGACAAGTTTGTACAAAAAAGCAGGCT
    • attB2: GGGGACCACTTTGTACAAGAAAGCTGGGT

  • rv_adapter: ssDNA QUEEN object or str, optional
    If mode is "standard", the value must be a QUEEN object or a str object representing a DNA sequence. The sequence will be added at the beginning of any reverse primers designed.
    If the mode is "gibson", "infusion", or "overlappcr", the value must be a dsDNA QUEEN object or None. If the value is None and the target is specified as a list of QUEEN objects, the QUEEN object immediately following the target used for the current primer design will be automatically specified. The adapter sequence overlapping the specified QUEEN object will be automatically designed and prepended to the reverse primer. If mode is "RE", the value must be a Cutsite object or a str object representing a restriction enzyme (RE) site. The adapter sequence including the specified RE site will be added at the beginning of the reverse primers.
    If mode is "BP", the value must be "attB1" or "attB2". The specified attB site will be added at the beginning of the reverse primers. Currently, "attB1" and "attB2" are specified as follows:

    • attB1: GGGGACAAGTTTGTACAAAAAAGCAGGCT
    • attB2: GGGGACCACTTTGTACAAGAAAGCTGGGT

  • homology_length: int or list of int, optional Required homology for adapters.

  • nonspecific_limit: int or list of int, optional The maximum number of mismatches allowed for primer binding outside of the designated primer design region within the template sequence.
    Primer pairs that bind to any region of the template with a number of mismatches equal to or less than this limit will be excluded from the design, to increase the specificity of the PCR reaction and decrease the likelihood of nonspecific amplification. Default is 3.

  • requirement: function or list of func, optional
    Function that takes a dictionary representing a primer pair and returns True if the pair meets the specified conditions.
    Ensures that the 3' end nucleotide of both primers is not A or T by default.
    The detailed default function is lambda x: x["fw"][-1] not in ("A", "T") and x["rv"][-1] not in ("A", "T") Default requirement is as follows.

    • x["fw"][-1] not in ("A", "T") and x["rv"][-1] not in ("A", "T")
    • "AAAA" not in x["fw"] and "TTTT" not in x["fw"] and "GGGG" not in x["fw"] and "CCCC" not in x["fw"]
    • "AAAA" not in x["rv"] and "TTTT" not in x["rv"] and "GGGG" not in x["rv"] and "CCCC" not in x["rv"]

  • fw_name: str, optional
    Foward primer name, Default is "fw_primer".

  • rv_name: str, optional
    Reverse primer name, Default is "rv_primer".

Returns

  • list of dict A list of dictionaries where each dictionary represents a primer pair.
    Each dictionary contains two keys, "fw" and "rv", with the corresponding primer sequences formed by ssDNA QUEEN objects.
    The list is sorted by the closeness of the primer's Tm to the target_tm, with the closest pair first.

Example Usage

>>> from QUEEN.queen import *
>>> template_Q = QUEEN('ATGC...')
>>> target_Q = QUEEN('ATGC...')
>>> #Assuming target_Q sequence is within template_Q
>>> primers = primerdesign(template_Q, target_Q, target_tm=65.0, num_design=5)
>>> primers
[
    {"fw": QUEEN(seq="ATGCGT...", ssdna=True), "rv": QUEEN(seq="TACGCA...", ssdna=True)},
    {"fw": QUEEN(seq="ATGCGT...", ssdna=True), "rv": QUEEN(seq="TACGCA...", ssdna=True)},
    ...
]

Notes

The requirement for the target sequence to be within the template sequence ensures specificity of the primers to the region of interest. The function will not proceed if the target sequence is not a subset of the template.

Under implementation

  • intra_site_specific_recombination
  • homologous_recombination