Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Initiate scAdvanced cheatsheet #663

Merged
merged 33 commits into from
Mar 6, 2023
Merged

Conversation

sjspielman
Copy link
Member

Towards #646

This PR begins the process of establishing a scAdvanced cheatsheet. I am going to split this up into 2 PRs, since there's a decent amount to review here.
This PR accomplishes two goals:

  • Add functions to the intro cheatsheet that should have been in the intro cheatsheet all along
  • Establish the scAdvanced cheatsheet, including all tables of functions

There will be one additional PR to add in Seurat <-> SCE conversions (stubbed out but not filled out in the cheatsheet!). Right now, I have only committed md files since I expect changes! At the end of this PR, I'd like for the intro PDF to make it into the repo, but the advanced PDF will be part of the next PR.

Some specific notes for reviewers:

  • Enjoy link clicking and finding all the links I didn't get right 🥴! That's it for this bullet.
  • Turns out map_df() is in the intro r cheatsheet, but it's only used in setup code for the intro workshop. It didn't seem like a big deal to me to leave in. I had forgotten there was some very light purrr in intro, too!!
  • Any overall thoughts on order of the topics in the cheatsheet? I tried to loosely structure in order of when items appear (though this isn't possible to do fully linearly), with all tidyverse at the end. The conversion is stubbed out at the top as this is a common question.
  • plotExpression() is really the only "new" scater function in scAdvanced. But, I went ahead and added some of intro the scater functions into the advanced, since they're important for advanced and come up a lot (plotReducedDim and plotUMAP). Eventually this will get solidified with "cheatsheets by topic," so I thought this duplication would be ok for now.
  • I couldn't quite land on the right level of detail for miQC explanations, any thoughts? Somehow "Plot the miQC model" for plotModel() didn't seem enough, but actually explaining what gets plotted makes for a LONG table row...!
  • I'm not a fan, but the title for HarmonyMatrix() is "Main Harmony interface". Feeling like I just ignore that and write "harmony matrix"...
  • Currently all tidyverse is in one table, and I both feel like that's reasonable and it's excessive! Therefore, how many tables this is can be up to reviewers! (Maybe a separate table for just ggplot2?)

…monade/training-modules into sjspielman/scAdvanced-cheatsheet
Copy link
Member

@jashapiro jashapiro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good to start!

I think I addressed most of your bullet points with line comments, but for some of the more overall comments, I think the order is fine, though I might move the seurat conversion to the end. But I can probably go either way on that.

I checked many links, but probably not all of them...

module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
@sjspielman
Copy link
Member Author

@jashapiro this should be ready for another look! I've implemented the in-line reviews, and I also went ahead and purged all the here links from the 3 cheatsheets (intro r, intro sc, advanced sc) since it was moving brackets around. The only TBD is this comment which I wasn't quite sure what you meant? #663 (comment)

Copy link
Member

@jashapiro jashapiro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good! But since we are apparently moving the links, I made them bigger and more specific.

I also realized we don't have syntax \(x){} anywhere, which we should. Somewhere. I don't care too much about where, but made a suggestion.

Also, maybe TOCs?

module-cheatsheets/intro-to-R-tidyverse-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/intro-to-R-tidyverse-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/intro-to-R-tidyverse-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/intro-to-R-tidyverse-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/intro-to-R-tidyverse-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-cheatsheet.md Outdated Show resolved Hide resolved
@@ -24,12 +24,16 @@ Read the Base `R` documentation [**here**](https://rdrr.io/r/).
| Base `R`| [`<-function(x) { <code> }`](https://adv-r.hadley.nz/functions.html) | Function | Creates a function that would take the defined parameters as input and execute the commands within the curly braces |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I realized that we don't have a link to the \() anywhere... I don't know if this is the right place, but we should put it somewhere... Maybe with purrr? Docs here: https://rdrr.io/r/base/function.html

@sjspielman
Copy link
Member Author

This has been updated in a couple ways:

  • I added cheatsheet links to the advanced cheatsheet, but not to the intro, under the assumption that we'll do a cheatsheet overall organizing by topic in the not distant future and can update all around at that time
  • For all PDF links, I added language that they are downloads
  • Added TOCs via doctoc and copy/pasting
  • Added a code chunk showing anonymous function syntax, feedback appreciated there! The example I chose is inspired by things we do in the integration instruction notebook

I also decided to think a little bit about PDF export, whose current status quo (please enjoy the blame view here and the most recent commit 🥴) is not my favorite - a little too manual, and MacDown is no longer being maintained if this issue is any indication. I ended up settling on the markdown-pdf VS Code extension, with some css to override mediocre font colors in module-cheatsheets/assets/markdown-pdf.css. I quite like the look of these cheatsheets, and they are at least more reproducible than what we've been doing! If reviewers are on board, I'll file a subsequent PR to update instructions for PDF export. For fun, reviewers may also appreciate this commit 3ff00fd and infer the silly journey I had along the way 😄

Copy link
Member

@jashapiro jashapiro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks good, with a few minor comments below.

On the subject of conversion; I agree that moving away from MacDown is a good goal, but I don't think moving to another interactive tool is necessarily the way we should go about this. I might rather have a little script that renders to html with rmarkdown then converts that to pdf via pandoc or some other scriptable tool. I don't think this PR is the place to spend our time on it.

module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
module-cheatsheets/scRNA-seq-advanced-cheatsheet.md Outdated Show resolved Hide resolved
@sjspielman
Copy link
Member Author

then converts that to pdf via pandoc or some other scriptable tool.

I'll just note that if this involves a custom LaTeX template, that's all you.... I will revert to Macdown-exported PDFs, but will state for the record I find those versions way less attractive than what markdown-pdf gives.

@jashapiro
Copy link
Member

then converts that to pdf via pandoc or some other scriptable tool.

I'll just note that if this involves a custom LaTeX template, that's all you.... I will revert to Macdown-exported PDFs, but will state for the record I find those versions way less attractive than what markdown-pdf gives.

No latex! I was thinking whatever is being used under the hood here, maybe with a conda environment to install it.

I'm fine with leaving these as they are here. I just don't want to get into encoding & documenting a new method that may be similarly brittle.

Copy link
Member

@jashapiro jashapiro left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A couple more suggestions for rendering

@sjspielman
Copy link
Member Author

@jashapiro I had missed the TOC and PDF re-render for the intro cheatsheet. Can I get a thumbs here for changes made in f103eb5 and 4795e88 ?

@jashapiro
Copy link
Member

@jashapiro I had missed the TOC and PDF re-render for the intro cheatsheet. Can I get a thumbs here for changes made in f103eb5 and 4795e88 ?

👍🏼

@sjspielman sjspielman merged commit 415d13a into master Mar 6, 2023
@sjspielman sjspielman deleted the sjspielman/scAdvanced-cheatsheet branch March 6, 2023 20:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants