Package: samsift
SAMsift is a program for advanced filtering and tagging of SAM/BAM alignments
using Python expressions.Getting started# clone this repo and add it to PATHgitclonehttp://github.com/karel-brinda/samsiftcdsamsiftexportPATH=$(pwd)/samsift:$PATH# filtering: keep only alignments with score >94, save them as filtered.bamsamsift-itests/test.bam-ofiltered.bam-f'AS>94'# filtering: keep only unaligned readssamsift-itests/test.bam-f'FLAG & 0x04'# filtering: keep only aligned readssamsift-itests/test.bam-f'not(FLAG & 0x04)'# filtering: keep only sequences containing ACCAGAGGATsamsift-itests/test.bam-f'SEQ.find("ACCAGAGGAT")!=-1'# filtering: keep only sequences containing A and T only (defined using regular expressions)samsift-itests/test.bam-f're.match(r"^[AT]*$", SEQ)'# filtering: sample alignments with 25% ratesamsift-itests/test.bam-f'random.random()<0.25'# filtering: sample alignments with 25% rate with a fixed RNG seedsamsift-itests/test.bam-f'random.random()<0.25'-0'random.seed(42)'# filtering: keep only alignments of reads specified in tests/qnames.txtsamsift-itests/test.bam-0'q=open("tests/qnames.txt").read().splitlines()'-f'QNAME in q'# filtering: keep only first 5000 reads from chr1 and 5000 reads from chr2samsift-itests/test.bam-0'c={"chr1":5000,"chr2":5000}'-f'c[RNAME]>0'-c'c[RNAME]-=1'-mnonstop-remove# tagging: add tags 'ln' with sequence length and 'ab' with average base qualitysamsift-itests/test.bam-c'ln=len(SEQ);ab=1.0*sum(QUALa)/ln'# tagging: add a tag 'ii' with the number of the current alignmentsamsift-itests/test.bam-0'i=0'-c'i+=1;ii=i'# updating: removing sequences and base qualitiessamsift-itests/test.bam-c'a.query_sequence=""'# updating: switching all reads to unalignedsamsift-itests/test.bam-c'a.flag|=0x4;a.reference_start=-1;a.cigarstring="";a.reference_id=-1;a.mapping_quality=0'InstallationUsing Bioconda:# add all necessary Bioconda channelscondaconfig--addchannelsdefaultscondaconfig--addchannelsconda-forgecondaconfig--addchannelsbioconda# install samsiftcondainstallsamsiftUsing PIP from PyPI:pipinstall--upgradesamsiftUsing PIP from Github:pipinstall--upgradegit+https://github.com/karel-brinda/samsiftCommand-line parametersProgram: samsift (advanced filtering and tagging of SAM/BAM alignments using Python expressions)
Version: 0.2.5
Author:  Karel Brinda <kbrinda@hsph.harvard.edu>

Usage:   samsift.py [-i FILE] [-o FILE] [-f PY_EXPR] [-c PY_CODE] [-m STR]
                    [-0 PY_CODE] [-d PY_EXPR] [-t PY_EXPR]

Basic options:
  -h, --help            show this help message and exit
  -v, --version         show program's version number and exit
  -i FILE               input SAM/BAM file [-]
  -o FILE               output SAM/BAM file [-]
  -f PY_EXPR            filtering expression [True]
  -c PY_CODE            code to be executed (e.g., assigning new tags) [None]
  -m STR                mode: strict (stop on first error)
                              nonstop-keep (keep alignments causing errors)
                              nonstop-remove (remove alignments causing errors) [strict]

Advanced options:
  -0 PY_CODE            initialization [None]
  -d PY_EXPR            debugging expression to print [None]
  -t PY_EXPR            debugging trigger [True]Algorithmexec(INITIALIZATION)forALIGNMENTinALIGNMENTS:ifeval(DEBUG_TRIGER):print(eval(DEBUG_EXPR))ifeval(FILTER):exec(CODE)print(ALIGNMENT)Python expressions and code.All expressions and code should be valid with
respect toPython 3. Expressions are evaluated
using theevalfunction and code is executed using theexecfunction.
Initialization can be used for importing Python modules, setting global
variables (e.g., counters) or loading data from disk. Some modules (namelyrandomandre) are loaded without an explicit request.Example(printing all alignments):samsift-itests/test.bam-f'True'SAM fields.Expressions and code can access variables mirroring the fields
from the alignment section of theSAM specification, i.e.,QNAME,FLAG,RNAME,POS(1-based),MAPQ,CIGAR,RNEXT,PNEXT,TLEN,SEQ, andQUAL. Several additional variables are defined to
simply accessing some useful information:QUALastores the base qualities
as an integer array;SEQs,QUALs,QUALsaskip soft-clipped bases;
andRNAMEiandRNEXTistore the reference ids as integers.Example(keeping only the alignments with leftmost position <= 10000):samsift-itests/test.bam-f'POS<=10000'SAMsift internally uses thePySamlibrary and
the representation of the current alignment (an instance of the classpysam.AlignedSegment) is
available as a variablea. Therefore, the previous example is equivalent tosamsift-itests/test.bam-f'a.reference_start+1<=10000'Theavariable can also be used for modifying the current alignment record.Example(removing the sequence and the bases from every record):samsift-itests/test.bam-c'a.query_sequence=""'SAM tags.Every SAM tag is translated to a variable with the same name.Example(removing alignments with a score smaller or equal to the sequence length):samsift-itests/test.bam-f'AS>len(SEQ)'IfCODEis provided, all two-letter variables exceptre(the Python regex
module) are back-translated to tags after the code execution.Example(adding a tagabcarrying the average base quality):samsift-itests/test.bam-c'ab=1.0*sum(QUALa)/len(QUALa)'Errors.If an error occurs during an evalution of an expression or an
execution of a code (e.g., due to accessing an undefined tag), then SAMsift
behavior depends on the specified mode (-m).  With the strict mode (-mstrict, default), SAMsift will immediately interrupt the computation and
report an error.  With the-mnonstop-keepoption, SAMsift will continue
processing the alignments while keeping the error-causing alignments in the
output.  With the-mnonstop-removeoption, all error-causing alignments
are skipped and ommited from the output.Similar programssamtools viewcan filter alignments based on FLAGS, read group tags, and CIGAR strings.sambamba viewsupports, in addition to SAMtools, a filtration usingsimple Perl-like expressions. However, it is not possible to use floats or compare different tags.BamQLprovides a simple query language for filtering SAM/BAM files.bamPalsadds tags XB, XE, XP and XL.SamJavascriptcan filter alignments using JavaScript expressions.Picard FilterSamReadscan also filter alignments using JavaScript expressions.IssuesPlease useGithub issues.ChangelogSeeReleases.LicenceMITAuthorKarel Brinda<kbrinda@hsph.harvard.edu>