Skip to main content

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

Video Presentation 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

  1. Embedding Extraction: Extract dense representations using pretrained models (e.g., ResNet18)
  2. Linear Probe: Evaluate embedding quality for outcome prediction (AUC)
  3. SAE Training: Learn sparse, interpretable features with TopK activation
  4. SAE Linear Probe: Evaluate sparse feature quality for outcome prediction

ms.hypothesis_search() - Step 5

  1. 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)

Source distribution for glyph-discovery 0.1.0
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)

Table of built distributions (wheels) for glyph-discovery 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page