Clustering utility module

[sjspielman]

Proposed analysis

This proposed analysis module is adapted from the discussion #682 and focuses on only one of the previously proposed scientific goals:

Provide a module that can be flexibly used by OpenScPCA contributors to perform and/or evaluate clusters, which will overall improve object processing consistency across modules

I propose a module which will have a series of utility functions (as well as wrapper scripts/notebooks) that can be used to accomplish these complementary goals as related to graph-based clustering:

• perform clustering
• evaluate a given set of cluster assignments (e.g., bootstrap stability)
• assess a range of clustering parameters (e.g., silhouette width, purity)

The code should be written flexibly to take either an SCE or Seurat object and perform clustering on the object's normalized matrix. The module will make heavy use of bluster as the main clustering engine.

This module can then be used in the following ways:

• First, we can run ScPCA libraries through the module with the goal of assessing a range of clustering parameters
  • For each object, a TSV file of clusters across parameters as well as a "QC" notebook visualizing cluster quality will be provided as results. Therefore, we'll need to include a module run script that also renders a template notebook with viz. Note that this clustering template notebook from the cell-type-ewings module may be useful!
  • Contributors can then review these reports manually to determine which set of clustering parameters is the "best," and read those cluster assignments in from the associated TSV.
• Second, contributors should be able to leverage the code in this module to integrate into their own module. As such, we should include a decent amount of documentation w/ examples to explain how to use the module.
  • As part of this, we should consider adding wrapper functions for common groups of tasks (e.g., perform clustering and evaluate it via bootstrap), but we can figure out details here as the core functions get built up first

Scientific goals

The goal of this analysis is to provide a unified suite of functions that contributors can use to support their clustering analyses, as well as provide clustering labels themselves across parameter sweeps which contributors might directly leverage in their analysis.

Methods or approach

This module will primarily use bluster to perform clustering, as well as as functionality from other common bioc/R packages to assess clustering and visualize results.

Note that this module is going to be written in R; in the future we may have a complementary Python module, but for now the TSV results that the module exports allow results to be more agnostic as to R vs Python and hopefully generally usable from either framework.

Existing modules

N/A

Input data

Eventually, all ScPCA data

Scientific literature

No response

Other details

No response

[sjspielman]

Another organizational approach might end up being cleaner in the end - rather than a single module defining all utility functions/templates and processing ScPCA data, we might instead write two modules:

• A module called cluster-utils which will contain all functions/templates, but is not intended to be run "standalone"
• A module called evaluate-scpca-clusters which uses code in cluster-utils to run over ScPCA libraries.

Another benefit to this approach is that folks can see the utils module "in action" by referring to the second module listed above.

[sjspielman]

A module called cluster-utils which will contain all functions/templates, but is not intended to be run "standalone"

But, we'd still want testing scripts that would run standalone! This may mean just having scripts for the purposes of running functions in CI for testing.

[jashapiro]

At this point it sounds like you are describing a package. I wonder if we might just want to go all the way there, for namespacing reasons if nothing else. I don't think the overhead of R packages is too bad, and it might be worth it for this use case. It also provides a nice structure for initial docs.

If you do want to go that way, I'd probably pull it from analyses to a separate root directory for common code/packages (still within this repo, not a whole separate repo).

[sjspielman]

I am very into this idea, since it is indeed more or less what I'm describing.

If you do want to go that way, I'd probably pull it from analyses to a separate root directory for common code/packages (still within this repo, not a whole separate repo).

I expect contributors would ultimately use this module by adding the package to renv. The syntax to install it would be (assuming it lives in a root directory packages)

renv::install("AlexsLemonade/OpenScPCA-analysis:packages/cluster-utils")

using a : for the subdirectory, and maybe toss in an @ for permalinking (but not sure if @ goes after repo name or at the end).

Either way this is a pretty focused package, so it's a good use case for trying out writing OpenScPCA packages more generally.

[jashapiro]

I wonder whether it might be simpler to make a single OpenScPCAtools package that we could add functions to as needed? (Pretty sure we can't have a dash in the package name, so we need something else.)

[maximilianh]

Is visualization of the clusters a concern? If so, we could add an option to our cell browsers to load these new tsv files on demand and add to the UI. Just an idea. May take a while to implement. Also, we currently only have permission to show the acute myeoloid leukemo datasets of the OpenScPCA on the cell browser: https://cells-test.gi.ucsc.edu/?ds=acute-myeloid-leuk

…

Message ID: <AlexsLemonade/OpenScPCA-analysis/repo-discussions/727/comments/10488085@ github.com>

[sjspielman]

Hi @maximilianh, thanks for your interest here! At this point, we're actually refocusing to first write a general package (see #731) that will include some clustering utility functions. The clustering results we'd ultimately get out of this might benefit from interactive visualization, but I'm not sure how widely it would get used in the end and it seems like a lot of effort for an unknown about of use! If it turns out that many folks end up wanting to look through the clustering reports we get, then maybe we'll talk more about how to make those results more accessible :)

[maximilianh]

We can actually visualize anything, gene expression and any attributes that are numbers or strings, for the cells. It takes us about 30 minutes to update all cell browsers if your change the meta data attributes for the cells, if we can get them in a structured format (e.g. list of .tsv files, first column is cellId, any other columns, first header row has the label).

…

On Tue, Sep 3, 2024 at 5:11 AM Stephanie Spielman ***@***.***> wrote: Hi @maximilianh <https://github.com/maximilianh>, thanks for your interest here! At this point, we're actually refocusing to first write a general package (see #731 <#731>) that will include some clustering utility functions. The clustering results we'd ultimately get out of this might benefit from interactive visualization, but I'm not sure how widely it would get used in the end and it seems like a lot of effort for an unknown about of use! If it turns out that many folks end up wanting to look through the clustering reports we get, then maybe we'll talk more about how to make those results more accessible :) — Reply to this email directly, view it on GitHub <#727 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AACL4TLLB3VWKILUDPMQBX3ZUWRNNAVCNFSM6AAAAABNGPUWTCVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTANJTGE2DCNI> . You are receiving this because you were mentioned.Message ID: <AlexsLemonade/OpenScPCA-analysis/repo-discussions/727/comments/10531415@ github.com>

[sjspielman]

See the related discussion #731!