Saved outputs

mosa train asks the selected model to write its results to model.output_dir. The library uses a common Parquet convention for latent representations and reconstructions, while model files, logs, and exported splits depend on the implementation.

A custom model implements its own exports; the interface does not create these files automatically.

VAE checkpoints and logs¶

A run with a validation split and checkpoint_top_k > 0 writes:

<output_dir>/
├── checkpoints/
│   ├── last.ckpt
│   └── mosa-epoch=NNN-val_loss=N.NNNN.ckpt
├── lightning_logs/version_N/
│   ├── metrics.csv
│   └── hparams.yaml
├── train/
├── val/
└── full/

Each exported split holds latent.parquet and recon_<view>.parquet. model.inference: true adds inference/. last.ckpt records the end of training; the other monitored checkpoints retain the best validation epochs up to checkpoint_top_k.

With evaluation.test_size: 0, there is no validation, early stopping, val/, or monitored checkpoints/last.ckpt. Lightning may save an unmonitored checkpoint under its log directory. checkpoint_top_k: 0 also disables monitored checkpoints. Through Python, model.save(path) can explicitly save a fitted model to .ckpt or .pt.

Checkpoints include data and model configuration, fitted preprocessing, and category information. The Parquet conventions are described below.

MOFA model file¶

mofa_model.hdf5 stores the model and adapter preprocessing metadata. Its neighbouring full/ directory contains fitted-sample exports. Projection and reconstruction on the input scale require the saved preprocessing record.

Parquet layout¶

A split directory uses these filenames:

full/
├── latent.parquet
├── recon_gexp.parquet
└── recon_meth.parquet

latent.parquet is indexed by sample ID, with one column per latent dimension or retained factor.

Each recon_<view>.parquet has one row per sample and one column per feature, using the input feature names and order. Current implementations return supported reconstructions on the original input scale, after reversing their fitted preprocessing.

import pandas as pd

z = pd.read_parquet("outputs/experiment-01/full/latent.parquet")
x_hat = pd.read_parquet("outputs/experiment-01/full/recon_gexp.parquet")
print(z.shape, x_hat.shape)

Reconstructions include estimates for missing entries. Use the input masks to compare predictions with observed measurements.

Splits¶

For the MOSA VAE, train/ and val/ correspond to the fitting split, while full/ includes both. Use full/ for cohort-wide coordinates; distinguish fitted and held-out samples when assessing reconstruction.

For MOFA, full/ contains only the samples passed to fitting. With a nonzero validation holdout, it excludes held-out samples because this backend does not export a separate validation split. Set evaluation.test_size: 0 to fit and export the entire cohort, or use transform to project additional samples.

The VAE's optional inference/ split changes the decoder's batch condition for conditional reconstruction. It is a separate export, not a held-out evaluation split.

Cross-validation and optimization¶

The cross-validate CLI prints pooled and per-fold scores, writes held-out recon_<view>.parquet files into model.output_dir, and writes history.csv when the model provides epoch history. Every row is reconstructed by the fold model that held that sample out. Fold models and their temporary directories are removed after scoring.

optimize prints the best parameters and score. It keeps neither fold models nor a persisted study, and does not train the final model. See Evaluation and optimization.

Projection and plots¶

transform writes latent.parquet directly into its --output directory, with optional recon_<view>.parquet files alongside it. It does not create a full/ subdirectory. Once predictions succeed, it replaces projection files and removes stale reconstruction Parquets in that directory.

plot adds plots/ and metrics/clustering_metrics.csv to a training output directory. See Analysis and plotting for their contents.

Use a separate directory for each run. A repeated training run can overwrite Parquet files while leaving earlier checkpoints and log versions in place.