Metadata-Version: 2.4
Name: mmmvae
Version: 1.0.0
Summary: MMMVAE: Multi‑Modal Metabolic Variational Auto‑Encoder for spatial transcriptomics
Author-email: TianMiaoMiao <Tmm18846175562@163.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/TianMiaoMiaoWorkspace/MMMVAE
Project-URL: Bug Tracker, https://github.com/TianMiaoMiaoWorkspace/MMMVAE/issues
Keywords: spatial‑transcriptomics,metabolism,variational‑autoencoder,bioinformatics
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.23
Requires-Dist: torch>=2.0
Requires-Dist: pandas>=1.5
Requires-Dist: scanpy>=1.9
Requires-Dist: matplotlib>=3.6
Requires-Dist: scikit-learn>=1.2
Requires-Dist: tqdm
Dynamic: license-file

# MMMVAE
Multi‑Modal Metabolic Variational Autoencoder
## Installation
Install from PyPI:
pip install mmmvae#
## Input file hierarchy
```markdown

```text
args.root/
    {sample}_coords.txt
    {sample}_scores.txt
    {sample}_adj_matrix.txt
    {sample}_counts.txt
    {sample}_neighbor_means_counts.txt
    {sample}_exp.txt 
    {sample}_flux.txt
    {sample}_balance.txt

Single-cell will not input the "neighbor_means_counts.txt" file
 ```  

## Output file hierarchy:
```markdown
args.output_root/
    output_root/
        {sample}_lesion_prob.csv
        {sample}_python_clusters.csv
        {sample}_GMM_BICAIC.pdf
        {sample}_Importance.pdf
        {sample}_spatial_cluster.pdf


``` 

## Usage
```markdown
mmmvae -h
usage: mmmvae [-h] --sample SAMPLE [--species {Homo_sapiens,Mus_musculus}] [--test_file TEST_FILE]
              [--moduleGene_file MODULEGENE_FILE] [--stoichiometry_matrix STOICHIOMETRY_MATRIX]
              [--cName_file CNAME_FILE] [--output_flux_file OUTPUT_FLUX_FILE]
              [--output_balance_file OUTPUT_BALANCE_FILE] --root ROOT [--output_root OUTPUT_ROOT]
              [--datatype {Spatial,single_cell}] [--epochs EPOCHS] [--n_clusters_range N_CLUSTERS_RANGE] [--seed SEED]
              [--n_components N_COMPONENTS] [--custom_colors CUSTOM_COLORS]

MMMVAE: Multi-Modal Metabolic Variational Autoencoder

options:
  -h, --help            show this help message and exit
  --sample SAMPLE       Sample name of input files, which is also used to name the output files
  --species {Homo_sapiens,Mus_musculus}
                        Species: 'Homo_sapiens'(human) or 'Mus_musculus'(mouse). Default: Homo_sapiens
  --test_file TEST_FILE
                        Tab‑separated gene profile matrix input file. Row is gene symbol, column is single‑cell or
                        spatial spot. Default: {sample}_exp.txt under --root.
  --moduleGene_file MODULEGENE_FILE
                        The table contains genes for each module. We provide human and mouse two models. For human
                        model, please use module_gene_m168.csv which is default. All candidate moduleGene files are
                        provided in /data/ folder.
  --stoichiometry_matrix STOICHIOMETRY_MATRIX
                        The table describes relationship between compounds and modules. Each row is an intermediate
                        metabolite and each column is metabolic module. For human model, please use cmMat_c70_m168.csv
                        which is default. All candidate stoichiometry matrices are provided in /data/ folder.
  --cName_file CNAME_FILE
                        Built‑in compound name table csv.This table contains the names of the compounds and their
                        corresponding identifiers. Specifically, the first row represents the names of the compounds,
                        and the second row shows the corresponding identifiers. Default: cName_c70_m168.csv
  --output_flux_file OUTPUT_FLUX_FILE
                        Filename for predicted flux output. Default: {sample}_flux.txt
  --output_balance_file OUTPUT_BALANCE_FILE
                        Filename for predicted balance output. Default: {sample}_balance.txt
  --root ROOT           The data directory for input data. The root includes Spatial folder, filtered_count_matrix
                        folder or filtered_feature_bc_matrix.h5. The Spatial folder includes
                        tissue_positions_list.csv, tissue_hires_image.png, tissue_lowres_image.png and
                        scalefactors_json.json. The filtered_count_matrix folder includes barcodes.tsv.gz,
                        features.tsv.gz, and matrix.mtx.gz
  --output_root OUTPUT_ROOT
                        Output directory for MMMVAE results storing output matrices. Default: {root}/output
  --datatype {Spatial,single_cell}
                        The data type input by the user, either 'single_cell' or 'Spatial'. Default: Spatial
  --epochs EPOCHS       Training epochs. Default: 100
  --n_clusters_range N_CLUSTERS_RANGE
                        Upper bound for niche‑cluster search. Algorithm searches optimal k from 2 to this value.
                        Default: 15
  --seed SEED           Random seed for reproducibility. Default: 2026
  --n_components N_COMPONENTS
                        Manually set fixed number of metabolic niche clusters, skip automatic BIC‑based optimal‑k
                        selection.
  --custom_colors CUSTOM_COLORS
                        Comma‑separated hex color strings for plotting metabolic ecotypes, e.g.: ['#83fc8d',
                        '#7c7afa'].

``` 
## Test:
```markdown
#Local installation
cd ./MMMVAE
conda activate mmmvae_env
pip install -e . 

#Online installation
pip install mmmvae

mmmvae -h
mmmvae --sample spatial_exampleDATA  --species Mus_musculus --datatype Spatial  --root .\r_preprocess\example\spatial_exampleDATA\mmmvaeinput 
``` 


## Test output
```markdown
(mmmvae_env) D:\Desktop\MMMVAE>mmmvae --sample spatial_exampleDATA  --species Mus_musculus --datatype Spatial  --root .\r_preprocess\example\spatial_exampleDATA\mmmvaeinput
scFEA start...
Load data done.
D:\Desktop\MMMVAE\src\mmmvae\MMMVAE.py:327: FutureWarning: The behavior of DataFrame concatenation with empty or all-NA entries is deprecated. In a future version, this will no longer exclude empty or all-NA columns when determining the result dtypes. To retain the old behavior, exclude the relevant entries before the concat operation.
  geneExprDf = pd.concat([geneExprDf, temp], ignore_index=True, sort=False)
Process data done.
Starting train neural network...
100%|████████████████████████████████████████████████████████████████████████████████| 100/100 [01:28<00:00,  1.14it/s]
Training time: 88.08639144897461
Starting load data...
Starting process data...
Active modalities: ['score', 'balance', 'flux', 'counts', 'neighbor']
Starting training...
Epoch 000 | Loss=7.5302 | Recon=7.5302 | KL=0.2742 |
Epoch 020 | Loss=5.0009 | Recon=4.8414 | KL=0.7976 |
Epoch 040 | Loss=4.8495 | Recon=4.4950 | KL=0.8864 |
Epoch 060 | Loss=4.4985 | Recon=4.1121 | KL=0.6440 |
Epoch 080 | Loss=4.3076 | Recon=3.8563 | KL=0.5642 |
 BIC and AIC Plotting...
Auto-selected best n_components = 11 (min BIC)
Process data done:

================ GMM Model Selection =================
[INFO] BIC/AIC curve has been saved to:
.\r_preprocess\example\spatial_exampleDATA\mmmvaeinput\output\spatial_exampleDATA_GMM_BICAIC.pdf
[INFO] Please check this file to determine the optimal number of clusters.
[INFO] If you do not specify --n_components, the model will use the BIC-optimal value.
=====================================================

[AUTO] n_components is not provided. Using BIC-optimal value: 11
.\r_preprocess\example\spatial_exampleDATA\mmmvaeinput\output\spatial_exampleDATA_spatial_cluster.pdf

``` 
