10XGenomics · evolvedmicrobe · Nov 4, 2019 · Nov 8, 2019 · Dec 28, 2019 · Jan 3, 2020
diff --git a/.gitignore b/.gitignore
@@ -1,13 +1,24 @@
 *.o
 Depend.list
 
+.project
+.kdev4/
+source.kdev4
+
+
 # Don't track intermediary files from building the manual
-doc/*.aux
-doc/*.fdb_latexmk
-doc/*.fls
-doc/*.log
-doc/*.out
-doc/*.toc
+extras/doc-latex/*.aux
+extras/doc-latex/*.fdb_latexmk
+extras/doc-latex/*.fls
+extras/doc-latex/*.log
+extras/doc-latex/*.out
+extras/doc-latex/*.gz
+extras/doc-latex/*.toc
 
 # Don't track the STAR binary once it has being built
 source/STAR
+.DS_Store
+*.xcworkspacedata
+*.pbxproj
+*.plist
+*.xcuserstate
diff --git a/CHANGES.md b/CHANGES.md
diff --git a/README.md b/README.md
@@ -1,18 +1,19 @@
-STAR 2.7
-========
+STAR 2.7.9a
+==========
 Spliced Transcripts Alignment to a Reference
-© Alexander Dobin, 2009-2019
+© Alexander Dobin, 2009-2021
 https://www.ncbi.nlm.nih.gov/pubmed/23104886
 
 AUTHOR/SUPPORT
 ==============
-Alex Dobin, dobin@cshl.edu
+Alex Dobin, dobin@cshl.edu </br>
+https://github.com/alexdobin/STAR/issues </br>
 https://groups.google.com/d/forum/rna-star
 
 HARDWARE/SOFTWARE REQUIREMENTS
 ==============================
   * x86-64 compatible processors
-  * 64 bit Linux or Mac OS X 
+  * 64 bit Linux or Mac OS X
 
 MANUAL
 ======
@@ -35,9 +36,9 @@ Download the latest [release from](https://github.com/alexdobin/STAR/releases) a
 
 ```bash
 # Get latest STAR source from releases
-wget https://github.com/alexdobin/STAR/archive/2.7.2a.tar.gz
-tar -xzf 2.7.2a.tar.gz
-cd STAR-2.7.2a
+wget https://github.com/alexdobin/STAR/archive/2.7.9a.tar.gz
+tar -xzf 2.7.9a.tar.gz
+cd STAR-2.7.9a
 
 # Alternatively, get STAR source using git
 git clone https://github.com/alexdobin/STAR.git
@@ -51,17 +52,26 @@ Compile under Linux
 cd STAR/source
 make STAR
 ```
+For processors that do not support AVX extensions, specify the target SIMD architecture, e.g.
+```
+make STAR CXXFLAGS_SIMD=sse
+```
+
 
 Compile under Mac OS X
 ----------------------
 
 ```bash
 # 1. Install brew (http://brew.sh/)
-# 2. Install gcc with brew: 
+# 2. Install gcc with brew:
 $ brew install gcc --without-multilib
 # 3. Build STAR:
+# run 'make' in the source directory
 # note that the path to c++ executable has to be adjusted to its current version
+$cd source
 $make STARforMacStatic CXX=/usr/local/Cellar/gcc/8.2.0/bin/g++-8
+# 4. Make it availible through the terminal
+$cp STAR /usr/local/bin
 ```
 
 All platforms - non-standard gcc
@@ -100,5 +110,5 @@ Please contact the author for a list of recommended parameters for much larger o
 FUNDING
 =======
 The developmenr of STAR is supported by the National Human Genome Research Institute of
-the National Institutes of Health under Award Number R01HG009318. 
-The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.
+the National Institutes of Health under Award Number R01HG009318.
+The content is solely the responsibility of the authors and does not necessarily represent the official views of the National Institutes of Health.
diff --git a/RELEASEnotes.md b/RELEASEnotes.md
@@ -1,3 +1,99 @@
+STAR 2.7.9a --- 2021/05/05 ::: STARsolo updates
+=====================================================
+
+* [**Counting *multi-gene* (multimapping) reads**](#multi-gene-reads)
+* STARsolo uses [SIMDe](https://github.com/simd-everywhere/simde) package which support different types of SIMD extensions. For processors that do not support AVX extensions, specify the target SIMD architecture, e.g.
+```
+make STAR CXXFLAGS_SIMD=sse
+```
+
+
+STAR 2.7.8a --- 2021/02/20
+===========================
+**Major STARsolo updates and many bug fixes**
+
+* [**Cell calling (filtering) similar to CellRanger:**](docs/STARsolo.md#emptydrop-like-filtering)
+    * ```--soloCellFilter EmptyDrops_CR``` option for cell filtering (calling) nearly identical to that of CellRanger 3 and 4
+    * ```--runMode soloCellFiltering``` option for cell filtering (calling) of the raw count matrix, without re-mapping
+* [**Input from BAM files for STARsolo:**](docs/STARsolo.md#input-reads-from-bam-files)
+    * Input from unmapped or mapped SAM/BAM for STARsolo, with options ```--soloInputSAMattrBarcodeSeq``` and ```--soloInputSAMattrBarcodeQual``` to specify SAM tags for the barcode read sequence and qualities
+* [**Read trimming similar to CellRanger4:**](docs/STARsolo.md#matching-cellranger-4xx-and-5xx-results)
+    * ```--clipAdapterType CellRanger4``` option for 5' TSO adapter and 3' polyA-tail clipping of the reads to better match CellRanger >= 4.0.0 mapping results
+* [**Support for barcodes embedded in mates (such as 10X 5' protocol):**](docs/STARsolo.md#barcode-and-cdna-on-the-same-mate)
+    * ```--soloBarcodeMate``` to support scRNA-seq protocols in which one of the paired-end mates contains both barcode sequence and cDNA (e.g. 10X 5' protocol)
+
+STAR 2.7.7a --- 2020/12/28
+==========================
+**Major new feature:
+STARconsensus: mapping RNA-seq reads to consensus genome.**
+
+* Provide the VCF file with consensus SNVs and InDels at the genome generation stage with ```--genomeTransformVCF Variants.vcf  --genomeTransformType Haploid```.
+The alternative alleles in this VCF will be inserted to the reference genome to create a "transformed" genome.
+Both the genome sequence and transcript/gene annotations are transformed.
+
+* At the mapping stage, the reads will be mapped to the transformed (consensus) genome.
+The quantification in the transformed annotations can be performed with standard ```--quantMode TranscriptomeSAM and/or GeneCounts``` options.
+If desired, alignments (SAM/BAM) and spliced junctions (SJ.out.tab) can be transformed back to the original (reference) coordinates with ```--genomeTransformOutput SAM and/or SJ```.
+This is useful if downstream processing relies on reference coordinates.
+
+STAR 2.7.6a --- 2020/09/19
+==========================
+**Major new feature:**
+Output multimapping chimeric alignments in BAM format using
+```
+--chimMultimapNmax N>1 --chimOutType WithinBAM --outSAMtype BAM Unsorted [and/or] SortedByCoordinate
+```
+Many thanks to Sebastian @suhrig who implemented this feature!
+More detailed description from Sebastian in PR #802.
+
+STAR 2.7.5a 2020/06/16
+======================
+**Major new features:  
+~ support for Plate-based (Smart-seq) scRNA-seq  
+~ manifest file to list the input reads FASTQ files**
+
+* Typical STAR command for mapping and quantification of plate-based (Smart-seq) scRNA-seq  will look like:
+```
+ --soloType SmartSeq --readFilesManifest /path/to/manifest.tsv --soloUMIdedup Exact --soloStrand Unstranded
+```
+For detailed description, see [Plate-based (Smart-seq) scRNA-seq](docs/STARsolo.md#plate-based-Smart-seq-scRNA-seq)
+
+* The convenient way to list a large number of reads FASTQ files and their IDs is to create a file manifest and supply it in `--readFilesManifest /path/to/manifest.tsv`. The manifest file should contain 3 tab-separated columns. For paired-end reads:
+```
+Read1-file-name \t Read2-file-name \t File-id
+```
+For single-end reads, the 2nd column should contain the dash - :
+```
+Read1-file-name \t - \t File-id
+```
+File-id can be any string without spaces. File-id will be added as ReadGroup tag (*RG:Z:*) for each read in the SAM/BAM output. If File-id starts with *ID:*, it can contain several fields separated by tab, and all the fields will be copied verbatim into SAM *@RG* header line.
+
+
+STAR 2.7.4a 2020/06/01
+======================
+This release fixes multiple bugs and issues.  
+The biggest issue fixed was a seg-fault for small genome which previously required scaling down `--genomeSAindexNbases`. Such scaling is still recommended but is no longer required.  
+**This release requires re-generation of the genome indexes**
+
+STAR 2.7.3a 2019/10/08
+======================
+Major new features in STARsolo
+------------------------------
+* **Output enhancements:**
+    * Summary.csv statistics output for raw and filtered cells useful for quick run quality assessment.
+    * --soloCellFilter option for basic filtering of the cells, similar to the methods used by CellRanger 2.2.x.
+* [**Better compatibility with CellRanger 3.x.x:**](docs/STARsolo.md#matching-cellranger-3xx-results)
+    * --soloUMIfiltering MultiGeneUMI option introduced in CellRanger 3.x.x for filtering UMI collisions between different genes.
+    * --soloCBmatchWLtype 1MM_multi_pseudocounts option, introduced in CellRanger 3.x.x, which slightly changes the posterior probability calculation for CB with 1 mismatch.
+* [**Velocyto spliced/unspliced/ambiguous quantification:**](docs/STARsolo.md#velocyto-splicedunsplicedambiguous-quantification)
+    * --soloFeatures Velocyto option to produce Spliced, Unspliced, and Ambiguous counts similar to the [velocyto.py](http://velocyto.org/) tool developed by [LaManno et al](https://doi.org/10.1038/s41586-018-0414-6). This option is under active development and the results may change in the future versions.
+* [**Support for complex barcodes, e.g. inDrop:**](docs/STARsolo.md#barcode-geometry)
+    * Complex barcodes in STARsolo with --soloType CB_UMI_Complex, --soloCBmatchWLtype --soloAdapterSequence, --soloAdapterMismatchesNmax, --soloCBposition,--soloUMIposition
+* [**BAM tags:**](#bam-tags)
+    * CB/UB for corrected CellBarcode/UMI
+    * GX/GN for gene ID/name
+* STARsolo most up-to-date [documentation](docs/STARsolo.md).
+
 STAR 2.7.2a 2019/08/13
 ======================
 
@@ -17,10 +113,10 @@ STAR 2.7.0c 2019/02/05
 STARsolo: mapping, demultiplexing and gene quantification for single cell RNA-seq
 ---------------------------------------------------------------------------------
 STARsolo is a turnkey solution for analyzing droplet single cell RNA sequencing data (e.g. 10X Genomics Chromium System) built directly into STAR code.
-STARsolo inputs the raw FASTQ reads files, and performs the following operations 
+STARsolo inputs the raw FASTQ reads files, and performs the following operations
 * error correction and demultiplexing of cell barcodes using user-input whitelist
 * mapping the reads to the reference genome using the standard STAR spliced read alignment algorithm
-* error correction and collapsing (deduplication) of Unique Molecular Identifiers (UMIa) 
+* error correction and collapsing (deduplication) of Unique Molecular Identifiers (UMIa)
 * quantification of per-cell gene expression by counting the number of reads per gene
 
 STARsolo output is designed to be a drop-in replacement for 10X CellRanger gene quantification output.
@@ -29,15 +125,15 @@ At the same time STARsolo is ~10 times faster than the CellRanger.
 
 The STAR solo algorithm is turned on with:
 ```
---soloType Droplet 
+--soloType Droplet
 ```
 
 Presently, the cell barcode whitelist has to be provided with:
-``` 
+```
 --soloCBwhitelist /path/to/cell/barcode/whitelist
 ```
 
-The 10X Chromium whitelist file can be found inside the CellRanger distribution, 
+The 10X Chromium whitelist file can be found inside the CellRanger distribution,
 e.g. [10X-whitelist](https://kb.10xgenomics.com/hc/en-us/articles/115004506263-What-is-a-barcode-whitelist-).
 Please make sure that the whitelist is compatible with the specific version of the 10X chemistry (V1,V2,V3 etc).
 
@@ -105,20 +201,20 @@ If the overlap is found, STAR will map merge the mates and attempt to map the re
 If requested, the chimeric detection will be performed on the merged-mate sequence, thus allowing chimeric detection in the overlap region.
 If the score of this alignment higher than the original one, or if a chimeric alignment is found, STAR will report the merged-mate aligment instead of the original one.
 In the output, the merged-mate aligment will be converted back to paired-end format.  
-The developmment of this algorithm was supported by Illumina, Inc. 
+The developmment of this algorithm was supported by Illumina, Inc.
 Many thanks to June Snedecor, Xiao Chen, and Felix Schlesinger for their extensive help in developing this feature.
 
 
 **2. Detection of personal variants overlapping alignments.**  
-Option --varVCFfile /path/to/vcf/file is used to input VCF file with personal variants. Only single nucleotide variants (SNVs) are supported at the moment. 
+Option --varVCFfile /path/to/vcf/file is used to input VCF file with personal variants. Only single nucleotide variants (SNVs) are supported at the moment.
 Each variant is expected to have a genotype with two alleles.
-To output variants that overlap alignments, vG and vA have to be added to --outSAMattributes list. 
+To output variants that overlap alignments, vG and vA have to be added to --outSAMattributes list.
 SAM attribute vG outputs the genomic coordinate of the variant, allowing for identification of the variant.
 SAM attribute vA outputs which allele is detected in the read: 1 or 2 match one of the genotype alleles, 3 - no match to genotype.
 
 **3. WASP filtering of allele specific alignments.**  
 This is re-implementation of the original WASP algorithm by Bryce van de Geijn, Graham McVicker, Yoav Gilad & Jonathan K Pritchard. Please cite the original [WASP paper: Nature Methods 12, 1061–1063 (2015)   ](https://www.nature.com/articles/nmeth.3582).
-WASP filtering is activated with --waspOutputMode SAMtag, which will add vW tag to the SAM output: 
+WASP filtering is activated with --waspOutputMode SAMtag, which will add vW tag to the SAM output:
 vW:i:1 means alignment passed WASP filtering, while all other values mean it did not pass.  
 Many thanks to Bryce van de Geijn for fruitful discussions.
 
@@ -147,17 +243,17 @@ STAR 2.5.0a 2015/11/06
 
 Major new features:
 -------------------
-1. It is now possible to add extra sequences to the reference genome ont the fly (without re-generating the genome) by specifying 
-_--genomeFastaFiles /path/to/genome/fasta1 /path/to/genome/fasta2_ at the mapping stage. 
+1. It is now possible to add extra sequences to the reference genome ont the fly (without re-generating the genome) by specifying
+_--genomeFastaFiles /path/to/genome/fasta1 /path/to/genome/fasta2_ at the mapping stage.
 
 2. By default, the order of the multi-mapping alignments for each read is not truly random.
-The _--outMultimapperOrder Random_ option outputs multiple alignments for each read in random order, 
-and also also randomizes the choice of the primary alignment from the highest scoring alignments. 
-Parameter _--runRNGseed_ can be used to set the random generator seed. 
-With this option, the ordering of multi-mapping alignments of each read, 
+The _--outMultimapperOrder Random_ option outputs multiple alignments for each read in random order,
+and also also randomizes the choice of the primary alignment from the highest scoring alignments.
+Parameter _--runRNGseed_ can be used to set the random generator seed.
+With this option, the ordering of multi-mapping alignments of each read,
 and the choice of the primary alignment will vary from run to run, unless only one thread is used and the seed is kept constant.
 
-3. The --outSAMmultNmax parameter limits the number of output alignments (SAM lines) for multimappers. 
+3. The --outSAMmultNmax parameter limits the number of output alignments (SAM lines) for multimappers.
 For instance, _--outSAMmultNmax 1_ will output exactly one SAM line for each mapped read.
 
 
@@ -173,13 +269,13 @@ The counts coincide with those produced by htseq-count with default parameters.
 Requires annotations (GTF or GFF with --sjdbGTFfile option) used at the genome generation step, or at the mapping step.
 
 Outputs read counts per gene into ReadsPerGene.out.tab file with 4 columns which correspond to different strandedness options:
-column 1: gene ID 
+column 1: gene ID
 column 2: counts for unstranded RNA-seq
 column 3: counts for the 1st read strand aligned with RNA (htseq-count option -s yes)
 column 4: counts for the 2nd read strand aligned with RNA (htseq-count option -s reverse)
 Select the output according to the strandedness of your data.
 Note, that if you have stranded data and choose one of the columns 3 or 4, the other column (4 or 3) will give you the count of antisense reads.
- 
+
 With --quantMode TranscriptomeSAM GeneCounts, and get both the Aligned.toTranscriptome.out.bam and ReadsPerGene.out.tab outputs.
 
 
@@ -196,7 +292,7 @@ New features:
    The on the fly genome indices can be saved (for reuse) with "--sjdbInsertSave All", into _STARgenome directory inside the current run directory.
    Default --sjdbOverhang is now set at 100, and does not have to be specified unless you need to change this value.
 
-   The "all-sample" 2-pass method can be simplified using this on the fly junction insertion option: 
+   The "all-sample" 2-pass method can be simplified using this on the fly junction insertion option:
    (i) run the 1st pass for all samples as usual, with or without annotations
    (ii) run 2nd pass for all samples, listing SJ.out.tab files from all samples in --sjdbFileChrStartEnd /path/to/sj1.tab /path/to/sj2.tab ...
 
@@ -208,12 +304,12 @@ New features:
 3. Included link (submodule) to Brian Haas' STAR-Fusion code for detecting fusion transcript from STAR chimeric output:
    https://github.com/STAR-Fusion/STAR-Fusion
 
-4. Included Gery Vessere's shared memory implementation for POSIX and SysV. 
+4. Included Gery Vessere's shared memory implementation for POSIX and SysV.
    To compile STAR with POSIX shared memory, use `make POSIXSHARED`
 
 5. New option "--chimOutType WithinBAM" to include chimeric alignments together with normal alignments in the main (sorted or unsorted) BAM file(s).
    Formatting of chimeric alignments follows the latest SAM/BAM specifications. Thanks to Felix Schlesinger for thorough testing of this option.
 
-6. New option "--quantTranscriptomeBan Singleend" allows insertions, deletions ans soft-clips in the transcriptomic alignments, which can be used by some expression quantification software (e.g. eXpress). 
-   
+6. New option "--quantTranscriptomeBan Singleend" allows insertions, deletions ans soft-clips in the transcriptomic alignments, which can be used by some expression quantification software (e.g. eXpress).
+
 7. New option "--alignEndsTypeExtension Extend5pOfRead1" to enforce full extension of the 5p of the read1, while all other ends undergo local alignment and may be soft-clipped.
diff --git a/bin/Linux_x86_64/STAR b/bin/Linux_x86_64/STAR
diff --git a/bin/Linux_x86_64/STARlong b/bin/Linux_x86_64/STARlong
diff --git a/bin/Linux_x86_64_static/STAR b/bin/Linux_x86_64_static/STAR
diff --git a/bin/Linux_x86_64_static/STARlong b/bin/Linux_x86_64_static/STARlong
diff --git a/bin/MacOSX_x86_64/STAR b/bin/MacOSX_x86_64/STAR
diff --git a/bin/MacOSX_x86_64/STARlong b/bin/MacOSX_x86_64/STARlong
diff --git a/doc/STARmanual.pdf b/doc/STARmanual.pdf
diff --git a/docs/STARconsensus.md b/docs/STARconsensus.md
@@ -0,0 +1,13 @@
+STARconsensus: mapping RNA-seq reads to consensus genome.
+=========================================================
+
+* Introduced in STAR 2.7.7a (2020/12/28)
+
+* Provide the VCF file with consensus SNVs and InDels at the genome generation stage with ```--genomeTransformVCF Variants.vcf --genomeTransformType Haploid```.
+The alternative alleles in this VCF will be inserted to the reference genome to create a "transformed" genome.
+Both the genome sequence and transcript/gene annotations are transformed.
+
+* At the mapping stage, the reads will be mapped to the tranformed (consensus) genome.
+The quantification in the transformed annotations can be performed with standard ```--quantMode TranscriptomeSAM and/or GeneCounts``` options.
+If desired, alignments (SAM/BAM) and spliced junctions (SJ.out.tab) can be transformed back to the original (reference) coordinates with ```--genomeTransformOutput SAM and/or SJ```.
+This is useful if downstream processing relies on reference coordinates.