Extend functions (e.g., Cluster_Stats_All_Samples) to support data.frame and data.table inputs

[lisch7]

Hi,

First of all, thank you for developing scCustomize — it’s an excellent package and very useful in my daily workflow.

I’ve noticed that several functions in the package (for example, Cluster_Stats_All_Samples) are currently limited to accepting Seurat object inputs. While this works well, many of these functions could easily operate on a data.frame that already contains the required information. When using the seurat object when sub subsets are needed, the operation takes more time. It is better to use sce@meta.data directly.

I think it would greatly improve flexibility if these functions could also support data.frame or data.table inputs. Additionally, instead of relying exclusively on seurat_object@active.ident, a new argument could be added to specify which column should be used as the cluster identity.

A simple code is attached:

if (class(object)=="Seurat"){
    data <- object@meta.data
  } else if (class(object)=="data.frame") {
    data <- as.data.frame(object)
  } else {
    stop("'object' is not a Seurat object or a data frame.")
  }

This small enhancement would make scCustomize more general and easier to integrate into broader R workflows beyond Seurat.

[samuel-marsh]

Hi @lisch7,

Thanks so much for kind words. I'm definitely ok extending Cluster_Stats_All_Samples to support data.frame inputs and could rework some to just pull meta.data if needed. However, generally speaking using Seurat objects (or just the meta data) as starting points provides a lot of backend safety in terms of all data being present and formatted correctly etc. This significantly reduces the checks needed internally in function to ensure it works properly (and error messages are informative) vs. externally generated data.frames.

Also not sure exactly what this means and wondering if you can explain more what you mean by: "When using the seurat object when sub subsets are needed, the operation takes more time. It is better to use sce@meta.data directly"?

What other functions besides Cluster_Stats_All_Samples were you thinking of in terms of using data.frame as input?

I'm also happy regardless of changes to add additional parameter to Cluster_Stats_All_Samples to support use of alternative meta.data column for the identity.

Best,
Sam

[samuel-marsh]

I would also note that generally speaking I would love to enable scCustomize support of SingleCellExperiment objects I currently don't have the bandwidth to make such additions and it is not currently on my roadmap due to the bandwidth required.

However, if you (or anyone else in community reading this) are interested in creating PR to add SCE support I'm very happy to support such efforts.

Best,
Sam

[lisch7]

Hi Sam,

I think functions that rely on metadata, such as Median_Stats, MAD_Stats, Plot_Median_var, and so on, could also be extended to support data.frame inputs. I completely agree that using Seurat objects provides much better backend safety and helps avoid many potential errors. However, this requirement can also limit the flexibility of these otherwise excellent functions.

For example, if I process my data in Python and only want to visualize results in R, I need to convert AnnData to a Seurat object first. But in many cases—such as when I only need to examine cluster proportions—working directly with the metadata would be sufficient. In my workflow, once the data are annotated, I usually prefer using the combined dataset to generate all the required plots, except for those that specifically depend on embedding data (e.g., DimPlot). In such cases, using a plain data frame is actually more convenient than a Seurat object, since it takes up much less memory and allows for more flexible and faster manipulation.

In fact, Cluster_Stats_All_Samples is a very powerful and versatile function. The calculated proportions can be used in many downstream visualizations, and compared with repeatedly writing long chunks of code to calculate per-sample cluster proportions or add grouping variables, using Cluster_Stats_All_Samples is much simpler, cleaner, and easier to maintain. Supporting data.frame inputs would also make it easy to wrap the entire workflow into a standardized and reusable analysis pipeline.

Moreover, in some analyses, I might want to calculate cluster proportions within a major cell type (e.g., CD4T cells rather than the entire TME). Currently, I would need to subset all CD4T cells from the Seurat object and then rerun Cluster_Stats_All_Samples. However, when dealing with large datasets, this subsetting process can be time-consuming and resource-wasting. In fact, all that’s really needed for this calculation is the subset of meta.data, which is much lighter and allows faster computation.

Thanks