Metadata-Version: 2.4
Name: glyph-discovery
Version: 0.2.0
Summary: Domain-agnostic hypothesis generation using sparse autoencoders
Author-email: Robbie Holland <robbie.holland@stanford.edu>
License-Expression: MIT
Project-URL: Homepage, https://github.com/StanfordMIMI/Glyph
Project-URL: Repository, https://github.com/StanfordMIMI/Glyph
Keywords: sparse autoencoders,mechanistic interpretability,hypothesis generation,phewas,medical imaging
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: torchvision>=0.15.0
Requires-Dist: pytorch-lightning>=2.0.0
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: scikit-learn>=1.3.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: networkx>=3.0
Requires-Dist: umap-learn>=0.5.4
Requires-Dist: pillow>=9.5.0
Requires-Dist: pyarrow>=12.0.0
Requires-Dist: hydra-core>=1.3.0
Requires-Dist: omegaconf>=2.3.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tqdm>=4.65.0
Provides-Extra: hf
Requires-Dist: transformers>=4.56.0; extra == "hf"
Requires-Dist: huggingface-hub>=0.23.0; extra == "hf"
Requires-Dist: safetensors>=0.4.0; extra == "hf"
Provides-Extra: browser-tests
Requires-Dist: pytest>=7.0.0; extra == "browser-tests"
Requires-Dist: playwright>=1.45.0; extra == "browser-tests"
Provides-Extra: confounders
Requires-Dist: xgboost>=2.0.0; extra == "confounders"
Provides-Extra: zoo
Requires-Dist: huggingface-hub>=0.23.0; extra == "zoo"
Provides-Extra: ct
Requires-Dist: torch>=2.6.0; extra == "ct"
Requires-Dist: torchvision>=0.21.0; extra == "ct"
Requires-Dist: huggingface-hub>=0.23.0; extra == "ct"
Requires-Dist: merlin-vlm>=0.0.7; extra == "ct"
Requires-Dist: monai>=1.3.0; extra == "ct"
Requires-Dist: nibabel>=4.0; extra == "ct"
Provides-Extra: text
Requires-Dist: huggingface-hub>=0.23.0; extra == "text"
Requires-Dist: transformers>=4.51.0; extra == "text"
Provides-Extra: labs
Requires-Dist: huggingface-hub>=0.23.0; extra == "labs"
Provides-Extra: autointerp
Requires-Dist: google-genai>=1.0.0; extra == "autointerp"
Provides-Extra: tracking
Requires-Dist: wandb>=0.15.0; extra == "tracking"
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <img src="https://raw.githubusercontent.com/StanfordMIMI/Glyph/main/Glyph.svg" alt="Glyph" width="100%">
</p>

# Glyph

Glyph automates discovery in foundation-model embeddings. It learns sparse
concepts, searches for associations with outcomes, and summarizes its findings
in interactive visualizations and concise reports. Use it on your own data,
or apply the pretrained concept dictionaries released with the paper.

## Demos

See Glyph run on public images, with executed notebooks, interactive concept maps
and illustrated reports.

| Demo | Notebook | PDF report | Interactive HTML |
| --- | --- | --- | --- |
| [Skin-lesion diagnosis](https://github.com/StanfordMIMI/Glyph/blob/main/demos/pad_ufes/README.md) · 1,373 patients, clinical baseline | [Open notebook](https://github.com/StanfordMIMI/Glyph/blob/main/demos/pad_ufes/demo.ipynb) | [View report](https://github.com/StanfordMIMI/Glyph/blob/main/demos/pad_ufes/report.pdf) | [Get HTML](https://github.com/StanfordMIMI/Glyph/blob/main/demos/pad_ufes/explorer.html) |
| [Chest X-ray mortality](https://github.com/StanfordMIMI/Glyph/blob/main/demos/sbu_cxr/README.md) · 948 patients, clinical baseline | [Open notebook](https://github.com/StanfordMIMI/Glyph/blob/main/demos/sbu_cxr/demo.ipynb) | [View report](https://github.com/StanfordMIMI/Glyph/blob/main/demos/sbu_cxr/report.pdf) | [Get HTML](https://github.com/StanfordMIMI/Glyph/blob/main/demos/sbu_cxr/explorer.html) |
| [Handwritten digits](https://github.com/StanfordMIMI/Glyph/blob/main/demos/dinov3_digits/README.md) · 1,000 images, ten digit labels | [Open notebook](https://github.com/StanfordMIMI/Glyph/blob/main/demos/dinov3_digits/demo.ipynb) | [View report](https://github.com/StanfordMIMI/Glyph/blob/main/demos/dinov3_digits/report.pdf) | [Get HTML](https://github.com/StanfordMIMI/Glyph/blob/main/demos/dinov3_digits/explorer.html) |

GitHub displays the notebooks and PDFs. Download an HTML file and open it in your
browser to use the interactive explorer.

## Install

```bash
pip install "glyph-discovery[hf,zoo]"
```

The source repository is [StanfordMIMI/Glyph](https://github.com/StanfordMIMI/Glyph).

For the paper's pretrained dictionaries, install the matching encoder extra:
`pip install "glyph-discovery[zoo,ct]"`, `"glyph-discovery[zoo,text]"`, or `"glyph-discovery[zoo,labs]"`.
Model weights download when needed. DINOv3 requires approved access to its
[HF checkpoint](https://huggingface.co/facebook/dinov3-vits16-pretrain-lvd1689m).

## Learn new concepts

```python
from glyph import Glyph

glyph = Glyph(config_path='config', config_overrides=[
    'data.metadata=/path/to/metadata.csv',
    'data.input_cols=[image_path]',
    'data.outcome_cols=[pneumonia]',
    'data.embedding_map={image_path: "hf:facebook/dinov3-vits16-pretrain-lvd1689m"}',
    'data.embedding_model_kwargs={image_path: {input_type: image, pooling: cls}}',
])

glyph.fit()
glyph.hypothesis_search()
glyph.visualize(outcome='pneumonia', split='test')
```

The metadata supplies study IDs, image paths, and outcome labels. `fit` favors
sparse SAE configurations using validation reconstruction R² and warns below
0.85. `hypothesis_search` tests concept–outcome associations; `visualize` shows
an interactive concept space with association statistics and significant
concepts highlighted. Node area reflects activation prevalence, and correlation
links are visible by default with at most eight per concept. Confounder adjustment and automated interpretation are
optional. Labels are not required for learning and exploring concepts.

For a small text encoder, use `qwen3-embedding-0.6b`. Other HF models and your
own models can specify their preprocessing and embedding output; see the
[encoder guide](https://github.com/StanfordMIMI/Glyph/blob/main/docs/hf_embeddings.md).

## Extract the paper's concepts on your data

```python
from glyph import Glyph

# 1. EXTRACT A SINGLE PUBLISHED CONCEPT ON YOUR DATA
ct = Glyph.from_pretrained('ct-merlin')
i87 = ct.measure('I87', metadata='ct_metadata.csv')

# Optionally select one study by its ID in your metadata.
i87 = ct.measure('I87', metadata='ct_metadata.csv', sample_id='scan_001')

# 2. EXTRACT THE FULL PRETRAINED CONCEPT SPACE ON YOUR DATA
labs = Glyph.from_pretrained('labs-loinc')
concepts = labs.measure(metadata='labs_metadata.csv')
labs.visualize()

# Select an individual concept from the measured space.
l127 = concepts['L127']
```

`ct_metadata.csv` contains `sample_id` and `image_path` (CT NIfTI paths).
`labs_metadata.csv` contains `sample_id` and `labs_path` (prepared laboratory JSON
paths); see [lab preparation](https://github.com/StanfordMIMI/Glyph/blob/main/docs/extraction.md#labs-release-bundle) for raw LOINC data.

`from_pretrained` loads the published SAE. `measure` computes the matching
foundation-model embeddings on your data, then applies that SAE. No labels,
SAE training, or train/test splits are needed. Repeated requests reuse measured
studies; missing studies are encoded when requested.

A single concept returns a Series indexed by study ID. Whole-space extraction
returns all 8,192 original concept columns in a DataFrame. The explorer shows
concepts active in your cohort and available published interpretations; labels
are needed for association testing and significance highlighting.

Bundles are `ct-merlin`, `findings-qwen3`, and `labs-loinc`. Each preserves the
paper's normalization and concept indices and uses the original matching encoder.
See [extraction and saved runs](https://github.com/StanfordMIMI/Glyph/blob/main/docs/extraction.md) for supplied embeddings,
reloading, and input options.

## Run through a coding agent

The package includes skills for using Glyph, literature comparisons, interactive
HTML, and brief visual reports. Install them for your coding agent:

```bash
glyph skills install --agent claude   # or --agent codex
glyph skills list
```

Then ask, for example:

```text
Run Glyph on my cohort.
Metadata: /path/to/metadata.csv
Inputs: image_path
Outcome: pneumonia
Encoder: hf:facebook/dinov3-vits16-pretrain-lvd1689m, using CLS pooling.

Report reconstruction R², draw the concept map, and list associated concepts
with odds ratios and Bonferroni significance. Compare against source-backed
literature markers and produce a brief visual report.

If my inputs match a modality in the paper, apply its pretrained concepts with
the matching encoder instead of fitting a new dictionary, and assess the
associations in my cohort.
```

Interpretation through Gemini/Vertex and supplementary literature search through
Paperclip are optional and require configured access. Numerical analyses and
visualization do not require an LLM key.

[Documentation](https://github.com/StanfordMIMI/Glyph/blob/main/docs/README.md) · [Agent harnesses](https://github.com/StanfordMIMI/Glyph/blob/main/docs/literature.md) ·
[Remote HTML viewing](https://github.com/StanfordMIMI/Glyph/blob/main/docs/html_explorer.md)
