Module to demonstrate using rOpenScPCA for clustering

[sjspielman]

Proposed analysis

Related to #775

We have written some core functionality for the rOpenScPCA package to perform and evaluate clustering.

We have discussed writing a module that demonstrates using the functions in this package. The purpose of this Discussion is to plan some of the content in that module.

Scientific goals

The module should show contributors how to do the following:

• Install the package and add it to renv (noting I'm currently looking into how precisely to do this).
  • The module itself will also use renv, since it's using the package!
• Demonstrate how to use the package to perform & evaluate clustering (no sweeping!) and add clustering results into an SCE and/or Seurat object, and explain associated steps. We might toss in a UMAP here too
• Demonstrate how to use the package to evaluate clustering parameters and select an optimal set of clusters for continued use. This will necessarily involve visualization.

Releasing this module will also provide us with some information into how contributors might use the package, which in turn will help guide potential next steps to package development (#731).

Methods or approach

• The module's README file can explain the overall context as an example module, as well as provide information on how to obtain & track the package (noting I'm currently playing around with renv for this)
• Each of the two demonstration flavors can be its own notebook. Some content may be repetitive, but that doesn't bother me since it will allow users can focus on the notebook that best matches their needs without too much clutter. That said I am not tied to having two notebooks if streamlining into 1 seems preferable to others.
• Before starting this module, we should probably merge rOpenScPCA into main. One reason for this is that the package is cooked enough to be merged into main! The other reason is, while playing around with installing, it appears the slash in the branch name (feature/ropenscpca) isn't our friend, and I couldn't debug this (I didn't try too hard though, since we want to merge anyways)....

  > remotes::install_github("AlexsLemonade/OpenScPCA-analysis/packages/rOpenScPCA@feature/ropenscpca")
  Downloading GitHub repo AlexsLemonade/OpenScPCA-analysis@feature/ropenscpca
  Error in utils::download.file(url, path, method = method, quiet = quiet,  : 
    download from 'https://api.github.com/repos/AlexsLemonade/OpenScPCA-analysis/tarball/feature%2Fropenscpca' failed
  

Existing modules

This will use the rOpenScPCA package, which is not a module but lives in the top-level packages directory.

Input data

This module will use a single sample to scaffold the demonstration. Since we'd probably like the example to be realistic, it would make sense to use real (aka, not test) data here.

Scientific literature

N/A

Other details

This example module will be established and begin being built up this sprint (10/7 - 10/18).

[sjspielman]

Happily, installing and tracking with renv "just works" as expected:

renv::install("repo/path/to/package")
renv::snapshot()

The one wrinkle is there appears to be a creds-related bug in older versions of renv. The current version 1.0.10 installs as expected, but older versions (I previously had 1.0.7) don't work.

So, we should include instructions here to ensure renv is up-to-date, which can be accomplished with renv::update(packages="renv") as needed.

[jashapiro]

I had no trouble installing with renv 1.0.7, aside from the usual gitcreds complaint.

renv::install("AlexsLemonade/OpenScPCA-analysis/packages/rOpenScPCA@feature/ropenscpca")

Separately, any updating of renv should be done with renv::upgrade() as that will also update the activate script as required. This applies most within a given environment... base installs it does not matter.

[sjspielman]

Following some discussion, we've decided some things:

• This module will be named hello-clusters
• We'll use Ewings data, since we'd like the option to run a project through the example code too, and the Ewings project is small.