Skip to content

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_effects artifact 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
  1. Install the binding: pip install altar-sei.
  2. Download sei_model.tar.gz (3.3 GB) from the official Zenodo record and extract it. The files are in its model/ directory. The binding has no fetch command.
  3. 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" }
    
  4. Set [variants] reference_fasta to 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:

  1. sum the histone-profile predictions of each allele;
  2. scale each allele's histone profiles to the mean of the two sums;
  3. project the adjusted profiles onto the published sequence-class vectors;
  4. 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_names is needed only by the chromatin_profile_effects artifact. A run that selects the artifact without it is refused.
  • image must be a name@sha256:<digest> reference built from runtimes/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 N gives a primary row with null scores, n_classes_scored 0 and no class rows. The runtime logs the reason and scores the rest of the batch. Later runs count that variant as done.
  • N bases: encoded as 0.25 in each channel, as Selene does, and flagged in contains_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_effects to 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/sei in 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-sei is 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.