Add celltyping to external instructions

config/reference_paths.config

@@ -12,13 +12,16 @@ celltype_organism = "Homo_sapiens.GRCh38.104"
 
 // cell type references directories
 celltype_ref_dir = "${params.ref_rootdir}/celltype"
-// output from save_singler_refs() process
+
+// populated by `build-celltype-ref.nf`, this stores the unaltered reference datasets
+//  from `celldex`. This is not used in `main.nf`.
 singler_references_dir = "${params.celltype_ref_dir}/singler_references"
-// output from train_singler_models() process, and input to classify_singler()
+
+// These directories hold the default SingleR and CellAssign reference files to use during cell typing
+// they are populated by `build-celltype-ref.nf` and consumed by `main.nf` during cell typing
 singler_models_dir = "${params.celltype_ref_dir}/singler_models"
-// output from generating cell assign reference matrices, and input to classify_cellassign()
 cellassign_ref_dir = "${params.celltype_ref_dir}/cellassign_references"
 
-// cell type metadata for building references
+// cell type metadata for building references in `build-celltype-ref.nf`; not used by main workflow
 celltype_ref_metadata = "${projectDir}/references/celltype-reference-metadata.tsv"
 panglao_marker_genes_file = "${projectDir}/references/PanglaoDB_markers_2020-03-27.tsv"

examples/README.md

@@ -2,37 +2,41 @@
 
 ## Example files
 
-This directory contains an example [metadata file](../external-data-instructions.md#prepare-the-metadata-file) and [configuration file](../external-data-instructions.md#configuration-files) for the `scpca-nf` workflow.
-These files should be used as an example of formats and content, but note that the values in these files may not be applicable or sufficient to allow running `scpca-nf` to be used directly on your system.
+This directory contains the following example files:
+
+- An example [metadata file](../external-instructions.md#prepare-the-run-metadata-file) for the `scpca-nf` workflow.
+- An example [configuration file](../external-instructions.md#configuration-files) for the `scpca-nf` workflow.
+- An example [cell type annotation metadata file](../external-instructions.md#performing-cell-type-annotation) for performing optional cell type annotation in the `scpca-nf` workflow.
+
+These files provide examples of expected formatting and content, but note that the specific values in these files may not be applicable or sufficient for running `scpca-nf` directly on your system.
 
 ## Testing your setup with example data
 
 :warning: These instructions are only intended to be used to test accurate set up of a configuration file.
-Before following these instructions, please ensure that you have already set up your own [configuration file](../external-data-instructions.md#configuration-files) and have [created and named a profile to use](../external-data-instructions.md#setting-up-a-profile-in-the-configuration-file).
+Before following these instructions, please ensure that you have already set up your own [configuration file](../external-instructions.md#configuration-files) and have [created and named a profile to use](../external-instructions.md#setting-up-a-profile-in-the-configuration-file).
 
 You can test your configuration setup by performing a test run with the example data that we have provided.
 
 We recommend using the example 10X dataset from a [human glioblastoma donor that was processed using the 10X Genomics' Next GEM Single Cell 3' Reagent Kits v3.1](https://www.10xgenomics.com/resources/datasets/2-k-sorted-cells-from-human-glioblastoma-multiforme-3-v-3-1-3-1-standard-6-0-0)(note: you may be prompted to provide an email and register upon navigating to the 10X downloads site).
 The fastq files for this example data can be downloaded from the following link (**note:** These files will take approximately 10 GB of disk space upon download and expanding the tar file): [Brain_Tumor_3p_fastqs.tar](https://cf.10xgenomics.com/samples/cell-exp/6.0.0/Brain_Tumor_3p/Brain_Tumor_3p_fastqs.tar).
 
-
 Following download and unzipping of the fastq files, you will need to create a tab-separated values **run** metadata file that looks like the following:
 
-| scpca_run_id | scpca_library_id | scpca_sample_id | scpca_project_id | technology | assay_ontology_term_id | seq_unit | sample_reference | files_directory | submitter_cell_types_file |
-| ------------ | ---------------- | --------------- | ---------------- | ---------- | ---------------------- | -------- | ---------------- | --------------- | ------------------------ |
-| run01 | library01 | sample01 | project01 | 10Xv3.1 | EFO:XXX | cell | Homo_sapiens.GRCh38.104 | /path/to/example_fastq_files | /path/to/annotated_cell_types_file
+| scpca_run_id | scpca_library_id | scpca_sample_id | scpca_project_id | technology | assay_ontology_term_id | seq_unit | sample_reference        | files_directory              |
+| ------------ | ---------------- | --------------- | ---------------- | ---------- | ---------------------- | -------- | ----------------------- | ---------------------------- |
+| run01        | library01        | sample01        | project01        | 10Xv3.1    | EFO:XXX                | cell     | Homo_sapiens.GRCh38.104 | /path/to/example_fastq_files |
 
-Be sure to enter the **full** path to the directory containing the fastq files in the `files_directory` column, and similarly the full path for the `submitter_cell_types_file` column.
+Be sure to enter the **full** path to the directory containing the fastq files in the `files_directory` column.
 
 You will also need to create a tab-separated values **sample** metadata file.
-At a minimum, the sample metadata file must contain a column with `scpca_sample_id` as the header_.
+At a minimum, the sample metadata file must contain a column with `scpca_sample_id` as the header.
 The contents of this column should contain all unique sample ids that are present in the `scpca_sample_id` column of the run metadata file.
 
 Below is an example of a sample metadata file:
 
-| scpca_sample_id | diagnosis | age |
-| --------------- | --------- | --- |
-| sample01 | glioblastoma | 71 |
+| scpca_sample_id | diagnosis    | age |
+| --------------- | ------------ | --- |
+| sample01        | glioblastoma | 71  |
 
 **Note that the `diagnosis` and `age` columns are shown as example sample metadata one might include in the sample metadata file.
 The metadata file that you create does not need to match this exactly, but it must contain the required `scpca_sample_id` column.**
@@ -47,11 +51,11 @@ nextflow run AlexsLemonade/scpca-nf \
   --sample_metafile <path to sample metadata file>
 ```
 
-Where `<path to config file>` is the **relative** path to the configuration file that you have setup after following the instructions on [creating a configuration file](../external-data-instructions.md#configuration-files), `<name of profile>` is the name of the profile that you chose when creating a profile, `<path to run metadata file>` is the **full** path to the run metadata TSV you created, and `<path to sample metadata file>` is the **full** path to the sample metadata TSV you created.
+Where `<path to config file>` is the **relative** path to the configuration file that you have setup after following the instructions on [creating a configuration file](../external-instructions.md#configuration-files), `<name of profile>` is the name of the profile that you chose when creating a profile, `<path to run metadata file>` is the **full** path to the run metadata TSV you created, and `<path to sample metadata file>` is the **full** path to the sample metadata TSV you created.
 For the [example configuration file that we provided](./user_template.config), we used the profile name `cluster` and would indicate that we would like to use that profile at the command line with `-profile cluster`.
-For more detailed information on setting up the metadata file for your own data, see instructions on [preparing the run metadata file](../external-data-instructions.md#prepare-the-run-metadata-file) and [preparing the sample metadata file](../external-instructions.md/#prepare-the-sample-metadata-file).
+For more detailed information on setting up the metadata file for your own data, see instructions on [preparing the run metadata file](../external-instructions.md#prepare-the-run-metadata-file) and [preparing the sample metadata file](../external-instructions.md/#prepare-the-sample-metadata-file).
 
 ## Example output
 
 You can download an example of the expected output files here: [`scpca_out.zip`](https://s3.amazonaws.com/scpca-references/example-data/scpca_out.zip).
-For more information on the file structure and what to expect see the description of the [output files](../external-data-instructions.md#output-files).
+For more information on the file structure and what to expect see the description of the [output files](../external-instructions.md#output-files).

examples/example_project_celltype_metadata.tsv

@@ -0,0 +1,4 @@
+scpca_project_id	singler_ref_name	singler_ref_file	cellassign_ref_name	cellassign_ref_file
+project01	BlueprintEncodeData	BlueprintEncodeData_celldex_1-10-1_model.rds	blood-compartment	blood-compartment_PanglaoDB_2020-03-27.tsv
+project02	HumanPrimaryCellAtlasData	HumanPrimaryCellAtlasData_celldex_1-10-1_model.rds	NA	NA
+project03	NA	NA	blood-compartment	blood-compartment_PanglaoDB_2020-03-27.tsv