Methods for cell type annotation and AnnData conversion

content/04.methods.md

@@ -103,8 +103,26 @@ In addition to using the default parameters for `salmon quant`, we applied the `
 
 ### Cell type annotation
 
-  - Implementation of SingleR and CellAssign
-  - Description of metrics used (e.g., what is the delta median and where does the probability come from)
+If cell types were obtained from the submitter of the dataset, the submitter-provided annotations were incorporated into all `SingleCellExperiment` objects (unfiltered, filtered, and processed). 
+Cell type labels determined by both `SingleR`[@doi:10.1038/s41590-018-0276-y] and `CellAssign`[@doi:10.1038/s41592-019-0529-1] were added to processed `SingleCellExperiment` objects.
+
+To build the references used for assigning cell types, a separate workflow within `scpca-nf` was run, `build-celltype-index.nf`. 
+For `SingleR` we used the `BlueprintEncodeData` from the `celldex` package [@doi:10.3324/haematol.2013.094243;@doi: 10.1038/nature11247;@doi:10.18129/B9.bioc.celldex]  to train the `SingleR` classification model with `SingleR::trainSingleR()`.
+The model and the processed `SingleCellExperiment` object were input to `SingleR::classifySingleR()`. 
+The `SingleR` output of cell type annotations and a score matrix for each cell and all possible cell types were added to the processed `SingleCellExperiment` object output. 
+To evaluate confidence in `SingleR` cell type assignments, we also calculated a delta median statistic for each cell by subtracting the median cell type score from the maximum score for that cell [@url:https://bioconductor.org/books/release/SingleRBook/annotation-diagnostics.html#based-on-the-deltas-across-cells]. 
+
+The delta median statistic is helpful in evaluating how confident `SingleR` is in assigning each cell to a specific cell type, where low delta median values indicate ambiguous assignments and high delta median values indicate confident assignments. 
+To identify the most appropriate reference to use with `SingleR`, we annotated a handful of samples across multiple disease types with all human-specific references available in the `celldex` package. 
+`BlueprintEncodeData` had the most consistently high delta median statistic distribution across samples from multiple disease types and was chosen as the reference to use for all ScPCA samples.
+
+For `CellAssign`, marker gene references were created using the marker gene lists available on `PanglaoDB` [@doi:10.1093/database/baz046]. 
+Organ-specific references were built using all cell types in a specified organ listed in `PanglaoDB` to accommodate all ScPCA projects encompassing a variety of disease and tissue type. 
+If a set of disease types in a given project encompassed cells that may be present in multiple organ groups, multiple organs were combined - e.g., for sarcomas that appear in bone or soft tissue, we created a reference containing bone, connective tissue, smooth muscle, and immune cells.
+
+Given the processed `SingleCellExperiment` object and organ-specific reference, `scvi.external.CellAssign` was used to train the model and predict the assigned cell type. 
+For each cell type in the reference, `CellAssign` calculates the probability that each cell is assigned to that cell type. 
+The probability matrix and a prediction based on the most likely cell type were added as cell type annotations to the processed `SingleCellExperiment` object output by `scpca-nf`.
 
 ### Generating merged data
 
@@ -124,6 +142,13 @@ If any libraries included in the ScPCA project contain additional ADT data, the
 By contrast, if any libraries included in the ScPCA project are multiplexed and contain HTO data, the HTO data is not merged and will not be present in the merged `SingleCellExperiment` object. 
 
 ### Converting SingleCellExperiment objects to AnnData objects
-  - use of zellkonverter
+
+`zellkonverter::writeH5AD()` was used to convert `SingleCellExperiment` objects to `AnnData` format and export the objects as `.hdf5` files. 
+For any `SingleCellExperiment` objects containing an `altExp` (e.g., ADT data), the RNA and ADT data were exported and saved separately as RNA (`_rna.hdf5`) and ADT (`_adt.hdf5`) files. 
+Multiplexed libraries were not converted to `AnnData` objects, due to the potential for ambiguity in sample origin assignments.
+
+All merged `SingleCellExperiment` objects were converted to `AnnData` objects and saved as `.hdf5` files.
+If a merged `SingleCellExperiment` object contained any ADT data, the RNA and ADT data were exported and saved separately as RNA (`_rna.hdf5`) and ADT (`_adt.hdf5`). 
+In contrast, if a merged `SingleCellExperiment` object contained HTO data due to the presence of any multiplexed libraries in the merged object, the HTO data was removed from the `SingleCellExperiment` object and not included in the exported `AnnData` object. 
 
 ### Code and data availability