Debian Codegraph @

src/java/org/broadinstitute/dropseqrna/barnyard/digitalallelecounts/sampleassignment/GenerateSyntheticDoublets.java

raw
1 /*
2 * MIT License
3 *
4 * Copyright 2017 Broad Institute
5 *
6 * Permission is hereby granted, free of charge, to any person obtaining a copy
7 * of this software and associated documentation files (the "Software"), to deal
8 * in the Software without restriction, including without limitation the rights
9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10 * copies of the Software, and to permit persons to whom the Software is
11 * furnished to do so, subject to the following conditions:
12 *
13 * The above copyright notice and this permission notice shall be included in all
14 * copies or substantial portions of the Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24 package org.broadinstitute.dropseqrna.barnyard.digitalallelecounts.sampleassignment;
25
26 import java.io.File;
27 import java.util.Iterator;
28 import java.util.List;
29 import java.util.Map;
30
31 import org.broadinstitute.barclay.argparser.Argument;
32 import org.broadinstitute.barclay.argparser.CommandLineProgramProperties;
33 import org.broadinstitute.dropseqrna.barnyard.BarcodeListRetrieval;
34 import org.broadinstitute.dropseqrna.barnyard.ParseBarcodeFile;
35 import org.broadinstitute.dropseqrna.cmdline.DropSeq;
36 import org.broadinstitute.dropseqrna.utils.FileListParsingUtils;
37 import org.broadinstitute.dropseqrna.utils.readiterators.SamFileMergeUtil;
38 import org.broadinstitute.dropseqrna.utils.readiterators.SamHeaderAndIterator;
39
40 import htsjdk.samtools.SAMFileWriter;
41 import htsjdk.samtools.SAMFileWriterFactory;
42 import htsjdk.samtools.SAMRecord;
43 import htsjdk.samtools.SamReaderFactory;
44 import htsjdk.samtools.util.CloserUtil;
45 import htsjdk.samtools.util.IOUtil;
46 import htsjdk.samtools.util.Log;
47 import htsjdk.samtools.util.ProgressLogger;
48 import picard.cmdline.CommandLineProgram;
49 import picard.cmdline.StandardOptionDefinitions;
50
51 @CommandLineProgramProperties(summary = "Takes a fraction of the cell barcodes and merges the barcode labels and reads of those cells into synthetic doublets. For example if cell A and B were"
52 + "selected to be a doublet, then a new cell called A_B would be generated that contained all the reads from the A and B cell barcodes.", oneLineSummary = "", programGroup = DropSeq.class)
53 public class GenerateSyntheticDoublets extends CommandLineProgram {
54 private static final Log log = Log
55 .getInstance(GenerateSyntheticDoublets.class);
56
57 @Argument(shortName = StandardOptionDefinitions.INPUT_SHORT_NAME, doc = "The input SAM or BAM file to analyze. This argument can accept wildcards, or a file with the suffix .bam_list that contains the locations of multiple BAM files", minElements = 1)
58 public List<File> INPUT;
59
60 @Argument(shortName = StandardOptionDefinitions.OUTPUT_SHORT_NAME, doc = "The output BAM file with generated multi-cells.")
61 public File OUTPUT;
62
63 @Argument (doc="Should singleton cells be emitted? If set to false, only the multicells that are generated are emitted.")
64 public Boolean EMIT_SINGLETONS=false;
65
66 @Argument(doc="Output file of the newly generated multicells. This file has 1 column with the names of the cells that were combined, colon seperated. "
67 + "This is the same format as MULTI_CELL_FILE, and can be used as input in a different run. ", optional=true)
68 public File SUMMARY;
69
70 @Argument(doc="How many multicells should be generated from the data? If the NUMBER_MULTICELL*NUM_CELLS_PER_MULTICELL > "
71 + "number of total cells, the program will report this as an error and exit.", mutex={"MULTI_CELL_FILE"})
72 public Integer NUMBER_MULTICELL;
73
74 @Argument(doc="How many cells should each multi-cell be made from?", mutex={"MULTI_CELL_FILE"})
75 public int MULTIPLICITY=2;
76
77 @Argument(doc="Instead of randomly selecting a fraction of cells as multicells, input a file defining the cell barcodes that will generate a doublet. "
78 + "The file has 1 column, for each cell barcode. Each row defines a single multicell. The entry is a colon seperated list of cell barcodes that represent all the cells that should be merged. "
79 + "For example, if you wanted to merge cells A B and C, the entry would be A:B;C. The file is tab delimited with no column header.", mutex={"NUMBER_MULTICELL"})
80 public File MULTI_CELL_FILE;
81
82 @Argument(doc = "The cell barcode tag. If there are no reads with this tag, the program will assume that all reads belong to the same cell and process in single sample mode.")
83 public String CELL_BARCODE_TAG = "XC";
84
85 @Argument(doc = "Number of cells that you want to extract from the BAM. The program will picks the top <NUM_BARCODES> barcodes by read count.", mutex = { "CELL_BC_FILE" }, optional=true)
86 public Integer NUM_BARCODES = null;
87
88 @Argument(doc = "Override NUM_CORE_BARCODES and process reads that have the cell barcodes in this file instead. The file has 1 column with no header.", mutex = { "NUM_BARCODES" }, optional=true)
89 public File CELL_BC_FILE = null;
90
91 @Argument(doc = "The map quality of the read to be included.")
92 public Integer READ_MQ = 10;
93
94 @Override
95 protected int doWork() {
96 this.INPUT = FileListParsingUtils.expandFileList(INPUT);
97 IOUtil.assertFileIsWritable(this.OUTPUT);
98 if (this.SUMMARY!=null)
99 IOUtil.assertFileIsWritable(this.SUMMARY);
100
101 List<MultiCell> multiCells = getMultiCells(this.MULTI_CELL_FILE, this.NUMBER_MULTICELL, this.MULTIPLICITY);
102 Map<String, List<String>> multiCellMap = MultiCell.getMap(multiCells);
103
104 // now just iterate through reads and write out the BAM with modified cell barcode tags.
105 SamHeaderAndIterator headerAndIter= SamFileMergeUtil.mergeInputs(this.INPUT, false, SamReaderFactory.makeDefault());
106
107 SAMFileWriter writer= new SAMFileWriterFactory().makeSAMOrBAMWriter(headerAndIter.header, true, OUTPUT);
108
109 ProgressLogger pl = new ProgressLogger(this.log);
110
111 for (Iterator<SAMRecord> i = headerAndIter.iterator; i.hasNext(); ) {
112 SAMRecord r = i.next();
113 pl.record(r);
114 String cellBarcode = r.getStringAttribute(this.CELL_BARCODE_TAG);
115 List<String> newBarcodes = multiCellMap.get(cellBarcode);
116
117 // cell is in MultiCell, change the barcode and write.
118 if (newBarcodes!=null) {
119 // write out the original read before writing out retagged reads.
120 if (EMIT_SINGLETONS)
121 writer.addAlignment(r);
122 // for each multicell this cell barcode partipates in, write out the read with the new tag.
123 for (String newBarcode: newBarcodes) {
124 r.setAttribute(this.CELL_BARCODE_TAG, newBarcode);
125 writer.addAlignment(r);
126 }
127 }
128 }
129 writer.close();
130
131 // write summary
132 if (this.SUMMARY!=null)
133 MultiCell.writeToFile(multiCells, this.SUMMARY);
134
135 return 0;
136 }
137
138
139
140 /**
141 * Generate a list of doublets
142 * This is either parsed in from a doubletFile, or if that parameter is null
143 * is generated from a list of cell barcodes and a fraction of doublets.
144 * @param doubletFile A file containing a list of cells to be merged into doublets
145 * @param cellBarcodes If doubletFile is null, a list of cell barcodes to merge into doublets
146 * @param numMultiCells The number of multi-cells created.
147 * @param multiplicity how many cells go into the multi-cell
148 * @return A list of doublets.
149 */
150 private List<MultiCell> getMultiCells (final File multiCellFile, final Integer numMultiCells, final Integer multiplicity) {
151 // if there's a doublet file
152 if (multiCellFile!=null) {
153 IOUtil.assertFileIsReadable(multiCellFile);
154 return MultiCell.parseFile(multiCellFile);
155 }
156 // do it the hard way and generate multiCells
157 List<String> cellBarcodes = getCellBarcodes();
158 List<MultiCell> result = MultiCell.generateMultiCells(cellBarcodes, numMultiCells, multiplicity);
159 return result;
160 }
161
162
163 // done before, pretty well tested elsewhere boilerplate.
164 private List<String> getCellBarcodes() {
165 if (this.CELL_BC_FILE != null) {
166 IOUtil.assertFileIsReadable(this.CELL_BC_FILE);
167 List<String> cellBarcodes = ParseBarcodeFile
168 .readCellBarcodeFile(this.CELL_BC_FILE);
169 log.info("Found " + cellBarcodes.size() + " cell barcodes in file");
170 return (cellBarcodes);
171 }
172 log.info("Gathering barcodes for the top [" + this.NUM_BARCODES
173 + "] cells");
174 return new BarcodeListRetrieval().getListCellBarcodesByReadCount(
175 this.INPUT, this.CELL_BARCODE_TAG, this.READ_MQ, null,
176 this.NUM_BARCODES);
177 }
178
179
180 /** Stock main method. */
181 public static void main(final String[] args) {
182 System.exit(new GenerateSyntheticDoublets().instanceMain(args));
183 }
184 }