Adaptive Multi-View Fusion based clustering

🛠 Requirements

Please ensure your environment meets the following dependencies:

• Python == 3.7.0
• Torch == 1.13.1
• NumPy == 1.21.6
• Pandas == 1.1.5
• SciPy == 1.7.3
• Scikit-learn == 0.22.2

Installation

You can install the required packages using pip:

pip install torch==1.13.1 numpy==1.21.6 pandas==1.1.5 scipy==1.7.3 scikit-learn==0.22.2

---

📂 Data Availability

We evaluated scEGG on several benchmark single-cell datasets. The original data sources can be accessed via the links below:

Dataset	Source / Accession	Link
Darmanis	PubMed 26060301	PubMed
Bjorklund	GSE70580	NCBI GEO
Sun	GSE128066	NCBI GEO
Marques	PubMed 30078729	PubMed
Zeisel	PubMed 25700174	PubMed
Fink	PubMed 35914526	PubMed

---

🧬 Gene Representation Construction

To fully utilize the scEGG framework, it is essential to construct exogenous gene representations before training the model. These embeddings introduce external biological knowledge (e.g., from PPI networks) to guide the clustering process.

Detailed instructions and scripts for generating these embeddings can be found in the guide:
👉 Produce_Gene_Emb.md

Example: Generating Embeddings for Bjorklund

To run scEGG on the Bjorklund dataset, you must first generate the corresponding gene embedding file (Bjorklund.emb).

1. Prepare Data: Ensure the Bjorklund dataset is correctly placed in the data directory.
2. Run Generation Script: Follow the instructions in Produce_Gene_Emb.md to process the gene interaction network.
3. Output: The process will yield a Bjorklund.emb file.

Note: Ensure the generated .emb file matches the dataset name specified in your configuration (e.g., Bjorklund) so the model can load it automatically.

---

🚀 Usage

1. Configuration

The model parameters can be configured via command-line arguments. Key arguments (e.g., dataset name, number of clusters) are defined in the parser:

Add other arguments as needed...

**Implement:**

```python
# Example configuration
parser.add_argument('--dataset_str', default='Bjorklund', type=str, help='Name of the target dataset')
parser.add_argument('--n_clusters', default=4, type=int, help='Expected number of clusters')
# ... additional arguments ...

2. Execution

To run the scEGG model with the default configuration:

python run_scEGG.py

New method: AMVF

I added an improved clustering method in code/run_amvf.py called Adaptive Multi-View Fusion (AMVF).

• It combines an expression view, a sparse binary-program view, a TF-IDF rarity view, and an optional gene-embedding view.
• It uses a stronger stacked multi-view latent as the default representation, with only light confidence-based calibration.
• It runs with standard numpy/pandas/scikit-learn dependencies.

Example:

python code/run_amvf.py \
  --data_path data/Bjorklund/Bjorklund_data.csv \
  --label_path data/Bjorklund/label.ann \
  --embedding_path data/Bjorklund/Bjorklund.emb \
  --n_clusters 4 \
  --output_path result/bjorklund_amvf_predictions.tsv

Benchmark the classical baselines against AMVF on Bjorklund:

python code/benchmark_bjorklund.py

Additional notes:

• code/run_scEGG.py now runs on CPU.
• code/Nmetrics.py no longer depends on the external munkres package.
• Method notes are in docs/literature_review.md and docs/amvf_method.md.

Standardized cell-type mappings

I added code/build_standardized_mappings.py to standardize cell identifier to label metadata across the datasets in this workspace.

It writes:

• result/standardized_celltype_mappings.tsv for the combined table.
• result/standardized_celltype_mapping_summary.tsv for dataset coverage.
• per-dataset files under result/standardized_mappings/.

The standardized columns are:

• dataset_id
• sample_id
• cell_id
• cell_barcode
• cell_type
• label_kind
• label_source
• label_status

Run it with:

python code/build_standardized_mappings.py

Cross-dataset benchmark

I added code/benchmark_other_datasets.py to run the same baseline family used in the Bjorklund benchmark on the other labeled datasets in data/datasets/.

• Methods: KMeans-PCA, Agglomerative-PCA, Spectral-kNN, and AMVF.
• Output: result/other_dataset_benchmark.tsv.
• For larger datasets, the script uses a deterministic stratified subset so all baselines remain comparable and feasible.

Run it with:

python code/benchmark_other_datasets.py --max_cells 2000