Package: pyinseq
Lightweight python package to map transposon insertion sequencing (INSeq) data in
bacteria.Quick startThis section is meant for users who know their way around terminal andconda. To usepyinseq,
create a virtual environment withpython3.7 and installpyinsequsingconda.$condainstall-nbase-cconda-forgemamba
$condacreate-npyinseq-py37python=3.7
$condaactivatepyinseq-py37(pyinseq-py37)$condainstall-cbiocondabowtie(pyinseq-py37)$pipinstallpyinseqVerify your installation with--test(pyinseq-py37)$pyinseq--testNow you can runpyinseq!(pyinseq-py37)$pyinseq-i<inputfile>-s<samplefile>-g<genbankfile>-e<experimentname>Table of contentsOverview of Command Line OperationOutput descriptionNotes on outputBackgroundUser guideInput files descriptionGeneral UsageSpecialized tasksInstallationRequirementsInstallation in a conda environment (recommended)TestingFAQWhy do I get errors in processing the GenBank file?How do I uninstall pyinseq?How can I notify of an issue withpyinseqLicenseOverview of Command Line OperationBasic operation and a short description of the files are listed here. Below are detailed descriptions and links to example input files.$pyinseq-i<inputfile>-s<samplefile>-g<genbankfile>-e<experimentname>-i/--inputIllumina reads file in FASTQ or gzipped-FASTQ format.-s/--samplesSample list where each line is thesample_name<tab>barcode (4bp).-g/--genomeConcatenated GenBank File for all contigs for the genome.-e/--experimentAll results files will be created in a subfolder with this name.Snakemake--get_default_configCreates a default configuration file for runningpyinseq--config_formatFile format for configuration file (yamlorjson)-c/--configConfiguration file for running apyinseqworkflow. Every other argument will be ignored.--testRuns pytest on installedpyinseqsoftware.Optional arguments--gffGenerate genome output file ingff3format.-d/--disruptionFive-prime fraction of gene (0.0-1.0) that must be disrupted for the hit to be counted in the summary_gene_table. Often insertions at the 3' end of a gene do not disrupt function so it may be of interest to run the pipeline with a disruption value of0.8or0.9. [default: 0.9]--min_countMinimum number of reads per insertion site. [default: 3]--max_ratioMaximum ratio of left:right or right:left reads per insertion site. [default: 10]--barcode_lengthLength of barcode index that is expected in samples. [default: 4]--transposon_seqDNA sequence of transposon that flanks reads. [default: 'ACAGGTTG']-t/--threadsNumber of cores to use for execution [default: the CPU count of the computer]--snakemake_paramsAdditional parameters that will get passed tosnakemake.Output descriptionFileDescription<experiment name>-config.ymlConfiguration file with run parametersresults/summary_gene_table.txtsummary for entire experiment (values in counts-per-million, cpm)results/<sample>_sites.txt(for each sample)Counts of each insertion in each sampleresults/<sample>_genes.txt(for each sample)Counts of each insertion mapped to genesresults/<sample>_bowtie.txt(for each sample)Bowtie mapping resultsresults/<sample>_trimmed.fastq(for each sample)Demultiplexed fastq reads trimmed for the chromosome sequence onlyresults/log.txttext printed to consoleresults/samples_info_ymlbasics stats for each sampleresults/genome_lookup/genome.fnagenome fasta nucleotide fileresults/genome_lookup/genome.fttgenome feature tablebowtie indexesindex files created from genome by bowtieresults/raw_data/<sample>.fastq(for each sample)demultiplexed files for each sample/barcoderesults/raw_data/_other.fastqdemultiplexed files for unrecognized barcodesNotes on outputT50The minimum number of transposon insertion sites in the sample that account for at least 50% of the samples's reads. Used as a crude measure to detect bottlenecks, when comparing output T50 to the library input T50, or when comparing biological or technical replicates.samples_info.ymlContains basic information of each sample in the experiment.log.txtLog file from pyinseq, including the messages from thesnakemakeexecution. This includes the order of steps taken during the pyinseq execution.<experiment name>-config.yamlConfiguration file with run parameters.Backgroundpyinseqwas inspired by the software published byGoodman et al. (2011). There are a number of differences, some of which are noted here. Most are fairly superficial in that they are intended to increase automation and reproducibility but do not materially affect the results. One exception is the first point, which does affect the resulting output.As was conducted inBrooks et al. (2014)transposon site data are normalized across all replicons (chromosomes/plasmids/contigs) for calculation of a counts-per-million (cpm) per sample.The user's file of reads is demultiplexed into separate .fastq files for each barcoded read.The user provides a GenBank file, andpyinseqgenerates a fasta nucleotide file (.fna) and gene feature table (.ftt) that are formatted and named properly forbowtie.The gene feature table (.ftt) is comparable to the protein feature table (.ptt) but it also includes RNA genes.Ifpyinseqis installed fromconda, thenbowtieis installed fromcondaas a dependency.At the end of the analysis, results are aggregated into a tab-delimited table and sample info is summarized.pyinseqis written primarily in Python and usessnakemakeas the workflow manager. You probably figured that out already.User guideInput files descriptionIllumina sequencing reads [-i]for the experiment. File can be uncompressed (.fastq or .fq) or gzip-compressed (.fastq.gz or .fq.gz).Example input file@DGL9ZZQ1:720:C6YD0ACXX:2:1101:1246:2185 1:N:0:
GAAGCGACACCGACGACGGTAACAGGTTGGATGATAAGTCCCCGGTCTTCG
+
CCCFFFDDHHHHHCGHHHIJDHIIJJFHHJIJJJJIJJDHIJJHIAGIJJJ
...Sample file [-s]describing the sample names and barcodes. Sample names should be restricted to letters, numbers, dash (-), and underscore (_), with a tab between the sample and the barcode in each row of a text file. It is recommended that the file be prepared in a text editor to ensure that additional hidden characters are not introduced.BBEditis one option for Mac.Microsoft Excel can export tab-delimited files (.tsv), but do not use Microsoft Word for this purpose.Example sample fileE001_01 GAAG
E001_02 CTTTGenBank file [-g]listing the features and DNA sequence for the organism. If the organism has multiple chromosomes/contigs in the sequence the file they should be concatenated into a single file. Ensure that the double slash//at the end of the file remains to separate each contig.Files from NCBI GenBank often work where the corresponding files from NCBI RefSeq do not. Feel free to contact us with any questions here.Example GenBank fileLOCUS       CP000020             2897536 bp    DNA     circular BCT 02-APR-2008
DEFINITION  Vibrio fischeri ES114 chromosome I, complete sequence.
ACCESSION   CP000020
VERSION     CP000020.2  GI:171902228
KEYWORDS    .
SOURCE      Vibrio fischeri ES114
...
FEATURES             Location/Qualifiers
     source          1..2897536
                     /organism="Vibrio fischeri ES114"
                     /mol_type="genomic DNA"
                     /strain="ES114"
                     /db_xref="taxon:312309"
                     /chromosome="I"
     gene            complement(313..747)
                     /gene="mioC"
                     /locus_tag="VF_0001"
                     /old_locus_tag="VF0001"
     CDS             complement(313..747)
                     /dnas_title="FMN-binding protein MioC"
                     /gene="mioC"
                     /locus_tag="VF_0001"
                     /old_locus_tag="VF0001"
                     /codon_start=1
                     /transl_table=11
                     /product="FMN-binding protein MioC"
                     /protein_id="AAW84496.1"
                     /db_xref="GI:59478709"
                     /translation="MKKVSIITGSTLGGAEYVGDHLADLLEEMDFSTDIHNQPNLDDI
                     DIDSLWLLVVSTHGAGDYPDNIKPFIQQLESVTQPLSSVEFAVVAIGDSSYDTFCAAG
                     KSLQNTLKEHGAIEKYPLLEIDVTQNSIPEEPAELWLKQHIC"
...
ORIGIN
        1 aagatcactt aatatatata agatctttta aagagatctt ttattagatc tattatatag
       61 atcgtcgatc tctgtggata agtgataaat gatcaatagg atcatatact ttagatggat
      121 ccaaagttgt tatctttctt tgatcttcga tcggacagct tgaggacaaa agagttagtt
      181 atccacaagg ggggagggcg ttagatctta ttcaatggat aactataact tgatcactgg
      241 atctttctat agttatccac atagtaggta tcatctattt aataactttt atagatcgga
      301 caacactttt tattaacaaa tgtgttgttt tagccacaat tctgctggtt cttcagggat
      361 actattttga gttacatcta tctctaatag agggtacttt tcgatagcgc catgctcttt
      421 taaggtattt tgaagtgatt ttcctgctgc gcagaaagtg tcataacttg aatcaccgat
      481 agcaacaaca gcaaattcaa cgctcgataa tggctgagtc acgctttcta actgttgaat
      541 aaatggttta atgttgtcag ggtaatcacc agcaccgtga gttgatacaa cgagtaacca
      601 taagctatca atatcaatat catctaaatt tggttgatta tgaatatcgg tggaaaaatc
      661 catttcttct aataaatcag caagatggtc accaacatac tcagcaccac ctagagtgct
      721 tcctgtaata atagatactt ttttcatgaa tttatcctat aaaaatataa aaaatgggcc
      781 tacataggcc cattattaat cttattaata ttggttttat ttaccaatac agaatgaagt
...
//
LOCUS       CP000021             1330333 bp    DNA     circular BCT 02-APR-2008
DEFINITION  Vibrio fischeri ES114 chromosome II, complete sequence.
...General UsagePyinseq usessnakemaketo execute the following workflow:pyinseqDemultiplex a file of FASTQ reads.Write separate trimmed versions of the files (no barcodes, no transposon sequence).Map the trimmed reads to the genome.Quantify insertions per site and per ORF in the genome.Output summary gene table and report files describing the dataset.The benefit of usingsnakemakeis that it allows for parallel execution if more than onethreadis provided.
The modularity ofsnakemakeenables future feature implementation.Run Parameters (Config File)pyinseqwrites a configuration file (<experiment name>-config.yaml) into the working directory, which holds the parameters for the run.
For the example command below, thepyinseq-config.yamlfile will store the parameters used for this run.$pyinseq-ireads.fastq-ssamples.txt-ggenome.gbk-epyinseq--threads4Example Config File$catdemo-run-config.yaml
snakemake_params:[]barcode_length:4command:pyinseq
config:falseconfig_format:yaml
disruption:0.9
experiment:demo-run
genome:genome.gbk
get_default_config:falsegff3:falseinput:reads.fastq.gz
max_ratio:10min_count:3samples:samples.txt
threads:4transposon_seq:ACAGGTTGIf you installedcondain your terminal, you can use the option--use-condawhich will install bowtie during the executuion of the workflow.$pyinseq-ireads.fastq-ssamples.txt-ggenome.gbk-edemo-run--threads4--snakemake_params--use-condaYou can also get a default configuration file by using--get_default_configand modify it using a text-editor.$pyinseq--get_default_config
$ls
default-config-pyinseq.yamlMake sure that all file paths in the configuration are correctSpecialized tasksThese commands are useful when combining samples from multiple Illumina runs in a singlepyinseqanalysis.
Both commands will also create a configuration file specific to each subcommand.pyinseq demultiplexDemultiplex a file of Illumina reads.Writes separate trimmed versions of the files (no barcode, no transposon sequence) unless the optional--notrimflag is added.$pyinseqdemultiplex-i<inputfile>-s<samplefile>-e<experimentname>pyinseq genomeprepPrepare the fasta nucleotide (.fna) and feature table (.ftt) files from a GenBank file.Is a good quick test to run on new GenBank files.Generates bowtie indexes unless the--noindexflag is added.Optionally create GFF3 file with the-gffflag (for use in other programs).$pyinseqgenomeprep-g<genbankfile>-e<experimentname>Similar topyinseqmain usage, you can run these commands using a configuration
file and pass additionalsnakemakeoptions.InstallationRequirementspyinseqwas written and tested using a MacOS (or Linux-based) operating system.MacOS or Linux-based operating systems.Python 3.7bowtie(v1.0.0)snakemakepyinseqhas not being tested on Windows operating systems, but as of Windows 10
there is support for terminals withUbuntuAlso note thatpyinsequsesbowtie;not bowtie2, which is a different software.Installation in a conda environment (recommended)Conda is a command-line package manager that can create virtual environments with
all the necessary dependencies to runpyinseq. You can acquire conda by installingAnacondaand all the packages it
brings, or by installing its lightweight version calledminiconda.
We recommendminicondasince it installs a minimal number packages,
and is actually all you need to runpyinseqOnce conda is installed, you can verify it by running:$conda--helpInstalling mambamambais now required forsnakemake. Install it system-wide with this command. The subsequent steps are shown usingcondasince that is more common for the
scientific audience, but can largely be accomplished inmambaif the user desires.conda install -n base -c conda-forge mambaCreating a virtual environmentA virtual environment is an isolated computational space where you can install dependencies and software without affecting the base operating system's configuration.
We can usecondato create a virtual environment with python 3.7$condacreate-npyinseq-py37python=3.7To activate your environment:$condaactivatepyinseq-py37You should see the name of your environment surrounded by parentheses in your terminal prompt.(pyinseq-py37)$Installbowtie:(pyinseq-py37)$condainstall-cbiocondabowtieInstallpyinseq:Install the stable version:(pyinseq-py37)$pipinstallpyinseqOr, install the most recent version from GitHub:(pyinseq-py37) $ pip install git+https://github.com/mjmlab/pyinseqVerify your installation with--test(pyinseq-py37)$pyinseq--test


Verifythatpyinseqinstalledcorrectlybyrunning:```bash(pyinseq-py37)$pyinseq--help2021-05-2613:10-INFO-pyinseq-Processcommandlinearguments
usage:pyinseq[-h][--get_default_config][--config_formatCONFIG_FORMAT][-cCONFIG][-tTHREADS][--snakemake_params...][-v][-iINPUT][-sSAMPLES][-eEXPERIMENT][-gGENOME][-dDISRUPTION][--min_countMIN_COUNT][--max_ratioMAX_RATIO][--barcode_lengthBARCODE_LENGTH][--transposon_seqTRANSPOSON_SEQ][--gff3]{demultiplex,genomeprep}...
...Now you are ready to runpyinseq!TestingYou can test your installation ofpyinseqby using the option--test.(pyinseq-py37)$pyinseq--testIf all tests pass then you are good to go!FAQWhy do I get errors in processing the GenBank file?Ensure that the file is in GenBank and not RefSeq format.How do I uninstall pyinseq?You can do this two ways:uninstalling pyinseq from the virtual environmentpip uninstall pyinseqor completely remove the conda virtual environment.conda env remove -n pyinseq-py37Note: will need toconda deactivatefirst to leave the environment.How can I notify of an issue withpyinseqPlease use theGitHub Issues.LicensePyinseq is an open-source software licensed under BSD-3.