QUEEN Installation and User Manual

QUEEN (a framework to generate quinable and efficiently editable nucleotide sequence resources) is a Python programming module designed to describe, share credit DNA building processes and resources. DNA parts information can be imported from external annotated DNA files (GenBank and FASTA format). Output file (GenBank format) encodes the complete information of the constructed DNA and its annotations and enables the production of a quine code that self-reproduces the output file itself. In QUEEN, all of the manipulations required in DNA construction are covered by four simple operational functions, "cutdna", "modifyends", "flipdna", and "joindna" that can collectively represent any of the standard molecular DNA cloning processes, two search functions, "searchsequence" and "searchfeature", and two super functions, "editsequence" and "editfeature". A new DNA can be designed by programming a Python script or using Jupyter Notebook, an interactive Python programming interpreter. The designed DNA product can be output in the GenBank file format that involves the history of its building process. The "quinable" feature of a QUEEN-generated GenBank file certifies that the annotated DNA material information and its production process are fully transparent, reproducible, inheritable, and modifiable by the community.

<img src="img/ga.jpg" width="600x600">

If you've found QUEEN is useful for your research, please consider citing our paper published in Nature Communications.

Mori, H., Yachie, N. A framework to efficiently describe and share reproducible DNA materials and construction protocols. Nat Commun 13, 2894 (2022). https://doi.org/10.1038/s41467-022-30588-x

• Software dependency
• Installation
• Usage
• QUEEN class
• Output functions
  • .printsequence()
  • .printfeature()
  • .outputgbk()
• Search Function
  • .searchsequence()
  • .searchfeature()
• Operational functions
  • cutdna()
    • cropdna()
  • modifyends()
  • flipdna()
  • joindna()
  • editsequence()
  • editfeature()
• Common parameters of the quinable functions
• Quine
  • quine()
• Visualization
  • visualizemap()
  • visualizeflow()

News

qexperiment module was added

qexperiment module enable users to easily describe and simulate experimental molecular cloing process with newly implemented methods based on actual experimental methods. For now, the following methods can be available.

• pcr
• digestion
• ligation
• homology_based_assembly
• annealing
• gateway_reaction
• goldengate_assembly
• primerdesigin (prototype)

For deatails, please see qexperiment_usage.md, qexperiment_demo.ipynb and Google colab notebook.

Change log

Please see changelog.md.

Software dependency

Python 3.7.0 or later

Installation

1. Install QUEEN using the following command.
   For the official release (v1.1.0) on the Python Package Index

   pip install python-queen 
   

   For the developmental version on GitHub

   pip install git+https://github.com/yachielab/QUEEN.git@(branch name) 
   

2. Install Graphviz (optional; required for visualizing flowcharts of DNA building processes using the visualizeflow() function described below). Graphviz package is available at the following link.

   • Graphviz

Usage

QUEEN provides the QUEEN class to define a double-stranded (ds)DNA object with sequence annotations. The QUEEN class and its operational functions are described below. Jupyter Notebook files for all of the example codes are provided in ./demo/tutorial of QUEEN (https://github.com/yachielab/QUEEN) and made executable in Google Colaboratory.

• tutorial_ex01-23
• tutorial_ex24-28

Command line interface
A part of QUEEN functions can also be used from the command line interface (CLI) instead of describing python codes.
For details, please see CLI_usage.md

Simulators for general molecular cloning methods
simple molecular cloning simulators for both homology-based and digestion/ligation-based assembly are provided on Google colab. By using these simulators, you can exeperience the benefits of QUEEN without describing python codes.

• Digestion/ligation-based assembly simulator
• Homology-based assembly simulator

QUEEN class

The QUEEN class can define a dsDNA object with sequence annotations. It can be created by specifying a DNA sequence or importing a sequence data file in GenBank or FASTA file format (single sequence entry). When a GenBank format file is imported, its NCBI accession number, Addgene plasmid ID, or Benchling share link can be provided instead of downloading the file to your local environment.

Example code 1: Create a QUEEN class object (blunt-ends)

A QUEEN_object (blunt-end) is created by providing its top-stranded sequence (5’-to-3’). By default, the DNA topology will be linear.
(Expected runtime: less than 1 sec.)

Source code

from QUEEN.queen import *
dna = QUEEN(seq="CCGGTATGCGTCGA") 

Example code 2: Create a QUEEN class object (sticky-end)

The left and right values separated by "/" show the top and bottom strand sequences of the generating QUEEN_object, respectively. The top strand sequence is provided in the 5’-to-3’ direction from left to right, whereas the bottom strand sequence is provided in the 3′-to-5′ direction from left to right. Single-stranded regions can be provided by "-" for the corresponding nucleotide positions on the opposite strands. A:T and G:C base-pairing rule is required between the two strings except for the single-stranded positions.
(Expected runtime: less than 1 sec.)

Source code

from QUEEN.queen import *
dna = QUEEN(seq="CCGGTATGCG----/----ATACGCAGCT") 

Example code 3.1: Create a circular QUEEN class object

The sequence topology of generating QUEEN_object can be specified by "linear" or "circular".
(Expected runtime: less than 1 sec.)

Source code

from QUEEN.queen import *
dna = QUEEN(seq="CCGGTATGCGTCGA", topology="circular") 

Example code 3.2: Create a ssDNA QUEEN class object *(available from v1.1)

The single strand QUEEN_object can be generated by specifying ssdna=True.
(Expected runtime: less than 1 sec.)

Source code

from QUEEN.queen import *
dna = QUEEN(seq="CCGGTATGCGTCGA", ssdna=True) 

Example code 4.1: Create a QUEEN class object from a GenBank file in a local directory

GenBank file can be loaded by specifying its local file path.
(Expected runtime: less than 1 sec.)

Source code

from QUEEN.queen import *
pUC19 = QUEEN(reco