search

AlexsLemonade / scpca-docs

User information about ScPCA processing
https://scpca.readthedocs.io/en/latest/
BSD 3-Clause "New" or "Revised" License
0 stars 1 forks source link

Establish new docs page for merged object contents #219

Closed jaclyn-taroni closed 9 months ago

jaclyn-taroni commented 10 months ago

Nothing about the Single-cell gene expression file contents section was noted in our meeting notes. I am filing this WIP issue to ensure we discuss whether or not a change to this section is required the next time we plan a sprint.

sjspielman commented 9 months ago

From Slack chat with @dvenprasad:

Merged objects should be its own page (and be one of the top level navigation items too). On the portal, we treat merged objects as separate option from the data format and keeping that same distinction in the docs will be helpful for both consistency and linking users to the right section from the download options help button.

So, nothing will need to change in sce_file_contents.md. Instead, we'll want to create a whole new file.

sjspielman commented 9 months ago

Seeking an opinion on how in-depth this page should go (@dvenprasad @allyhawkins). I am thinking of two broad options:

  1. We can effectively mirror the text in sce_file_contents.md for all relevant sections. The benefit of this is that it allows users to only have to read these merged file contents docs if that is what they chosen to download. The drawback is substantial repetition between documents (but is this actually a drawback?). Just as a miscellaneous example, even text like this would be adapted into this new merged file with text updated to reflect merged contents: https://github.com/AlexsLemonade/scpca-docs/blob/d7c2b4db3c75eb08530518c103fa23afc090ab8c/docs/sce_file_contents.md?plain=1#L9-L24

  2. We can focus on highlighting the differences of a merged object from an individual-library object, with much less repetition. The text I linked above would not be precisely replicated at all; instead, we might just say something along the lines of "the merged object contains expression counts, as described in \<link that sce_file_contents section>, except it has these differences from an individual-library object: ...."

sjspielman commented 9 months ago

The text I linked above would not be precisely replicated at all; instead, we might just say something along the lines of "the merged object contains expression counts, as described in , except it has these differences from an individual-library object: ...."

Followup to this - linking means they would have to go back and forth between pages a lot, which is probably very annoying for users.

sjspielman commented 9 months ago

Noting that @allyhawkins and I chatted a little about this in a separate meeting we had, and we both think that option 1 above is the right call here.

sjspielman commented 9 months ago

Notes to self:

Don't forget that we only keep these colData columns: https://github.com/AlexsLemonade/scpcaTools/blob/2ebdc4f4dfc4233fad97805f9a9a5e3bc6919f1e/R/merge_sce_list.R#L50C5-L60

As well as these if citeseq: https://github.com/AlexsLemonade/scpcaTools/blob/2ebdc4f4dfc4233fad97805f9a9a5e3bc6919f1e/R/merge_sce_list.R#L97C25-L104

And then we add in library_id and cell_id: https://github.com/AlexsLemonade/scpcaTools/blob/2ebdc4f4dfc4233fad97805f9a9a5e3bc6919f1e/R/merge_sce_list.R#L286-L290

sjspielman commented 9 months ago

This page has been established, so I'm going to close this issue in favor of #240 and #241 which track fleshing out the page in full.