Sei¶
Sei predicts how a human SNV changes 40 sequence classes of regulatory activity, such as enhancer, promoter and Polycomb classes, derived from its predictions for 21,907 chromatin profiles (hg19 or hg38).
| Kind | Container model; type = "SEI" |
| Install | pip install altar-sei (PyPI) |
| Genome builds | hg19, hg38 |
| Variant classes | SNVs |
| Compute | An NVIDIA GPU per batch; up to 16 GB of memory per task |
| Image | riyavsinha/altar-sei@sha256:e6522cdf…, pinned by digest. linux/amd64, 3.2 GB compressed, pulled anonymously from Docker Hub on first use |
| Validation | Upstream parity (CPU) (Validation) |
| Licence | Academic and research use only; Zenodo archive lists CC BY 4.0 |
| Upstream | Code, Weights, Paper |
When to use it¶
- Use Sei to ask which kind of regulatory activity an SNV changes, as one of 40 sequence classes such as an enhancer, promoter or Polycomb class. The classes summarize 21,907 chromatin profiles from more than 1,300 cell lines and tissues.
- Select the opt-in
chromatin_profile_effectsartifact when you need the effect on each of the 21,907 profiles, not only on the classes (Outputs). - Choose ChromBPNet or Cherimoya to ask how a variant changes accessibility in one experiment, at base resolution, or to score indels.
- Choose Enformer, Borzoi or AlphaGenome to reach gene expression.
- The official Sei code and model are for academic and research use only (Cite and licence).
Add it to a run¶
[models.sei]
type = "SEI"
[models.sei.configuration]
weights = { uri = "...", digest = "sha256:..." } # required, resource: replace the example
projection_vectors = { uri = "...", digest = "sha256:..." } # required, resource: replace the example
histone_indices = { uri = "...", digest = "sha256:..." } # required, resource: replace the example
sequence_class_names = { uri = "...", digest = "sha256:..." } # required, resource: replace the example
- Install the binding:
pip install altar-sei. - Download
sei_model.tar.gz(3.3 GB) from the official Zenodo record and extract it. The files are in itsmodel/directory. The binding has no fetch command. -
Name each file with its SHA-256 digest. These are the digests of the official files:
[models.sei] type = "SEI" [models.sei.configuration] weights = { uri = "model/sei.pth", digest = "sha256:9d4771d5363e4955eec2a36567fedac986191f64c7874c85bfb9e203c7f60783" } projection_vectors = { uri = "model/projvec_targets.npy", digest = "sha256:7080fd22e98b3bb47436801f94682d8b097a29f4d8c9cb154210e64e0e4190c8" } histone_indices = { uri = "model/histone_inds.npy", digest = "sha256:7a7af2c642ae6833ce2cee799a702a907544c0926c56b5c8b1236cd6470f5443" } sequence_class_names = { uri = "model/seqclass.names", digest = "sha256:5276a0a39f4d0364e22c5bb93d02e75c7c171f6e4b61fc47baa301fce9cc15b3" } -
Set
[variants] reference_fastato an hg19 or hg38 FASTA, and give the spec a[backend].
altar models sei lists the six primary columns, the sequence_class_effects detail table, the
chromatin_profile_effects artifact and the output selection that writes it, the configuration fields and the
default image. Score variants with a model walks through a run.
Outputs¶
| Column | Type | Meaning | Units and reading |
|---|---|---|---|
top_class_index |
int | Index with largest absolute class effect | 0 to 39 |
top_class_label |
str | Published label with largest absolute effect | |
top_class_effect |
float | Signed nucleosome-adjusted alternate-minus-reference projection score | signed; positive means the alternate allele raises the class score |
max_abs_class_effect |
float | Absolute value of the largest-magnitude sequence-class effect | 0 or more |
n_classes_scored |
int | Sequence-class effect rows emitted for the variant: 40, or 0 for a variant the runtime could not score | count |
contains_unk |
bool | Whether the scored reference window contained at least one N encoded uniformly across bases | true or false |
The primary table has one row per variant. top_class_index and top_class_label name the class with the largest
absolute effect, and top_class_effect is that class's effect.
For each SNV, the runtime predicts the 21,907 chromatin profiles for the reference and the alternate sequence, on
both strands, and averages the strands. It then applies FunctionLab's published sc_hnorm_varianteffect:
- sum the histone-profile predictions of each allele;
- scale each allele's histone profiles to the mean of the two sums;
- project the adjusted profiles onto the published sequence-class vectors;
- report adjusted alternate minus adjusted reference for the first 40 classes.
The adjustment comes before the projection. Projecting first, or plain alt - ref, gives different numbers.
sequence_class_effects¶
A detail table, version 0.0.1: All 40 official nucleosome-adjusted Sei sequence-class variant effects.
| Column | Type | Meaning |
|---|---|---|
class_index |
int | Zero-based published class index |
class_label |
str | Published short class label |
class_name |
str | Published class description |
class_effect |
float | Signed nucleosome-adjusted alternate-minus-reference projection score |
The table keeps all 40 class effects per variant, one row per class. A variant the runtime could not score has no rows. Read it as Read a run's results describes.
chromatin_profile_effects¶
| Artifact | chromatin_profile_effects, version 0.0.2 |
| Media type | application/x-npz |
| One file per | batch |
| Contents | One NumPy .npz archive per scoring batch: variant_ids (str, n), effects (float32, n x 21,907; the strand-averaged alternate-minus-reference prediction of every chromatin profile, before nucleosome adjustment, NaN for a variant the runtime could not score), profile_index (int32, 21,907; the model's output column of each effect), and profile_names (str, 21,907; the published name of each column's chromatin profile: line profile_index + 1 of the official target.names). |
The 21,907 profile predictions behind the class effects are not scores. A run keeps them only when it selects this
artifact. effects has one row per variant, in the order of variant_ids, and one column per profile, in the order
of profile_index.
Select it with the model's output, give target_names, and declare an [artifact_store]:
[models.sei.configuration]
# ... the four resources above, and:
target_names = { uri = "model/target.names", digest = "sha256:3a2cece0a7877dadb2c23e8fcaf57b25ef57523258437201785fde9e537376a9" }
[models.sei.output]
outputs = ["scores", "sequence_class_effects", "chromatin_profile_effects"]
reducer = "official_nucleosome_adjusted_sequence_class_effect_v1"
[artifact_store]
type = "storage"
Altar stores the file without reading it. Selecting the artifact changes the output selection, so the run stores
scores under a new identity and scores the cohort again. target_names is read by no score, so setting it alone
keeps stored scores. Select details and artifacts covers output
selection for every model.
Configuration¶
| Field | Type | Default | Meaning |
|---|---|---|---|
weights |
resource | required | The official checkpoint, sei.pth, with a SHA-256 digest. |
projection_vectors |
resource | required | The official sequence-class projection vectors, projvec_targets.npy, with a SHA-256 digest. |
histone_indices |
resource | required | The official list of histone profiles used for the nucleosome adjustment, histone_inds.npy, with a SHA-256 digest. |
sequence_class_names |
resource | required | The official names of the 40 sequence classes, seqclass.names, with a SHA-256 digest. |
target_names |
resource | not set | The official names of the 21,907 chromatin profiles, target.names, with a SHA-256 digest. Needed only for the chromatin_profile_effects artifact. Setting it keeps stored scores. |
image |
text | "riyavsinha/altar-sei@sha256:e6522cdf…" |
The scoring image, as name@sha256:<digest>. Tags are refused. |
Fields go under [models.<name>.configuration]. Each resource is the official file named in
Where it comes from, with its SHA-256 digest.
target_namesis needed only by thechromatin_profile_effectsartifact. A run that selects the artifact without it is refused.imagemust be aname@sha256:<digest>reference built fromruntimes/sei.- Strand averaging, the 4,096-base window, the 21,907 profiles, the 40 classes and the histone adjustment are fixed parts of the published scoring, not options.
Inputs¶
- Genome builds: hg19 and hg38, the two reference workflows of the official Sei repository.
- Variant classes: SNVs only. Batch preparation sets indels and multi-nucleotide variants aside and reports them. The runtime writes an invalid row for a non-SNV in a batch staged some other way, and Altar refuses to store it, which fails that batch.
- Window: 4,096 bases, Selene's even-length window, with the SNV at 0-based index 2,047.
- Reference:
[variants] reference_fasta. A REF that does not match the reference gives a row with null scores. - Unscorable variants: a variant without a complete 4,096-base window on its contig, a REF mismatch, or a window
base other than A, C, G, T or
Ngives a primary row with null scores,n_classes_scored0 and no class rows. The runtime logs the reason and scores the rest of the batch. Later runs count that variant as done. Nbases: encoded as 0.25 in each channel, as Selene does, and flagged incontains_unk.
Where it comes from¶
A Sei model instance names four official files by SHA-256 digest, and a fifth for the artifact:
| Configuration field | File | Holds |
|---|---|---|
weights |
sei.pth |
the 4,096-base sequence model for 21,907 chromatin profiles |
projection_vectors |
projvec_targets.npy |
the published sequence-class projection vectors |
histone_indices |
histone_inds.npy |
the profiles used for the histone adjustment |
sequence_class_names |
seqclass.names |
the ordered names of the 40 sequence classes |
target_names |
target.names |
the names of the 21,907 profiles; only for the artifact |
The binding has no fetch command. Download sei_model.tar.gz (3.3 GB) from the official Zenodo
record and extract it. The files are in its model/ directory. The
digests in Add it to a run and under chromatin_profile_effects
are the official files' digests; sha256sum checks your copy.
The runtime has a packaging command, sei-resources package. It checks the files, copies them to an output
directory and writes sei.resources.json with their digests. It lives in the Sei runtime, not in altar-sei, so
run it from runtimes/sei in a source checkout, or inside the default image:
docker run --rm --user "$(id -u):$(id -g)" -v "$PWD":/w \
riyavsinha/altar-sei@sha256:e6522cdfb01c3ea3ce3f2048a7d8cad0b40e61194a4952db0a41e9f25a2139c1 \
sei-resources package --model-dir /w/model --output-dir /w/sei-resources
A run spec cannot name that manifest. Copy its digests into [models.<name>.configuration].
Each resource's digest is its identity. Moving the same bytes to another location keeps every stored score. Other
files or another image store scores under a new identity. target_names is read by no score, so setting it keeps
stored scores.
Compute and scale¶
- GPU: each batch task asks for one NVIDIA GPU and up to 16 GB of memory. No GPU run is recorded (Validation).
- CPU: the runtime uses the CPU when no GPU is visible.
[backend] cpu_only = true(run spec) clears the GPU request. The validation ran this way: 21 variants took about 37 seconds in the container on a CPU host. - Scale: Altar splits the cohort into batches, and each batch is one retryable container task. The runtime loads the checkpoint once per task, streams the batch's variants and predicts in small batches. The profile artifact is streamed to its file, so its size does not limit the batch.
- Image:
linux/amd64, 3.2 GB compressed. It runs PyTorch 2.6 on Python 3.11.
Prioritization¶
A variant is prioritized when max_abs_class_effect >= 1. Sei publishes no such cutoff. This is a screening rule,
not a calibrated threshold. Calibrate it for your cohort and question before you rely on it. What prioritized
means explains how rules combine.
Validation¶
Validation label: Upstream parity (CPU). The default image matches the official
sei-framework at 1e16bff on 20 hg38 SNVs, with both on a CPU.
The 40 sequence-class effects agree within 7.1e-11, every top class matches, and the 21,907 profile effects of the
artifact agree within 3.0e-8. Record:
cpu-official-81f595f.json.
Not validated:
- any GPU run: no GPU smoke test and no GPU parity run is recorded;
- hg19;
- indels, which the binding does not score.
The validation status table lists every model.
Limits¶
- SNVs only.
- A variant without a complete window, or with a REF mismatch, gets null scores. Selene instead replaces a mismatching base with the VCF reference and flags it.
- The primary row reports one class. Use
sequence_class_effectsto compare classes. - The prioritization rule is a screening rule, not a calibrated threshold.
Cite and licence¶
Cite the Sei paper, and the Zenodo record of the model archive you downloaded:
@article{chen2022sei,
author = {Chen, Kathleen M. and Wong, Aaron K. and Troyanskaya, Olga G. and Zhou, Jian},
title = {A sequence-based global map of regulatory activity for deciphering human genetics},
journal = {Nature Genetics},
volume = {54},
number = {7},
pages = {940--949},
year = {2022},
doi = {10.1038/s41588-022-01102-2}
}
@misc{chen2021seimodel,
author = {Chen, Kathleen},
title = {Sei framework sequence model},
version = {0.0.0},
publisher = {Zenodo},
year = {2021},
doi = {10.5281/zenodo.4906997}
}
10.5281/zenodo.4906997 is the archive's only version; 10.5281/zenodo.4906996, which this page links, resolves
to its latest version.
- Code: the Sei framework is licensed for academic and research use only. Princeton University's Office of Technology Licensing handles commercial use.
- Model archive: the Zenodo record lists CC BY 4.0. The archive also holds the model code, which the framework licence covers.
- Runtime image: built from
runtimes/seiin the Altar repository. The runtime's model and scoring code implements the Sei framework and carries its academic-and-research-only licence,UPSTREAM_LICENSE.txt. The image also bundles PyTorch and other third-party packages under their own licences. It contains no weights. Confirm that your use and any redistribution of the resources meet these terms. - Binding:
altar-seiis MIT-licensed. It contains no Sei code or weights.
Python and extension¶
SeiConfiguration holds the five resources and image. altar_sei.DEFAULT_IMAGE is the default image, and an
image must be a name@sha256:<digest> reference. SeiPlugin.profile_effects_output is the output selection that
writes the artifact. To build your own image, see
runtimes/sei/README.md, and set image
to the pushed digest. Models and plans is the API reference for the model interface it
implements.
The scoring plan has one GPU task per batch. Each resource is staged to a fixed path, and the runtime checks it against its digest before it loads it.