Update getting_started & sce_file_contents with celltyping instructions #193

sjspielman · 2023-11-09T14:38:47Z

Closes #165
Closes #192

This PR updates docs with more cell typing information. Note that this is more or less ready for review, but I'm opening as a Draft PR specifically because some of the changes (celldex/panglaodb versions) here depend on forthcoming updates as part of AlexsLemonade/scpca-nf#538. So, we should not move to final.final approval until that is done.

Most changes here are in getting_started.md. I have subsections for each possible annotation type, and I go show SCE then AnnData for each set of tasks one might do. Noting a different way to break this up could be to show all SCE things for a given annotation, and then all AnnData things.

You'll also notice these sentences:

<!-- TODO: this instead? -->
Additional information about <`CellAssign`/`SingleR`> annotation results is also available from the `SingleCellExperiment`'s metadata, as described in the {ref}`experiment metadata table<sce_file_contents:SingleCellExperiment experiment metadata>`.

We currently don't need these sentences, but we could use them instead if we don't want to show how to pull out reference information from the metadata, and instead point folks to that table. Let me know which approach we prefer - showing the code here, or having this sentence instead!

As indicated, I went ahead and took care of #192 since it was so quick. I also removed some periods from the ends of table contents per overall style since I noticed them while scrolling through.

…etting_started

…n a subsection, not the bullet list of available celltypes

…ecide later which to use

allyhawkins

This mostly looks good, but I did have some comments on overall organization that I left. Something I didn't mention in my comments is that we should include a few resources on cell type annotation at the end of the section. This would mirror the other sections.

allyhawkins · 2023-11-09T22:06:45Z

docs/getting_started.md

+- Automated annotations from [`SingleR`](https://bioconductor.org/packages/release/bioc/html/SingleR.html), a reference-based method ([Looney _et al._ 2019](https://doi.org/10.1038/s41590-018-0276-y)).
+- Automated annotations from [`CellAssign`](https://github.com/Irrationone/cellassign), a marker-gene based method ([Zhang _et al._ 2019](https://doi.org/10.1038/s41592-019-0529-1)).


Suggested change

- Automated annotations from [`SingleR`](https://bioconductor.org/packages/release/bioc/html/SingleR.html), a reference-based method ([Looney _et al._ 2019](https://doi.org/10.1038/s41590-018-0276-y)).

- Automated annotations from [`CellAssign`](https://github.com/Irrationone/cellassign), a marker-gene based method ([Zhang _et al._ 2019](https://doi.org/10.1038/s41592-019-0529-1)).

- Annotations determined by using [`SingleR`](https://bioconductor.org/packages/release/bioc/html/SingleR.html), a reference-based method ([Looney _et al._ 2019](https://doi.org/10.1038/s41590-018-0276-y)).

- Annotations determined by using [`CellAssign`](https://github.com/Irrationone/cellassign), a marker-gene based method ([Zhang _et al._ 2019](https://doi.org/10.1038/s41592-019-0529-1)).

I don't know if this is much better, but we didn't take annotations from these methods, we performed annotation using those methods.

I think this could be a good middle ground - Annotations determined by <method>, an automated <thing-based> method

allyhawkins · 2023-11-09T22:07:43Z

docs/getting_started.md

+
+#### Submitter-provided annotations
+
+To access submitter-provided annotations in the `SingleCellExperiment`, use the following command:


I think we should add a note that not all libraries will contain submitter annotations. Although everything should include CellAssign/SingleR, it's much more likely that these will be missing.

docs/getting_started.md

allyhawkins · 2023-11-09T22:12:50Z

docs/getting_started.md

@@ -203,6 +203,167 @@ See these resources for more information on clustering:
 - [Quantifying clustering behavior in Orchestrating Single Cell Analysis](https://bioconductor.org/books/release/OSCA.advanced/clustering-redux.html#quantifying-clustering-behavior)


+### Cell type annotation


Generally, I think we want to add a little bit more context to this section. I would describe the references used in this first section. I would also mention the supplemental cell type report and that it's a good resource for evaluating the provided cell type annotations.

I added 2 links for cell annotation, but we could add more! Perhaps from this list we have going here? https://github.com/AlexsLemonade/training-specific-template/blob/main/additional-resources/single-cell-resources.md#cell-type-annotation

@allyhawkins this comment may have fallen by the wayside, any other links here?

I think what you added is good!

Co-authored-by: Ally Hawkins <[email protected]>

…tonal rearrangement and add code to determine which cell types are present

…ith regular annotation code

sjspielman · 2023-11-10T16:28:52Z

Thanks for the feedback, ready for another look! Note that I also updated the "intro" section here to show how to determine which cell types are present. This could use some feedback about wording.

Also...

think we should add a note that not all libraries will contain submitter annotations. Although everything should include CellAssign/SingleR, it's much more likely that these will be missing.

For this, I also popped a bullet into the intro section to say that we dont always expect submitter. What do you think of that approach vs text in the submitter section directly?

allyhawkins

Organization looks good! I just had a few comments about word choice. Also we may want to revisit the two additions to the metadata based on incoming scpca-nf changes.

docs/getting_started.md

allyhawkins · 2023-11-13T17:35:10Z

docs/sce_file_contents.md

@@ -136,8 +136,11 @@ metadata(sce) # experiment metadata
 | `singler_results` | If cell typing with `SingleR` was performed, the full result object returned by `SingleR` annotation. Only present for `processed` objects |
 | `singler_reference` | If cell typing with `SingleR` was performed, the name of the [`celldex`](http://bioconductor.org/packages/release/data/experiment/html/celldex.html) reference dataset used for annotation. Only present for `processed` objects |
 | `singler_reference_label` | If cell typing with `SingleR` was performed, the name of the label in the reference dataset used for annotation. Only present for `processed` objects |
+| `singler_reference_version`  | If cell typing with `SingleR` was performed with ontology labels, the [`celldex`](http://bioconductor.org/packages/release/data/experiment/html/celldex.html) package version used for the reference dataset |


Just to note that I'm going to file a PR today with adding this into the SCE object. I am adding both package and version so it will be celldex_1-12-1 or whatever the version is. So we might update this once we make a decision regarding how we are storing this information.

Ok, I'll circle back once that PR is set then (we can block this PR as needed, probably dont need to for this situation)

And we're back! In the end, we did the following. Names here still need to be updated, but the components are not changed.

https://github.com/AlexsLemonade/scpca-nf/blob/b4e8cc860ea7a40f730fd6807e12f0c89f87dfb1/bin/add_celltypes_to_sce.R#L140-L144

https://github.com/AlexsLemonade/scpca-nf/blob/b4e8cc860ea7a40f730fd6807e12f0c89f87dfb1/bin/add_celltypes_to_sce.R#L189-L193

Co-authored-by: Ally Hawkins <[email protected]>

sjspielman · 2023-11-15T17:42:14Z

I have updated this with the final naming scheme and information we've used in add_celltypes_to_sce.R, but a couple comments about this:

We (accidentally? my bad during review..?) ended up with both singler_ref_<stuff> and singler_reference_<stuff> (same for cellassign) metadata variables. Do we want to backtrack and make them all say _reference_?
How's my phrasing? This is hard! I wonder if I rearranged text too much and should be more firm that we use celldex and PanglaoDB, since at this point that's all that will be on the Portal.
I feel like we need to include a table somewhere in these forward-facing docs about what organs go into each CellAssign reference. Where do you think this might go? Can be in a subsequent PR.

allyhawkins

Thanks for catching that! I made the update in AlexsLemonade/scpca-nf#569. And then also made some small suggestions here.

docs/getting_started.md

docs/sce_file_contents.md

Co-authored-by: Ally Hawkins <[email protected]>

allyhawkins

LGTM 👍

allyhawkins · 2023-11-15T19:50:45Z

docs/getting_started.md

@@ -203,6 +203,167 @@ See these resources for more information on clustering:
 - [Quantifying clustering behavior in Orchestrating Single Cell Analysis](https://bioconductor.org/books/release/OSCA.advanced/clustering-redux.html#quantifying-clustering-behavior)


+### Cell type annotation


I think what you added is good!

sjspielman added 9 commits November 8, 2023 11:03

Fix typo in clustering section and initiate the celltype section in g…

55f6b74

…etting_started

rearrange so that information about accessing data is only provided i…

ed5bfff

…n a subsection, not the bullet list of available celltypes

Fix some typos and add rellink to metadata table

0b5792d

add ontology column for singler and predictions matrix for cellassign

32c68b5

Add more about reference information, but left previous sentence to d…

ad234e9

…ecide later which to use

fix spelling and some are -> is

4437490

remove some periods

ec32dc7

Takes care of #192

7c629de

dont commit the spell check errors file...

245cc5b

sjspielman marked this pull request as draft November 9, 2023 14:38

sjspielman requested a review from allyhawkins November 9, 2023 21:33

allyhawkins reviewed Nov 9, 2023

View reviewed changes

sjspielman and others added 6 commits November 10, 2023 10:19

Update docs/getting_started.md

e84f4e3

Co-authored-by: Ally Hawkins <[email protected]>

Refer to table for metadata and remove those code examples. Some addi…

44f8284

…tonal rearrangement and add code to determine which cell types are present

indicate that submitter is less common and add sentence about QC report

7bfdfeb

bulletify some of that text

a746b2a

some cell type resources

ef0f767

Submitter-excluded title case, and condense singler ontology labels w…

572f219

…ith regular annotation code

also update bullet text per review

23c8b40

sjspielman requested a review from allyhawkins November 10, 2023 16:36

allyhawkins reviewed Nov 13, 2023

View reviewed changes

Apply suggestions from code review

b60f013

Co-authored-by: Ally Hawkins <[email protected]>

sjspielman mentioned this pull request Nov 13, 2023

Add quick comment AlexsLemonade/scpca-nf#557

Merged

sjspielman added 2 commits November 13, 2023 14:59

Merge branch 'development' into sjspielman/165-celltype-getting-started

886523a

condense sentences to 1 about referring to metadata for more info

20349ed

sjspielman marked this pull request as ready for review November 15, 2023 17:29

Update table with correct names, phrasing, hopefully...

b652817

sjspielman requested a review from allyhawkins November 15, 2023 17:42

allyhawkins mentioned this pull request Nov 15, 2023

Standardize how we store cell type reference information AlexsLemonade/scpca-nf#569

Merged

allyhawkins reviewed Nov 15, 2023

View reviewed changes

docs/getting_started.md Outdated Show resolved Hide resolved

docs/sce_file_contents.md Outdated Show resolved Hide resolved

docs/sce_file_contents.md Outdated Show resolved Hide resolved

docs/sce_file_contents.md Outdated Show resolved Hide resolved

sjspielman and others added 3 commits November 15, 2023 13:17

Apply suggestions from code review

f10d7cb

Co-authored-by: Ally Hawkins <[email protected]>

one more spot to indicate that submitter may not always be present

8bcd24a

panglaodb link and wording

b0a7e85

sjspielman requested a review from allyhawkins November 15, 2023 18:23

allyhawkins approved these changes Nov 15, 2023

View reviewed changes

sjspielman merged commit 325bfdb into development Nov 15, 2023
1 check passed

sjspielman deleted the sjspielman/165-celltype-getting-started branch November 15, 2023 20:04

sjspielman restored the sjspielman/165-celltype-getting-started branch November 15, 2023 20:15

sjspielman deleted the sjspielman/165-celltype-getting-started branch November 15, 2023 21:00

This was referenced Nov 15, 2023

Add cell type annotation to getting started docs #165

Closed

Update sce file contents with cell type reference versions #192

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Update getting_started & sce_file_contents with celltyping instructions #193

Update getting_started & sce_file_contents with celltyping instructions #193

sjspielman commented Nov 9, 2023

allyhawkins left a comment

allyhawkins Nov 9, 2023

sjspielman Nov 10, 2023

allyhawkins Nov 9, 2023

allyhawkins Nov 9, 2023

sjspielman Nov 10, 2023

sjspielman Nov 15, 2023

allyhawkins Nov 15, 2023

sjspielman commented Nov 10, 2023

allyhawkins left a comment

allyhawkins Nov 13, 2023

sjspielman Nov 13, 2023

sjspielman Nov 15, 2023

sjspielman commented Nov 15, 2023

allyhawkins left a comment

allyhawkins left a comment

allyhawkins Nov 15, 2023

		- Automated annotations from [`SingleR`](https://bioconductor.org/packages/release/bioc/html/SingleR.html), a reference-based method ([Looney _et al._ 2019](https://doi.org/10.1038/s41590-018-0276-y)).
		- Automated annotations from [`CellAssign`](https://github.com/Irrationone/cellassign), a marker-gene based method ([Zhang _et al._ 2019](https://doi.org/10.1038/s41592-019-0529-1)).


		#### Submitter-provided annotations

		To access submitter-provided annotations in the `SingleCellExperiment`, use the following command:

		@@ -203,6 +203,167 @@ See these resources for more information on clustering:
		- [Quantifying clustering behavior in Orchestrating Single Cell Analysis](https://bioconductor.org/books/release/OSCA.advanced/clustering-redux.html#quantifying-clustering-behavior)


		### Cell type annotation

Update getting_started & sce_file_contents with celltyping instructions #193

Update getting_started & sce_file_contents with celltyping instructions #193

Conversation

sjspielman commented Nov 9, 2023

allyhawkins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjspielman commented Nov 10, 2023

allyhawkins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

sjspielman commented Nov 15, 2023

allyhawkins left a comment

Choose a reason for hiding this comment

allyhawkins left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment