scMethyl + RNA Multi-omics SeekSoul Online Platform Jupyter Analysis User Guide
This guide is intended for users who have completed the standard SeekMethyl pipeline analysis and want to perform downstream customized analysis in the Jupyter environment of the SeekGene Bio Cloud Platform.
This document uses the example project {project_name} (project ID {project_id}, sample {sample_name}) to demonstrate the operation path.
In actual use, replace these placeholders with your real project information.
1. Start Jupyter customized analysis
1.1 Open the project details page
After logging in to the SeekGene Bio Cloud Platform, go to:
Resource Overview → My Projects
Find the target project in the project list, for example:
- Project ID:
{project_id} - Project name:
{project_name}
Click View on the right side of the project to enter the project details page.
1.2 Start JupyterLab
On the upper-right corner of the project details page, click Customized Analysis.
Click Quick Run. A resource configuration pop-up window will appear. Select the appropriate compute resources. After startup is complete, click Quick Run again, and the platform will automatically redirect to JupyterLab.
Common resource configurations:
| Resource configuration | Recommended scenario |
|---|---|
| 4 cores 32 GB | Result viewing, small-scale plotting, lightweight table processing |
| 8 cores 64 GB | Routine single-cell object processing and basic integration analysis |
| 16 cores 128 GB | Larger sample sets, multimodal integration, differential analysis |
| 32 cores 256 GB | Large object analysis, complex CNV analysis, or large-scale multi-omics analysis |
To change resources, select Reset Resources from Operations in the lower-right corner of JupyterLab.
Note: Reset Resources will terminate the current Jupyter instance and start a new one. Before doing this, save all notebooks, scripts, and generated results. Unsaved content will be lost.
1.3 Common JupyterLab areas
After entering JupyterLab, the commonly used areas are:
| Area | Function |
|---|---|
| Left file browser | Browse directories, open notebooks, upload or download files |
| Launcher | Create a new Notebook, Terminal, or other interactive interface |
| Lower-right Operations menu | Mount pipeline data, summarize data, access the template library, upload templates, extend time, reset resources, or close the page |
1.4 Lower-right Operations menu
The Operations menu in the lower-right corner of JupyterLab contains commonly used platform functions.
| Function | Description |
|---|---|
| Mount pipeline data | Pipeline data are not mounted by default. When pipeline results are needed, use Mount Pipeline Data to select and mount the relevant pipeline tasks. To unmount data, deselect the corresponding pipeline task. |
| Summarize data | Summarize data under /home/{username}/workspace/project/{username}/ and its subfolders to the corresponding pipeline Result Overview page. |
| Template library | Download platform-provided Notebook templates. Templates downloaded from the template library are saved to /home/{username}/workspace/project/{username}/. |
| Upload template | Upload .ipynb files located under /home/{username}/workspace/project/{username}/ and its subfolders. |
| Reset resources | Terminate the current Jupyter instance and start a new one. Before doing this, save all notebooks, scripts, and analysis results. Unsaved content will be lost. |
| Close page | Terminate the current Jupyter instance. Before closing, save all notebooks, scripts, and analysis results. Unsaved content will be lost. |
| Extend time | Extend the Jupyter session time. This operation can be performed multiple times, and each extension is added to the current remaining time. |
2. Working directories and pipeline data mounting
2.1 Working directory description
Two main directories are used in Jupyter: the project disk and the data disk.
| Directory type | Path | Description | Recommended use |
|---|---|---|---|
| project disk | /home/{username}/workspace/project/{username}/ | User-specific writable directory | Save customized analysis outputs such as notebooks, scripts, figures, tables, h5ad files, and rds files |
| data disk | /home/{username}/workspace/data/{mount_id}/ | Mounted pipeline result directory | Read standard pipeline output data |
It is recommended that all user-generated results be saved to:
/home/{username}/workspace/project/{username}/It is not recommended to write customized analysis results directly to the data disk. The data disk is mainly used as a read-only directory for standard pipeline results.
2.2 Storage and collaboration notes
- The total storage limit for all project personal working directories under
/home/{username}/workspace/project/{username}/is 500 GB. - Members of the same project can view analysis results generated by other members, for example:
/home/{username}/workspace/project/{OtherUsers}/Therefore, do not store sensitive information or large temporary files unrelated to the project in the project directory.
2.3 Mount pipeline data
SeekMethyl standard pipeline results do not appear in the Jupyter file system by default. They need to be mapped to the current Jupyter environment through Mount Pipeline Data.
Steps:
- Click Operations in the lower-right corner.
- Select Mount Pipeline Data.
- Select the pipeline task you want to use.
- Confirm the mount operation.
To unmount already mounted data, enter Mount Pipeline Data again and deselect the corresponding pipeline task.
After mounting, you can check the mounted data in Terminal:
ls -lh /home/{username}/workspace/data/The mounted SeekMethyl results are usually located at:
/home/{username}/workspace/data/{mount_id}/methylation/{task_directory}/The result directory for a single sample is usually:
/home/{username}/workspace/data/{mount_id}/methylation/{task_directory}/{sample_name}/Example:
cd /home/{username}/workspace/data/{mount_id}/methylation/{task_directory}/{sample_name}/
ls -lh3. Mounted data contents
3.1 Sample-level mounted directory structure
After mounting, the sample-level standard data currently provided by SeekMethyl for Jupyter downstream analysis are organized into the following five directory types:
allcools_generate_datasets
cnvPreflight
filtered_feature_bc_matrix
methscan
split_bamsExample structure:
{sample_name}/
├── allcools_generate_datasets
│ └── {sample_name}.mcds
│ ├── chrom10k
│ ├── chrom20k
│ ├── chrom50k
│ ├── chrom100k
│ ├── chrom500k
│ ├── chrom1M
│ ├── chrom_sizes.txt
│ └── geneslop2k
├── cnvPreflight
│ ├── copykit_{sample_name}_1Mb.rds
│ ├── copykit_{sample_name}_1Mb.rds.md5
│ ├── copykit_{sample_name}_500kb.rds
│ ├── copykit_{sample_name}_500kb.rds.md5
│ ├── copykit_{sample_name}_220kb.rds
│ └── copykit_{sample_name}_220kb.rds.md5
├── filtered_feature_bc_matrix
│ ├── barcodes.tsv.gz
│ ├── features.tsv.gz
│ └── matrix.mtx.gz
├── methscan
│ └── compact_data
│ ├── *.npz
│ ├── cell_stats.csv
│ ├── column_header.txt
│ └── run_info.txt
└── split_bams
├── {sample_name}_cells.csv
└── filtered_barcode_reads_counts.csvThese five directory types are the standard mounted results currently provided by the platform for Jupyter and can be used as the data basis for subsequent SeekMethyl template tutorials. Different tutorials may use one or more of these data types depending on the analysis purpose. Some tutorials also use intermediate results generated by previous tutorials based on these data, such as adata_rna.h5ad, adata_met.h5ad, or DMR result files.
3.2 Description of the five standard mounted data types
| Directory | Data description | Main use |
|---|---|---|
filtered_feature_bc_matrix/ | RNA expression matrix | RNA quality control, dimensionality reduction, clustering, annotation, and differential expression analysis |
allcools_generate_datasets/{sample_name}.mcds/ | Single-cell methylation MCDS dataset generated by ALLCools | Basic methylation analysis, regional methylation aggregation, DMG/DMB analysis, and multimodal integration |
methscan/compact_data/ | Compressed methylation matrix required by MethSCAn | VMR detection and DMR analysis |
cnvPreflight/ | CNV pre-analysis objects | CNV visualization, tumor cell identification, and clone grouping |
split_bams/ | Single-cell barcode and read statistics | Cell-level quality control, read distribution checks, and auxiliary doublet assessment |
4. SeekMethyl downstream analysis template instructions
The platform provides commonly used Notebook templates for SeekMethyl downstream analysis. These templates are centrally available in the template library. Users can select and download the appropriate template based on their analysis purpose and complete the corresponding analysis in the Jupyter environment.
4.1 Download a template
In JupyterLab, click Operations in the lower-right corner and then select Template Library.
After entering the template library, set the type to Public and the product to SeekMethyl. Find the tutorial you need and click the download arrow in the lower-right corner.
After download, templates are saved by default to /home/{username}/workspace/project/{username}/. You can open the corresponding .ipynb file from this directory in the left file browser.
Templates are divided into Public and Private types:
| Template type | Description |
|---|---|
| Public | Public templates. Users with access permission can view and download them. |
| Private | Private templates. Only the creator can view and use them. |
4.2 Select a Kernel
Different tutorials depend on different runtime environments. After opening a Notebook, first select the recommended Kernel according to the tutorial overview table in Section 4.3.
Operation path:
Kernel → Change Kernel → select the recommended Kernel
4.3 Tutorial overview table
The tutorial files listed below correspond to the English templates in the notebooks/en/ directory.
| Analysis category | Tutorial file | Recommended Kernel | Standard input source | Main output |
|---|---|---|---|---|
| Doublet identification | scMethyl+RNA_Multi-omics_Doublet_Detection.ipynb | SeekMethy_py | filtered_feature_bc_matrix/, allcools_generate_datasets/{sample}.mcds/, split_bams/ | sample_doublet.txt, UMI distribution plot, methylation read distribution plot, doublet assessment plot |
| Basic integration analysis | scMethyl+RNA_Multi-omics_Basic_Analysis.ipynb | SeekMethy_py | filtered_feature_bc_matrix/, allcools_generate_datasets/{sample}.mcds/ | adata_rna.h5ad, adata_met.h5ad, QC plots, UMAP plots |
| MOFA+ multimodal integration | scMethyl+RNA_Multi-omics_Integration_MOFA+.ipynb | muon_env(py) | adata_rna.h5ad and adata_met.h5ad from the basic analysis output | MOFA+ latent factors and omics contribution results |
| WNN multimodal integration | scMethyl+RNA_Multi-omics_Integration_WNN.ipynb | muon_env(py) | adata_rna.h5ad and adata_met.h5ad from the basic analysis output | WNN UMAP and integrated clustering results |
| Differential analysis and functional enrichment | scMethyl+RNA_Multi-omics_Differential_Analysis_Functional_Enrichment_Analysis.ipynb | SeekMethy_py | adata_rna.h5ad, adata_met.h5ad, allcools_generate_datasets/{sample}.mcds/ | DEG, DMG, DMB, Venn plots, Circos plots, GO/KEGG enrichment plots |
| Between-group cell-type differential enrichment | scMethyl+RNA_Multi-omics_InterGroup_CellType_Differential_Enrichment_Analysis.ipynb | SeekMethy_py | adata_rna.h5ad, adata_met.h5ad, allcools_generate_datasets/{sample}.mcds/, grouping information | Between-group DEG, between-group DMG, volcano plots, Venn plots, Circos plots, GO/KEGG enrichment plots |
| MethSCAn differential methylation analysis | scMethyl+RNA_Multi-omics_MethSCAn_Differential_Methylation_Analysis.ipynb | common_r | methscan/compact_data/, cell grouping information | VMR, DMR, differential methylation region table |
| DMR functional enrichment | scMethyl+RNA_Multi-omics_DMR_Functional_Enrichment_Analysis.ipynb | common_r | DMR BED file generated by upstream analysis | rGREAT annotation results and GO/KEGG enrichment results |
| DMR motif enrichment | scMethyl+RNA_Multi-omics_DMR_Motif_Enrichment_Analysis.ipynb | common_r | DMR/VMR BED file generated by upstream analysis | HOMER motif enrichment results and candidate TFs |
| CNV copy number variation analysis | scMethyl+RNA_Multi-omics_CNV_Analysis.ipynb | SingleCell R | cnvPreflight/copykit_{sample}_1Mb.rds, 500kb.rds, or 220kb.rds | CNV heatmap, tumor cell identification results, and clone grouping results |
5. Custom environment creation and management
The platform provides commonly used Kernels required by SeekMethyl templates:
| Kernel | Main use |
|---|---|
SeekMethy_py | Basic methylation + RNA dual-omics analysis, differential analysis, and between-group analysis |
common_r | MethSCAn, DMR functional enrichment, and DMR motif analysis |
singlecell_r | CopyKit CNV analysis |
muon_env(py) | MOFA+ and WNN multimodal integration |
In general, you do not need to create your own environment when using the template tutorials. A custom environment is recommended only when you need to install additional software packages, fix specific package versions, or run custom scripts.
5.1 Create a custom R environment
Example: create an R environment named DemoR.
# 1. Create an R environment
micromamba create --prefix /jp_envs/envs_user/{UserId}/DemoR -y
# 2. Activate the environment
micromamba activate /jp_envs/envs_user/{UserId}/DemoR
# 3. Install the R kernel and common R packages
micromamba install -c conda-forge -c bioconda -c defaults r-base r-irkernel r-seurat -y
# 4. Start R
RRun the following commands in the R interactive interface:
Sys.setenv(PATH = paste("/home/mambauser/bin:/home/mambauser/env/jupyter/bin", Sys.getenv("PATH"), sep = ":"))
IRkernel::installspec(
name = "DemoR",
displayname = "DemoR",
prefix = "/jp_envs/kernels_user/{UserId}/"
)
q()After returning to Terminal, run:
jupyter kernelspec install /jp_envs/kernels_user/{UserId}/share/jupyter/kernels/demor --user
micromamba deactivateRefresh the Jupyter page. You should then see DemoR in the Kernel list.
5.2 Delete a custom R environment
jupyter-kernelspec remove demor
micromamba env remove --prefix /jp_envs/envs_user/{UserId}/DemoR5.3 Create a custom Python environment
Example: create a Python environment named DemoPython.
# 1. Create a Python environment
micromamba create --prefix /jp_envs/envs_user/{UserId}/DemoPython python=3.10 -y
# 2. Activate the environment
micromamba activate /jp_envs/envs_user/{UserId}/DemoPython
# 3. Install the Jupyter kernel and common Python packages
micromamba install -c conda-forge -c bioconda -c defaults ipykernel scanpy pandas numpy matplotlib -y
# 4. Install the Python Kernel
python -m ipykernel install \
--name DemoPython \
--display-name "DemoPython" \
--prefix /jp_envs/kernels_user/{UserId}/
# 5. Register it to the current user's Jupyter
jupyter kernelspec install /jp_envs/kernels_user/{UserId}/share/jupyter/kernels/demopython --user
# 6. Exit the environment
micromamba deactivateRefresh the Jupyter page. You should then see DemoPython in the Kernel list.
5.4 Delete a custom Python environment
jupyter-kernelspec remove demopython
micromamba env remove --prefix /jp_envs/envs_user/{UserId}/DemoPython5.5 Notes on custom environments
- Prefer platform-provided Kernels whenever possible.
- Do not modify package versions in public environments.
- Use independent names for custom environments to avoid overwriting existing environments.
- When installing additional software packages, record the installation commands for reproducibility.
- If dependency conflicts are severe, create a new environment instead of repeatedly overwriting packages in an existing environment.
6. FAQ
Q1: What should I do if I cannot find the /home/{username}/workspace/data/ directory?
First confirm whether pipeline data have been mounted:
Lower-right Operations → Mount Pipeline Data
Then check in Terminal:
ls -lh /home/{username}/workspace/data/If you still cannot see the corresponding mount ID, remount the pipeline data, or confirm whether the current project has available SeekMethyl pipeline results that can be mounted.
Q2: Where are templates saved after download?
Templates are saved by default to:
/home/{username}/workspace/project/{username}/You can open the Notebook from this directory in the left file browser.
Q3: What should I do if a Notebook cannot be saved?
Confirm whether the Notebook is located in the personal project directory:
/home/{username}/workspace/project/{username}/If the Notebook is created in a read-only directory or a mounted data directory, a Permission denied error may occur.
Q4: What should I do if resources are insufficient?
If memory is insufficient, execution is too slow, or the task is interrupted, click Operations in the lower-right corner and select Reset Resources. Then choose a higher resource configuration and restart Jupyter.
Note: Resetting resources will terminate the current Jupyter instance and start a new one. Before doing this, save all notebooks, scripts, and important results. Unsaved content will be lost.
Q5: What should I do if the session is about to end?
Click Operations in the lower-right corner and select Extend Time to extend the Jupyter session time. This operation can be performed multiple times, and each extension is added to the current remaining time.
Also save notebooks and output results to the project directory in time to avoid losing unsaved content due to browser closure, session interruption, or instance restart.
7. Technical support and issue reporting
If you encounter a problem, provide the following information to help with troubleshooting:
- Project ID:
{project_id} - Project name:
{project_name} - Sample name:
{sample_name} - Name of the Notebook used
- Kernel used
- Current input path
- Error screenshot or complete error text
- Whether pipeline data have been mounted
- Resource configuration used: CPU / memory
After analysis is complete, it is recommended to release compute resources through Operations in the lower-right corner → Close Page.