This repository contains research scripts used for quantitative multiscale structural phenotyping of hepatocytes in three-dimensional expansion microscopy datasets. The analyses include cell and mitochondrial segmentation, global cell morphology, membrane curvature, mitochondrial morphology and skeleton analysis, dimensionality reduction, and multiscale classification of oncogenic phenotypes.
Qionghua Shen et al. Deciphering the Multiscale Morphology of Somatic Oncogenic Alterations in Hepatocellular Carcinoma. bioRxiv (2026). https://doi.org/10.64898/2026.07.15.738764 (bioRxiv version 1)
Please cite the preprint when using or adapting these scripts.
This repository is an archival release of the research scripts used to perform the quantitative analyses described in the preprint. It is provided primarily for methodological transparency and to facilitate adaptation of the analysis workflows.
The analyses were performed in a mixed computing environment. Most computational analyses were run on a Linux-based institutional cluster, while portions of the image-segmentation workflow were performed on a Windows workstation in the laboratory. Consequently, some scripts retain hardcoded input and output paths and directory conventions from the original computing environments. Users must update these paths and provide appropriately structured input data before running the scripts.
This repository is not currently distributed or validated as a turnkey, platform-independent, end-to-end software package.
The repository contains selected scripts for:
- preprocessing volumetric fluorescence images;
- refining cell segmentations;
- fusing precomputed orthogonal-view mitochondrial masks into 3D labels;
- extracting global cell morphology and membrane-curvature features;
- quantifying mitochondrial morphology and skeleton organization;
- assessing segmentation quality;
- visualizing mitochondrial feature relationships; and
- integrating multiscale features for oncogenic-state classification.
Some workflows begin with precomputed two-dimensional segmentation masks, completed three-dimensional label volumes, or previously extracted feature tables. The repository does not reproduce every interactive segmentation or model-inference step from raw microscopy data.
| Directory | Purpose | Typical starting input | Principal manuscript outputs |
|---|---|---|---|
Cell_Segmentation |
Rescale and refine cell labels with raw-image-guided filtering | Precomputed 3D cell labels and corresponding raw volumes | Figure 2 and Figure S2 workflows |
Global_Cell_Morphology |
Extract global geometric features and perform PCA, correlation, and permutation analyses | 3D cell masks or extracted feature tables | Figure 2E-G and Figure S3 |
Curvature_Analysis |
Generate surface meshes and quantify membrane-curvature distributions | 3D cell masks | Figure 2H-K and Figure S4 |
Mitochondria_Segmentation |
Preprocess mitochondrial images and fuse orthogonal 2D masks into 3D labels | Raw volumes and precomputed XY, XZ, and YZ masks | Figure 3 and Figure S5 workflows |
Mitochondria_Analysis |
Quantify mitochondrial size, shape, skeletons, and segmentation quality | 3D mitochondrial label volumes | Figure 3D-K and Figure S5-S6 |
Visualization |
Generate UMAP embeddings and group-distance summaries | Extracted mitochondrial feature tables | Figure 3L-M |
Classification |
Construct pseudo-bulk samples and evaluate multiscale classifiers | Cell, curvature, and mitochondrial feature tables with sample identifiers | Figure 4B-E |
The scripts reflect the environments in which the study was analyzed:
- Linux-based institutional compute cluster for most computational analyses;
- Windows laboratory workstation for portions of the segmentation workflow;
- Python 3.10 for Python-based processing, analysis, and visualization; and
- MATLAB R2023b for the included global cell morphology workflow.
Not every script has been independently tested on both Linux and Windows. Absolute paths use syntax from the environment in which an individual script was run.
Python package requirements are listed in
requirements.txt and environment.yml.
Use these files as dependency references when preparing a dedicated Python
3.10 environment. Automated environment creation from environment.yml was
not validated successfully in a fresh test; install dependencies manually for
your platform and confirm the required imports before running the analyses.
For external research packages, use the authoritative project documentation
linked below.
Several workflows also depend on external research software:
- micro-SAM for model-assisted or interactive 2D segmentation;
- u-Segment3D for multiview segmentation fusion, refinement, and guided filtering; and
- u-Unwrap3D for cell-surface mesh generation and membrane-curvature analysis.
Install these packages according to their authoritative project documentation. GPU acceleration is recommended for model-assisted segmentation of large image volumes, but is not generally required for downstream feature extraction, statistics, or plotting.
Input requirements differ across directories. Depending on the analysis stage, a script may require:
- a raw 3D fluorescence image;
- precomputed XY, XZ, and YZ 2D segmentation masks;
- a fused or postprocessed 3D label volume;
- an Excel workbook containing image or sample paths;
- a table of per-cell or per-mitochondrion features; or
- biological sample identifiers used to define grouped cross-validation.
Review the configuration section near the beginning of each script before running it. In particular, replace or verify:
- absolute Linux or Windows paths;
- input and output directories;
- spreadsheet filenames, worksheet names, and column names;
- voxel dimensions and expansion factors;
- fluorescence-channel assignments;
- sample identifiers; and
- segmentation, filtering, and statistical parameters.
Parameters that depend on image sampling, expansion, labeling, or signal-to-noise ratio should not be transferred unchanged to unrelated datasets.
The full volumetric microscopy datasets are not stored in this Git repository because of their size. As described in the preprint, a representative subset of the data will be archived upon publication; remaining imaging data are available from the corresponding author upon reasonable request.
These scripts document the analyses performed for the study, but the repository has not yet been validated as a single end-to-end workflow on an independent computing system. Exact reproduction additionally requires the source images, intermediate segmentations, sample metadata, and software versions used in the study.
This software is available for academic research use under the terms described
in LICENSE.md. Commercial use and redistribution for commercial
purposes are prohibited.
Questions about the scripts or requests for clarification can be submitted through the repository's GitHub Issues.