Glyph: Mechanistic Science
Domain-Agnostic Hypothesis Generation using Sparse Autoencoders
Glyph is a Python toolkit for discovering interpretable features and generating scientific hypotheses from multimodal data. It uses Sparse Autoencoders (SAEs) to learn interpretable features, then conducts Phenome-Wide Association Studies (PheWAS) to identify and rank hypotheses.
📄 Paper: MechSci: Scaling Clinical Science via Mechanistic Interpretability of Multimodal Medical Foundation Models — Agents4Science 2025
Click to watch the video presentation
Features
- Sparse Autoencoders with TopK activation and Matryoshka nested dictionaries
- Ghost Gradient Recovery to prevent dead features during training
- PheWAS Analysis for systematic hypothesis testing
- Statistical Rigor with odds ratios, confidence intervals, and AUC metrics
- GPU Acceleration for large-scale analysis
- Domain Agnostic - works with any structured data (images, tabular, etc.)
Installation
# Clone the repository
git clone https://github.com/yourusername/glyph.git
cd glyph
# Install in development mode
pip install -e .
Quick Start
from glyph import Glyph
# Define your configuration overrides
config = [
"data.metadata=/path/to/metadata.csv",
"data.input_cols=[image_path]",
"data.outcome_cols=[disease]",
"data.embedding_map={image_path: resnet18}",
"data.cache_dir=./cache",
"data.output_dir=./outputs",
"seed=42",
]
# Initialize Glyph
ms = Glyph(config_path='config', config_overrides=config)
# Option 1: Run full pipeline
results = ms() # Equivalent to ms.fit().hypothesis_search()
# Option 2: Run in stages
ms.fit() # Extract embeddings, train SAE, compute linear probes
ms.hypothesis_search() # Run PheWAS study
# Access results directly
print(f"Embeddings: {list(ms.embeddings.keys())}")
print(f"SAE models: {list(ms.sae_models.keys())}")
print(f"PheWAS hypotheses: {len(ms.phewas_results)}")
Pipeline Overview
Raw Data → Embeddings → SAE Training → Sparse Features → PheWAS → Ranked Hypotheses
ms.fit() - Steps 1-4
- Embedding Extraction: Extract dense representations using pretrained models (e.g., ResNet18)
- Linear Probe: Evaluate embedding quality for outcome prediction (AUC)
- SAE Training: Learn sparse, interpretable features with TopK activation
- SAE Linear Probe: Evaluate sparse feature quality for outcome prediction
ms.hypothesis_search() - Step 5
- PheWAS Study: Test all sparse feature-outcome associations
- Computes odds ratios, confidence intervals, and AUC for each feature
- Filters by minimum activation count for statistical reliability
- Ranks hypotheses by odds ratio
Example Output
[PheWAS Results]
Total hypotheses: 162
Outcome class balance (train):
outcome: 2436/3295 positive (73.9%), 859/3295 negative (26.1%)
Top 10 hypotheses (by train odds ratio):
──────────────────────────────────────────────────────────────────────────────────────────
Feature Train OR Test OR AUC % AUC Count
──────────────────────────────────────────────────────────────────────────────────────────
feature_98 3.75 3.96 0.796 60.0% 2818
feature_61 3.45 3.34 0.773 55.2% 2524
feature_140 2.86 2.64 0.614 23.2% 674
...
──────────────────────────────────────────────────────────────────────────────────────────
- Train/Test OR: Odds ratio (how much the feature increases disease odds)
- AUC: Predictive power of this single feature
- % AUC:
(feature_auc - 0.5) / (embedding_auc - 0.5)- what % of embedding's predictive power this feature captures - Count: Number of samples where feature activates
Configuration
Glyph uses Hydra for configuration management.
Key Configuration Options
# Data settings
data:
metadata: /path/to/metadata.csv # CSV with sample IDs and file paths
input_cols: [image_path] # Columns containing input data paths
outcome_cols: [disease] # Columns containing outcomes to predict
embedding_map: {image_path: resnet18} # Map input columns to embedding models
cache_dir: ./cache # Cache directory for embeddings
output_dir: ./outputs # Output directory for results
# SAE settings
sae:
top_ks: [20] # TopK sparsity values to try
matryoshka: [2048] # Dictionary sizes (Matryoshka nesting)
max_steps: 5000 # Training steps
learning_rate: 0.0003 # Learning rate
# PheWAS settings
phewas:
min_activations: 25 # Minimum feature activations for hypothesis
top_n_print: 10 # Number of top hypotheses to display
Project Status
✅ Core Pipeline Complete
- Phase 1: Project structure
- Phase 2: Data loading (GlyphDataset, DataLoader)
- Phase 3: Embedding extraction (ResNet18, caching)
- Phase 4: SAE training (TopK, Matryoshka loss, ghost gradients)
- Phase 5: Linear probe (binary classification, regression)
- Phase 6: PheWAS analysis (odds ratios, AUC, ranking)
- Phase 7: Main Glyph class with fit/hypothesis_search API
- Phase 8: Examples
- Phase 9: Unit tests (83 tests passing)
- Phase 10: AutoInterp (interpretation with LLMs)
- Phase 11: Documentation
Running Tests
# Run all tests
python -m pytest tests/test*.py -v
# Run specific test module
python -m pytest tests/test6_sae.py -v
python -m pytest tests/test7_phewas.py -v
Inspiration
Glyph distills core algorithms from a larger medical hypothesis generation research codebase. Key innovations preserved:
- Matryoshka SAEs for multi-resolution feature learning
- Ghost Gradients for dead feature recovery
- TopK Activation for interpretable sparse codes
- Rigorous Statistics with odds ratios and confidence intervals
License
MIT License - see LICENSE for details.
Citation
If you use Glyph in your research, please cite:
@software{glyph2025,
title = {Glyph: Domain-Agnostic Hypothesis Generation},
author = {Glyph Contributors},
year = {2025},
url = {https://github.com/yourusername/glyph}
}
Metadata
Release files for glyph-discovery 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| glyph_discovery-0.1.0.tar.gz | 72.2 kB | Without provenance | Details for glyph_discovery-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| glyph_discovery-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for glyph_discovery-0.1.0-py3-none-any.whl |
Total release size: 138.8 kB
Release files / glyph_discovery-0.1.0.tar.gz
| Download URL | glyph_discovery-0.1.0.tar.gz |
|---|---|
| Size | 72.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b93633e7d845d5451b69b36ebb09c3c2652c11065b55f18378702df63759eb67
|
|
BLAKE2b-256 checksum How to use checksums |
272c4322faf74621992929b9e8a664e1975c2aa6a6d345429746a1b58e0b0f1b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Release files / glyph_discovery-0.1.0-py3-none-any.whl
| Download URL | glyph_discovery-0.1.0-py3-none-any.whl |
|---|---|
| Size | 66.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1b85024b5870ccace4f327c1a6bad36ad754ba12866cb9de6c29d9e7251df1dc
|
|
BLAKE2b-256 checksum How to use checksums |
65ac81341fe388ab06d35bf3272b460339d3d8b1583c58207b725cea5d62077f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.9
|
Security for glyph-discovery 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.