Add essential alphagenome source files only

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+*.ipynb filter=lfs diff=lfs merge=lfs -text

alphagenome/source

@@ -1 +0,0 @@
-Subproject commit b7d3963ce241c2390ea18bb99fa0722e1c169952

alphagenome/source/.gitattributes

@@ -0,0 +1 @@
+*.ipynb linguist-documentation

alphagenome/source/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+---
+name: Bug report
+description: >-
+  Report a bug or unexpected behavior to help us improve AlphaGenome.
+labels:
+- bug
+
+body:
+- type: markdown
+  attributes:
+    value: >
+      ## Thank you for helping us improve AlphaGenome!
+
+      * Please verify that your issue has not been reported using
+      [Issue search][issue search].
+
+      * If you have a question about usage, please
+      consider [starting a discussion][Discussions].
+
+      * If you prefer a non-templated issue report, click [here][Raw report].
+
+      [Discussions]: https://www.alphagenomecommunity.com/
+
+      [issue search]: https://github.com/google-deepmind/alphagenome/search?q=is%3Aissue&type=issues
+
+      [Raw report]: https://github.com/google-deepmind/alphagenome/issues/new?template=none
+- type: textarea
+  attributes:
+    label: Description
+    description: A concise description of the bug.
+    placeholder: |
+      Text may use markdown formatting.
+      ```python
+      # for codeblocks, use triple backticks
+      ```
+  validations:
+    required: true
+- type: textarea
+  attributes:
+    label: System info (python version, alphagenome version, etc.)
+    description: >-
+      Include the output of `import alphagenome; alphagenome.__version__`
+    placeholder: |
+      ```
+      ...
+      ```
+  validations:
+    required: true

alphagenome/source/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Have questions or need support?
+    url: https://www.alphagenomecommunity.com/
+    about: Please ask questions on our community forums.

alphagenome/source/.github/workflows/presubmit_checks.yml

@@ -0,0 +1,37 @@
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install alphagenome with dependencies
+        run: |
+            python -m pip install -U pip hatch
+      - name: Check
+        run: python -m hatch run check:all
+      - name: Unit tests
+        run: python -m hatch test

alphagenome/source/.github/workflows/release.yaml

@@ -0,0 +1,45 @@
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+name: Release
+
+on:
+  release:
+    types: [published]
+
+# Use "trusted publishing", see https://docs.pypi.org/trusted-publishers/
+jobs:
+  release:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/alphagenome
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          filter: blob:none
+          fetch-depth: 0
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.12
+      - name: Install hatch
+        run: python -m pip install -U pip hatch
+      - name: Build package
+        run: python -m hatch build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

alphagenome/source/.pylintrc

@@ -0,0 +1,458 @@
+# This Pylint rcfile contains a best-effort configuration to uphold the
+# best-practices and style described in the Google Python style guide:
+#   https://google.github.io/styleguide/pyguide.html
+#
+# Its original canonical open-source location is:
+#   https://google.github.io/styleguide/pylintrc
+#
+# Also includes some modifications specific to this repository.
+
+[MASTER]
+
+# Add files or directories to the ignore list. They should be base names, not
+# paths.
+ignore=third_party,
+       ./src/alphagenome/protos
+
+# Add files or directories matching the regex patterns to the ignore list. The
+# regex matches against base names, not paths.
+ignore-patterns=
+
+# Pickle collected data for later comparisons.
+persistent=no
+
+# List of plugins (as comma separated values of python modules names) to load,
+# usually to register additional checkers.
+load-plugins=
+
+# Use multiple processes to speed up Pylint.
+jobs=4
+
+# Allow loading of arbitrary C extensions. Extensions are imported into the
+# active Python interpreter and may run arbitrary code.
+unsafe-load-any-extension=no
+
+# A comma-separated list of package or module names from where C extensions may
+# be loaded. Extensions are loading into the active Python interpreter and may
+# run arbitrary code.
+extension-pkg-allow-list=
+
+# Minimum Python version to use for version dependent checks.
+py-version=3.10
+
+[MESSAGES CONTROL]
+
+# Only show warnings with the listed confidence levels. Leave empty to show
+# all. Valid levels: HIGH, INFERENCE, INFERENCE_FAILURE, UNDEFINED
+confidence=
+
+# Enable the message, report, category or checker with the given id(s). You can
+# either give multiple identifier separated by comma (,) or put this option
+# multiple time (only on the command line, not in the configuration file where
+# it should appear only once). See also the "--disable" option for examples.
+#enable=
+
+# Disable the message, report, category or checker with the given id(s). You
+# can either give multiple identifiers separated by comma (,) or put this
+# option multiple times (only on the command line, not in the configuration
+# file where it should appear only once).You can also use "--disable=all" to
+# disable everything first and then reenable specific checks. For example, if
+# you want to run only the similarities checker, you can use "--disable=all
+# --enable=similarities". If you want to run only the classes checker, but have
+# no Warning level messages displayed, use"--disable=all --enable=classes
+# --disable=W"
+disable=abstract-method,
+        apply-builtin,
+        arguments-differ,
+        attribute-defined-outside-init,
+        backtick,
+        bad-option-value,
+        basestring-builtin,
+        buffer-builtin,
+        c-extension-no-member,
+        chained-comparison,
+        cmp-builtin,
+        cmp-method,
+        coerce-builtin,
+        coerce-method,
+        consider-iterating-dictionary,
+        consider-using-enumerate,
+        consider-using-in,
+        delslice-method,
+        div-method,
+        duplicate-code,
+        eq-without-hash,
+        execfile-builtin,
+        file-builtin,
+        filter-builtin-not-iterating,
+        fixme,
+        getslice-method,
+        global-statement,
+        hex-method,
+        idiv-method,
+        implicit-str-concat-in-sequence,
+        import-error,
+        import-self,
+        import-star-module-level,
+        inconsistent-return-statements,
+        input-builtin,
+        intern-builtin,
+        invalid-field-call,
+        invalid-str-codec,
+        locally-disabled,
+        long-builtin,
+        long-suffix,
+        map-builtin-not-iterating,
+        metaclass-assignment,
+        misplaced-comparison-constant,
+        missing-function-docstring,
+        missing-module-docstring,
+        next-method-called,
+        next-method-defined,
+        no-absolute-import,
+        no-else-break,
+        no-else-continue,
+        no-else-raise,
+        no-else-return,
+        no-init,  # added
+        no-member,
+        no-name-in-module,
+        no-self-use,
+        nonzero-method,
+        not-an-iterable,  # false positives around dataclasses
+        not-callable,  # false positives for jax.jit
+        oct-method,
+        old-division,
+        old-ne-operator,
+        old-octal-literal,
+        old-raise-syntax,
+        parameter-unpacking,
+        print-statement,
+        raising-string,
+        range-builtin-not-iterating,
+        raw_input-builtin,
+        rdiv-method,
+        reduce-builtin,
+        relative-import,
+        reload-builtin,
+        round-builtin,
+        setslice-method,
+        signature-differs,
+        standarderror-builtin,
+        suppressed-message,
+        sys-max-int,
+        too-few-public-methods,
+        too-many-ancestors,
+        too-many-arguments,
+        too-many-boolean-expressions,
+        too-many-branches,
+        too-many-instance-attributes,
+        too-many-locals,
+        too-many-nested-blocks,
+        too-many-positional-arguments,
+        too-many-public-methods,
+        too-many-return-statements,
+        too-many-statements,
+        trailing-newlines,
+        unichr-builtin,
+        unicode-builtin,
+        unnecessary-comprehension,
+        unnecessary-lambda-assignment,
+        unnecessary-pass,
+        unpacking-in-except,
+        use-dict-literal,
+        useless-else-on-loop,
+        useless-object-inheritance,
+        useless-suppression,
+        using-cmp-argument,
+        wrong-import-order,
+        xrange-builtin,
+        zip-builtin-not-iterating,
+
+[REPORTS]
+
+# Set the output format. Available formats are text, parseable, colorized, msvs
+# (visual studio) and html. You can also give a reporter class, eg
+# mypackage.mymodule.MyReporterClass.
+output-format=text
+
+# Tells whether to display a full report or only the messages
+reports=no
+
+# Python expression which should return a note less than 10 (10 is the highest
+# note). You have access to the variables errors warning, statement which
+# respectively contain the number of errors / warnings messages and the total
+# number of statements analyzed. This is used by the global evaluation report
+# (RP0004).
+evaluation=10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)
+
+# Template used to display messages. This is a python new-style format string
+# used to format the message information. See doc for all details
+#msg-template=
+
+
+[BASIC]
+
+# Good variable names which should always be accepted, separated by a comma
+good-names=main,_
+
+# Bad variable names which should always be refused, separated by a comma
+bad-names=
+
+# Colon-delimited sets of names that determine each other's naming style when
+# the name regexes allow several styles.
+name-group=
+
+# Include a hint for the correct naming format with invalid-name
+include-naming-hint=no
+
+# List of decorators that produce properties, such as abc.abstractproperty. Add
+# to this list to register other decorators that produce valid properties.
+property-classes=abc.abstractproperty,cached_property.cached_property,cached_property.threaded_cached_property,cached_property.cached_property_with_ttl,cached_property.threaded_cached_property_with_ttl
+
+# Regular expression matching correct function names
+function-rgx=^(?:(?P<exempt>setUp|tearDown|setUpModule|tearDownModule)|(?P<camel_case>_?[A-Z][a-zA-Z0-9]*)|(?P<snake_case>_?[a-z][a-z0-9_]*))$
+
+# Regular expression matching correct variable names
+variable-rgx=^[a-z][a-z0-9_]*$
+
+# Regular expression matching correct constant names
+const-rgx=^(_?[A-Z][A-Z0-9_]*|__[a-z0-9_]+__|_?[a-z][a-z0-9_]*)$
+
+# Regular expression matching correct attribute names
+attr-rgx=^_{0,2}[a-z][a-z0-9_]*$
+
+# Regular expression matching correct argument names
+argument-rgx=^[a-z][a-z0-9_]*$
+
+# Regular expression matching correct class attribute names
+class-attribute-rgx=^(_?[A-Z][A-Z0-9_]*|__[a-z0-9_]+__|_?[a-z][a-z0-9_]*)$
+
+# Regular expression matching correct inline iteration names
+inlinevar-rgx=^[a-z][a-z0-9_]*$
+
+# Regular expression matching correct class names
+class-rgx=^_?[A-Z][a-zA-Z0-9]*$
+
+# Regular expression matching correct module names
+module-rgx=^(_?[a-z][a-z0-9_]*|__init__)$
+
+# Regular expression matching correct method names
+method-rgx=(?x)^(?:(?P<exempt>_[a-z0-9_]+__|runTest|setUp|tearDown|setUpTestCase|tearDownTestCase|setupSelf|tearDownClass|setUpClass|(test|assert)_*[A-Z0-9][a-zA-Z0-9_]*|next)|(?P<camel_case>_{0,2}[A-Z][a-zA-Z0-9_]*)|(?P<snake_case>_{0,2}[a-z][a-z0-9_]*))$
+
+# Regular expression which should only match function or class names that do
+# not require a docstring.
+no-docstring-rgx=(__.*__|main|test.*|.*test|.*Test)$
+
+# Minimum line length for functions/classes that require docstrings, shorter
+# ones are exempt.
+docstring-min-length=10
+
+
+[TYPECHECK]
+
+# List of decorators that produce context managers, such as
+# contextlib.contextmanager. Add to this list to register other decorators that
+# produce valid context managers.
+contextmanager-decorators=contextlib.contextmanager,contextlib2.contextmanager
+
+# Tells whether missing members accessed in mixin class should be ignored. A
+# mixin class is detected if its name ends with "mixin" (case insensitive).
+ignore-mixin-members=yes
+
+# List of module names for which member attributes should not be checked
+# (useful for modules/projects where namespaces are manipulated during runtime
+# and thus existing member attributes cannot be deduced by static analysis. It
+# supports qualified module names, as well as Unix pattern matching.
+ignored-modules=
+
+# List of class names for which member attributes should not be checked (useful
+# for classes with dynamically set attributes). This supports the use of
+# qualified names.
+ignored-classes=optparse.Values,thread._local,_thread._local
+
+# List of members which are set dynamically and missed by pylint inference
+# system, and so shouldn't trigger E1101 when accessed. Python regular
+# expressions are accepted.
+generated-members=
+
+
+[FORMAT]
+
+# Maximum number of characters on a single line.
+max-line-length=80
+
+# lines made too long by directives to pytype.
+
+# Regexp for a line that is allowed to be longer than the limit.
+ignore-long-lines=(?x)
+  (^\s*(import|from)\s
+   |\$Id:\s\/\/depot\/.+#\d+\s\$
+   |^[a-zA-Z_][a-zA-Z0-9_]*\s*=\s*("[^"]\S+"|'[^']\S+')
+   |^\s*\#\ LINT\.ThenChange
+   |^[^#]*\#\ type:\ [a-zA-Z_][a-zA-Z0-9_.,[\] ]*$
+   |pylint
+   |"""
+   |\#
+   |lambda
+   |(https?|ftp):)
+
+# Allow the body of an if to be on the same line as the test if there is no
+# else.
+single-line-if-stmt=yes
+
+# Maximum number of lines in a module
+max-module-lines=99999
+
+# String used as indentation unit.  The internal Google style guide mandates 2
+# spaces.  Google's externaly-published style guide says 4, consistent with
+# PEP 8.  Here, we use 2 spaces, for conformity with many open-sourced Google
+# projects (like TensorFlow).
+indent-string='  '
+
+# Number of spaces of indent required inside a hanging  or continued line.
+indent-after-paren=4
+
+# Expected format of line ending, e.g., empty (any line ending), LF or CRLF.
+expected-line-ending-format=
+
+
+[MISCELLANEOUS]
+
+# List of note tags to take in consideration, separated by a comma.
+notes=TODO
+
+
+[STRING]
+
+# This flag controls whether inconsistent-quotes generates a warning when the
+# character used as a quote delimiter is used inconsistently within a module.
+check-quote-consistency=yes
+
+
+[VARIABLES]
+
+# Tells whether we should check for unused import in __init__ files.
+init-import=no
+
+# A regular expression matching the name of dummy variables (i.e., expectedly
+# not used).
+dummy-variables-rgx=^\*{0,2}(_$|unused_|dummy_)
+
+# List of additional names supposed to be defined in builtins. Remember that
+# you should avoid to define new builtins when possible.
+additional-builtins=
+
+# List of strings which can identify a callback function by name. A callback
+# name must start or end with one of those strings.
+callbacks=cb_,_cb
+
+# List of qualified module names which can have objects that can redefine
+# builtins.
+redefining-builtins-modules=six,six.moves,past.builtins,future.builtins,functools
+
+
+[LOGGING]
+
+# Logging modules to check that the string format arguments are in logging
+# function parameter format
+logging-modules=logging,absl.logging,tensorflow.io.logging
+
+
+[SIMILARITIES]
+
+# Minimum lines number of a similarity.
+min-similarity-lines=4
+
+# Ignore comments when computing similarities.
+ignore-comments=yes
+
+# Ignore docstrings when computing similarities.
+ignore-docstrings=yes
+
+# Ignore imports when computing similarities.
+ignore-imports=no
+
+
+[SPELLING]
+
+# Spelling dictionary name. Available dictionaries: none. To make it working
+# install python-enchant package.
+spelling-dict=
+
+# List of comma separated words that should not be checked.
+spelling-ignore-words=
+
+# A path to a file that contains private dictionary; one word per line.
+spelling-private-dict-file=
+
+# Tells whether to store unknown words to indicated private dictionary in
+# --spelling-private-dict-file option instead of raising a message.
+spelling-store-unknown-words=no
+
+
+[IMPORTS]
+
+# Deprecated modules which should not be used, separated by a comma
+deprecated-modules=regsub,
+                   TERMIOS,
+                   Bastion,
+                   rexec,
+                   sets
+
+# Create a graph of every (i.e., internal and external) dependencies in the
+# given file (report RP0402 must not be disabled)
+import-graph=
+
+# Create a graph of external dependencies in the given file (report RP0402 must
+# not be disabled)
+ext-import-graph=
+
+# Create a graph of internal dependencies in the given file (report RP0402 must
+# not be disabled)
+int-import-graph=
+
+# Force import order to recognize a module as part of the standard
+# compatibility libraries.
+known-standard-library=
+
+# Force import order to recognize a module as part of a third party library.
+known-third-party=enchant, absl
+
+# Analyse import fallback blocks. This can be used to support both Python 2 and
+# 3 compatible code, which means that the block might have code that exists
+# only in one or another interpreter, leading to false positives when analysed.
+analyse-fallback-blocks=no
+
+
+[CLASSES]
+
+# List of method names used to declare (i.e., assign) instance attributes.
+defining-attr-methods=__init__,
+                      __new__,
+                      setUp
+
+# List of member names, which should be excluded from the protected access
+# warning.
+exclude-protected=_asdict,
+                  _fields,
+                  _replace,
+                  _source,
+                  _make
+
+# List of valid names for the first argument in a class method.
+valid-classmethod-first-arg=cls,
+                            class_
+
+# List of valid names for the first argument in a metaclass class method.
+valid-metaclass-classmethod-first-arg=mcs
+
+
+[EXCEPTIONS]
+
+# Exceptions that will emit a warning when being caught. Defaults to
+# "Exception"
+overgeneral-exceptions=builtins.StandardError,
+                       builtins.Exception,
+                       builtins.BaseException
+

alphagenome/source/.readthedocs.yaml

@@ -0,0 +1,42 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.10"
+  jobs:
+    pre_build:
+      # Copy colabs into docs/source so they can be included in the documentation.
+      - cp -r colabs docs/source/
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  builder: html
+  configuration: docs/source/conf.py
+  fail_on_warning: false
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

alphagenome/source/CHANGELOG.md

@@ -0,0 +1,42 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0]
+
+### Added
+
+-   Add `is_insertion` and `is_deletion` properties to `Variant`.
+-   Add `DnaModel` abstract base class.
+-   Add support for center mask scoring over the entire sequence by passing
+    `None` for width.
+
+### Changed
+
+-   Move RPC requests and responses to `dna_model_service.proto`.
+-   Move functionality to convert `TrackData` to/from protocol buffers to
+    utility module.
+
+## [0.1.0]
+
+### Added
+
+-   Add `L2_DIFF_LOG1P` variant scoring aggregation type.
+-   Add `is_snv` property to `Variant`.
+-   Add non-zero mean track metadata field to model output metadata.
+-   Add optional interval argument to `predict_sequence`.
+
+## [0.0.2]
+
+### Added
+
+-   `colab_utils` module to wrap reading API keys from environment variables or
+    Google Colab secrets.
+
+## [0.0.1]
+
+Initial release.

alphagenome/source/CONTRIBUTING.md

@@ -0,0 +1,25 @@
+# How to Contribute
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution,
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+## Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google/conduct/).

alphagenome/source/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

alphagenome/source/README.md

@@ -0,0 +1,235 @@
+![AlphaGenome header image](docs/source/_static/header.png)
+
+# AlphaGenome
+
+![PyPI Python version](https://img.shields.io/pypi/pyversions/AlphaGenome)
+![Presubmit Checks](https://github.com/google-deepmind/alphagenome/actions/workflows/presubmit_checks.yml/badge.svg)
+
+[**Get API key**](https://deepmind.google.com/science/alphagenome) |
+[**Quick start**](#quick-start) | [**Installation**](#installation) |
+[**Documentation**](https://www.alphagenomedocs.com/) |
+[**Community**](https://www.alphagenomecommunity.com) |
+[**Terms of Use**](https://deepmind.google.com/science/alphagenome/terms)
+
+The AlphaGenome API provides access to AlphaGenome, Google DeepMind’s unifying
+model for deciphering the regulatory code within DNA sequences. This repository
+contains client-side code, examples and documentation to help you use the
+AlphaGenome API.
+
+AlphaGenome offers multimodal predictions, encompassing diverse functional
+outputs such as gene expression, splicing patterns, chromatin features, and
+contact maps (see [diagram below](#model_overview)). The model analyzes DNA
+sequences of up to 1 million base pairs in length and can deliver predictions at
+single base-pair resolution for most outputs. AlphaGenome achieves
+state-of-the-art performance across a range of genomic prediction benchmarks,
+including numerous diverse variant effect prediction tasks (detailed in
+[Avsec et al. 2025](https://doi.org/10.1101/2025.06.25.661532)).
+
+The API is offered free of charge for
+[non-commercial use](https://deepmind.google.com/science/alphagenome/terms)
+(subject to the terms of use). Query rates vary based on demand – it is well
+suited for smaller to medium-scale analyses such as analysing a limited number
+of genomic regions or variants requiring 1000s of predictions, but is likely not
+suitable for large scale analyses requiring more than 1 million predictions.
+Once you obtain your API key, you can easily get started by following our
+[Quick Start Guide](#quick-start), or watching our
+[AlphaGenome 101 tutorial](https://youtu.be/Xbvloe13nak).
+
+<a id='model_overview'>
+
+![Model overview](docs/source/_static/model_overview.png)
+
+</a>
+
+The documentation also covers a set of comprehensive tutorials, variant scoring
+strategies to efficiently score variant effects, and a visualization library to
+generate `matplotlib` figures for the different output modalities.
+
+We cover additional details of the capabilities and limitations in our
+documentation. For support and feedback:
+
+-   Please submit bugs and any code-related issues on
+    [GitHub](https://github.com/google-deepmind/alphagenome/issues).
+-   For general feedback, questions about usage, and/or feature requests, please
+    use the [community forum](https://www.alphagenomecommunity.com) – it’s
+    actively monitored by our team so you're likely to find answers and insights
+    faster.
+-   If you can't find what you're looking for, please get in touch with the
+    AlphaGenome team on alphagenome@google.com and we will be happy to assist
+    you with questions. We’re working hard to answer all inquiries but there may
+    be a short delay in our response due to the high volume we are receiving.
+
+## Quick start
+
+The quickest way to get started is to run our example notebooks in
+[Google Colab](https://colab.research.google.com/). Here are some starter
+notebooks:
+
+-   [Quick start](https://colab.research.google.com/github/google-deepmind/alphagenome/blob/main/colabs/quick_start.ipynb):
+    An introduction to quickly get you started with using the model and making
+    predictions.
+-   [Visualizing predictions](https://colab.research.google.com/github/google-deepmind/alphagenome/blob/main/colabs/visualization_modality_tour.ipynb):
+    Learn how to visualize different model predictions using the visualization
+    libraries.
+
+Alternatively, you can dive straight in by following the
+[installation guide](#installation) and start writing code! Here's an example of
+making a variant prediction:
+
+```python
+from alphagenome.data import genome
+from alphagenome.models import dna_client
+from alphagenome.visualization import plot_components
+import matplotlib.pyplot as plt
+
+
+API_KEY = 'MyAPIKey'
+model = dna_client.create(API_KEY)
+
+interval = genome.Interval(chromosome='chr22', start=35677410, end=36725986)
+variant = genome.Variant(
+    chromosome='chr22',
+    position=36201698,
+    reference_bases='A',
+    alternate_bases='C',
+)
+
+outputs = model.predict_variant(
+    interval=interval,
+    variant=variant,
+    ontology_terms=['UBERON:0001157'],
+    requested_outputs=[dna_client.OutputType.RNA_SEQ],
+)
+
+plot_components.plot(
+    [
+        plot_components.OverlaidTracks(
+            tdata={
+                'REF': outputs.reference.rna_seq,
+                'ALT': outputs.alternate.rna_seq,
+            },
+            colors={'REF': 'dimgrey', 'ALT': 'red'},
+        ),
+    ],
+    interval=outputs.reference.rna_seq.interval.resize(2**15),
+    # Annotate the location of the variant as a vertical line.
+    annotations=[plot_components.VariantAnnotation([variant], alpha=0.8)],
+)
+plt.show()
+```
+
+## Installation
+
+<!-- mdformat off(disable for [!TIP] format) -->
+
+> [!TIP]
+> You may optionally wish to create a
+> [Python Virtual Environment](https://docs.python.org/3/tutorial/venv.html) to
+> prevent conflicts with your system's Python environment.
+
+<!-- mdformat on -->
+
+To install `alphagenome`, clone a local copy of the repository and run `pip
+install`:
+
+```bash
+$ git clone https://github.com/google-deepmind/alphagenome.git
+$ pip install ./alphagenome
+```
+
+See [the documentation](https://www.alphagenomedocs.com/installation.html) for
+information on alternative installation strategies.
+
+## Citing `alphagenome`
+
+If you use AlphaGenome in your research, please cite using:
+
+<!-- disableFinding(SNIPPET_INVALID_LANGUAGE) -->
+
+```bibtex
+@article{alphagenome,
+  title={{AlphaGenome}: advancing regulatory variant effect prediction with a unified {DNA} sequence model},
+  author={Avsec, {\v Z}iga and Latysheva, Natasha and Cheng, Jun and Novati, Guido and Taylor, Kyle R. and Ward, Tom and Bycroft, Clare and Nicolaisen, Lauren and Arvaniti, Eirini and Pan, Joshua and Thomas, Raina and Dutordoir, Vincent and Perino, Matteo and De, Soham and Karollus, Alexander and Gayoso, Adam and Sargeant, Toby and Mottram, Anne and Wong, Lai Hong and Drot{\'a}r, Pavol and Kosiorek, Adam and Senior, Andrew and Tanburn, Richard and Applebaum, Taylor and Basu, Souradeep and Hassabis, Demis and Kohli, Pushmeet},
+  year={2025},
+  doi={https://doi.org/10.1101/2025.06.25.661532},
+  publisher={Cold Spring Harbor Laboratory},
+  journal={bioRxiv}
+}
+```
+
+<!-- enableFinding(SNIPPET_INVALID_LANGUAGE) -->
+
+## Acknowledgements
+
+AlphaGenome communicates with and/or references the following separate libraries
+and packages:
+
+*   [Abseil](https://github.com/abseil/abseil-py)
+*   [anndata](https://github.com/scverse/anndata)
+*   [gRPC](https://github.com/grpc/grpc)
+*   [immutabledict](https://github.com/corenting/immutabledict)
+*   [intervaltree](https://github.com/chaimleib/intervaltree)
+*   [jaxtyping](https://github.com/patrick-kidger/jaxtyping)
+*   [matplotlib](https://matplotlib.org/)
+*   [ml_dtypes](https://github.com/jax-ml/ml_dtypes)
+*   [NumPy](https://numpy.org/)
+*   [pandas](https://pandas.pydata.org/)
+*   [protobuf](https://developers.google.com/protocol-buffers/)
+*   [pyarrow](https://arrow.apache.org/)
+*   [SciPy](https://scipy.org/)
+*   [seaborn](https://seaborn.pydata.org/)
+*   [tqdm](https://github.com/tqdm/tqdm)
+*   [typeguard](https://github.com/agronholm/typeguard)
+*   [typing_extensions](https://github.com/python/typing_extensions)
+*   [zstandard](https://github.com/indygreg/python-zstandard)
+
+We thank all their contributors and maintainers!
+
+## License and Disclaimer
+
+Copyright 2024 Google LLC
+
+All software in this repository is licensed under the Apache License, Version
+2.0 (Apache 2.0); you may not use this except in compliance with the Apache 2.0
+license. You may obtain a copy of the Apache 2.0 license at:
+https://www.apache.org/licenses/LICENSE-2.0.
+
+Examples and documentation to help you use the AlphaGenome API are licensed
+under the Creative Commons Attribution 4.0 International License (CC-BY). You
+may obtain a copy of the CC-BY license at:
+https://creativecommons.org/licenses/by/4.0/legalcode.
+
+Unless required by applicable law or agreed to in writing, all software and
+materials distributed here under the Apache 2.0 or CC-BY licenses are
+distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
+either express or implied. See the licenses for the specific language governing
+permissions and limitations under those licenses.
+
+This is not an official Google product.
+
+### Third-party software
+
+Your use of any third-party software, libraries or code referenced in the
+materials in this repository (including the libraries listed in the
+[Acknowledgments](#acknowledgements) section) may be governed by separate terms
+and conditions or license provisions. Your use of the third-party software,
+libraries or code is subject to any such terms and you should check that you can
+comply with any applicable restrictions or terms and conditions before use.
+
+### Reference Datasets
+
+A modified version of the GENCODE dataset (which can be found here:
+https://www.gencodegenes.org/human/releases.html) is released with the client
+code package for illustrative purposes, and is available with reference to the
+following:
+
+-   Copyright © 2024 EMBL-EBI
+-   The GENCODE dataset is subject to the EMBL-EBI terms of use, available at
+    https://www.ebi.ac.uk/about/terms-of-use.
+-   Citation: Frankish A, et al (2018) GENCODE reference annotation for the
+    human and mouse genome.
+-   Further details about GENCODE can be found at
+    https://www.gencodegenes.org/human/releases.html, with additional citation
+    information at https://www.gencodegenes.org/pages/publications.html and
+    further acknowledgements can be found at
+    https://www.gencodegenes.org/pages/gencode.html.

alphagenome/source/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+alphagenome Project Package Initialization File
+"""

alphagenome/source/colabs/essential_commands.ipynb

@@ -0,0 +1,1405 @@
+{
+  "cells": [
+    {
+      "metadata": {
+        "id": "LIIksEJ7fbxF"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "# Essential commands\n",
+        "The following describes essential commands for interacting with the AlphaGenome API. It is broken into two sections: data and methods.\n",
+        "\n"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "gcms9aHWNnqs"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "```{tip}\n",
+        "Open this tutorial in Google colab for interactive viewing.\n",
+        "```"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 13,
+          "status": "ok",
+          "timestamp": 1749822645556,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "iEs6z4rGe3lk"
+      },
+      "cell_type": "code",
+      "source": [
+        "# @title Install AlphaGenome\n",
+        "\n",
+        "# @markdown Run this cell to install AlphaGenome.\n",
+        "from IPython.display import clear_output\n",
+        "! pip install alphagenome\n",
+        "clear_output()"
+      ],
+      "outputs": [],
+      "execution_count": 1
+    },
+    {
+      "metadata": {
+        "id": "rKyGK083Wwh7"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "# Imports"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 1070,
+          "status": "ok",
+          "timestamp": 1749822646891,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "V7MD3DBEfJwf"
+      },
+      "cell_type": "code",
+      "source": [
+        "from alphagenome.data import genome\n",
+        "from alphagenome.models import dna_client\n",
+        "import numpy as np\n",
+        "import pandas as pd\n",
+        "from google.colab import userdata"
+      ],
+      "outputs": [],
+      "execution_count": 2
+    },
+    {
+      "metadata": {
+        "id": "dzkwq2tyfj0q"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "##  Data: model inputs"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "3qR6e2XtW5IZ"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "### Genomic interval\n",
+        "\n",
+        "A genomic interval is specified using `genome.Interval`:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 57,
+          "status": "ok",
+          "timestamp": 1749822647220,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "XIZHnO32W4Hn"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval = genome.Interval(chromosome='chr1', start=1_000, end=1_010)"
+      ],
+      "outputs": [],
+      "execution_count": 3
+    },
+    {
+      "metadata": {
+        "id": "Qn9x1ArcXLVI"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "By default, these are human hg38 intervals. See the\n",
+        "[FAQ](https://www.alphagenomedocs.com/faqs.html#what-are-the-reference-genome-versions-used-by-the-model) for more\n",
+        "details on organisms and genome versions.\n"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "PCGNRUfHXOL1"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Interval properties\n",
+        "\n",
+        "Access some handy properties of the interval:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 66,
+          "status": "ok",
+          "timestamp": 1749822647565,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "8bn73Lm3XL1C",
+        "outputId": "f872b5f0-51bd-4455-9ec6-96c3d19a5c1d"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.center()"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "1005"
+            ]
+          },
+          "execution_count": 4,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 4
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 56,
+          "status": "ok",
+          "timestamp": 1749822647918,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "fJVk-ocQXWhm",
+        "outputId": "d0203696-36b6-4ca5-a204-f417284f2ca7"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.width"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "10"
+            ]
+          },
+          "execution_count": 5,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 5
+    },
+    {
+      "metadata": {
+        "id": "BvlmfYgBXXig"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Resize\n",
+        "\n",
+        "Use `genome.Interval.resize` to resize the interval\n",
+        "around its center point:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 64,
+          "status": "ok",
+          "timestamp": 1749822648252,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "y72ZqANrXehY",
+        "outputId": "5c001c60-01db-4807-8508-a795a88dc629"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.resize(100)"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "Interval(chromosome='chr1', start=955, end=1055, strand='.', name='')"
+            ]
+          },
+          "execution_count": 6,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 6
+    },
+    {
+      "metadata": {
+        "id": "ZrM4rMJDXkNF"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Compare intervals\n",
+        "\n",
+        "We can also check the interval's relationship to other intervals:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 68,
+          "status": "ok",
+          "timestamp": 1749822648622,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "Ye04nJETXmBL"
+      },
+      "cell_type": "code",
+      "source": [
+        "second_interval = genome.Interval(chromosome='chr1', start=1_005, end=1_015)"
+      ],
+      "outputs": [],
+      "execution_count": 7
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 62,
+          "status": "ok",
+          "timestamp": 1749822648949,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "9yecEDzAXpIS",
+        "outputId": "d5a0d62c-4d96-4945-c33b-9566f5c9d1b0"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.overlaps(second_interval)"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "True"
+            ]
+          },
+          "execution_count": 8,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 8
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 61,
+          "status": "ok",
+          "timestamp": 1749822649266,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "tMN-FGXZXsqr",
+        "outputId": "32d4de71-3d1c-4965-91c2-8f82b09d9aab"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.contains(second_interval)"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "False"
+            ]
+          },
+          "execution_count": 9,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 9
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 330,
+          "status": "ok",
+          "timestamp": 1749822649862,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "sDjWXjJYXuPB",
+        "outputId": "f43f4e1b-e319-44c7-d6d9-68b5384d579c"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval.intersect(second_interval)"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "Interval(chromosome='chr1', start=1005, end=1010, strand='.', name='')"
+            ]
+          },
+          "execution_count": 10,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 10
+    },
+    {
+      "metadata": {
+        "id": "X0U15RKjXwZL"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "As a subtle point, AlphaGenome classes use 0-based indexing, meaning that the\n",
+        "interval includes the base pair at the `start` position up to the base pair at\n",
+        "the `end-1` position. See the [FAQ](https://www.alphagenomedocs.com/faqs.html#how-do-i-specify-a-genomic-region)\n",
+        "for more on this topic."
+      ]
+    },
+    {
+      "metadata": {
+        "id": "dIDUCQKOX1Vj"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "### Genomic variant\n",
+        "\n",
+        "A `genome.Variant` specifies a genetic variant:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 54,
+          "status": "ok",
+          "timestamp": 1749822650248,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "R_D6AoKFXyBJ"
+      },
+      "cell_type": "code",
+      "source": [
+        "variant = genome.Variant(\n",
+        "    chromosome='chr3', position=10_000, reference_bases='A', alternate_bases='C'\n",
+        ")"
+      ],
+      "outputs": [],
+      "execution_count": 11
+    },
+    {
+      "metadata": {
+        "id": "L9QcFhogX693"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "This variant changes the base `A` to a `C` at position 10\\_000 on chromosome 3\\.\n",
+        "Note that the `position` attribute is 1-based to maintain compatibility with\n",
+        "common public variant formats (see [FAQ](https://www.alphagenomedocs.com/faqs.html#how-do-i-define-a-variant) for more\n",
+        "info.)"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "l6SRhPTrYKY3"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Insertions or deletions (indels)\n",
+        "\n",
+        "Variants can also be larger than a single base, such as insertions or deletions:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 56,
+          "status": "ok",
+          "timestamp": 1749822650560,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "PMmSYhSfX9K9"
+      },
+      "cell_type": "code",
+      "source": [
+        "# Insertion variant.\n",
+        "variant = genome.Variant(\n",
+        "    chromosome='chr3',\n",
+        "    position=10_000,\n",
+        "    reference_bases='T',\n",
+        "    alternate_bases='CGTCAAT',\n",
+        ")\n",
+        "\n",
+        "# Deletion variant.\n",
+        "variant = genome.Variant(\n",
+        "    chromosome='chr3',\n",
+        "    position=10_000,\n",
+        "    reference_bases='AGGGATC',\n",
+        "    alternate_bases='C',\n",
+        ")"
+      ],
+      "outputs": [],
+      "execution_count": 12
+    },
+    {
+      "metadata": {
+        "id": "_v9VY9kqYRoP"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "The sequence we pass for the `reference_bases` argument could differ from what\n",
+        "is actually at that location in the hg38 reference genome. The model will insert\n",
+        "whatever is passed as the reference and alternate bases into the sequence and\n",
+        "make predictions on them."
+      ]
+    },
+    {
+      "metadata": {
+        "id": "za3OTKasYYlb"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Reference interval\n",
+        "\n",
+        "We can get the `genome.Interval` corresponding to the\n",
+        "reference bases of the variant using `genome.Variant.reference_interval`:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 62,
+          "status": "ok",
+          "timestamp": 1749822650873,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "UUyBaqWtYfc0",
+        "outputId": "cb3fc331-604d-4d58-9802-f4491dfe9bb2"
+      },
+      "cell_type": "code",
+      "source": [
+        "variant = genome.Variant(\n",
+        "    chromosome='chr3', position=10_000, reference_bases='A', alternate_bases='T'\n",
+        ")\n",
+        "\n",
+        "variant.reference_interval"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "Interval(chromosome='chr3', start=9999, end=10000, strand='.', name='')"
+            ]
+          },
+          "execution_count": 13,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 13
+    },
+    {
+      "metadata": {
+        "id": "DATTTBK6YiEZ"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "A common use-case is to make predictions in a genome region around a variant,\n",
+        "which involves resizing the\n",
+        "`genome.Variant.reference_interval` to a sequence\n",
+        "length compatible with AlphaGenome:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 81,
+          "status": "ok",
+          "timestamp": 1749822651223,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "YijroJwOYnfU",
+        "outputId": "f923811e-b6c8-4aca-bc5a-d821377557d3"
+      },
+      "cell_type": "code",
+      "source": [
+        "input_interval = variant.reference_interval.resize(\n",
+        "    dna_client.SEQUENCE_LENGTH_1MB\n",
+        ")\n",
+        "input_interval.width"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "1048576"
+            ]
+          },
+          "execution_count": 14,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 14
+    },
+    {
+      "metadata": {
+        "id": "qGIpFPd_YmYc"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Overlap with interval\n",
+        "\n",
+        "We can also check if a variant’s reference or alternate alleles overlap an `genome.Interval`:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 128,
+          "status": "ok",
+          "timestamp": 1749822651618,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "HmiX9TELYxTD",
+        "outputId": "3e267c68-30dd-4aaf-e316-2a87df03d96e"
+      },
+      "cell_type": "code",
+      "source": [
+        "variant = genome.Variant(\n",
+        "    chromosome='chr3',\n",
+        "    position=10_000,\n",
+        "    reference_bases='T',\n",
+        "    alternate_bases='CGTCAAT',\n",
+        ")\n",
+        "\n",
+        "interval = genome.Interval(chromosome='chr3', start=10_005, end=10_010)\n",
+        "\n",
+        "print('Reference overlaps:', variant.reference_overlaps(interval))\n",
+        "print('Alternative overlaps:', variant.alternate_overlaps(interval))"
+      ],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Reference overlaps: False\n",
+            "Alternative overlaps: True\n"
+          ]
+        }
+      ],
+      "execution_count": 15
+    },
+    {
+      "metadata": {
+        "id": "Kr0329VfZAZo"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "##  Data: model outputs\n",
+        "\n",
+        "### Track data\n",
+        "\n",
+        "\u003ca href=\"https://services.google.com/fh/files/misc/trackdata.png\"\u003e\u003cimg src=\"https://services.google.com/fh/files/misc/trackdata.png\" alt=\"anndata\" border=\"0\" height=500\u003e\u003c/a\u003e\n",
+        "\n",
+        "`track_data.TrackData` objects store model predictions.\n",
+        "They have the following properties (using `tdata` as an example of a\n",
+        "`track_data.TrackData` object):\n",
+        "\n",
+        "*   `tdata.values` store track predictions as a `numpy.ndarray` .\n",
+        "*   `tdata.metadata` stores track metadata as a `pandas.DataFrame`. For\n",
+        "    each track in the predicted values, there will be a corresponding row in the\n",
+        "    track metadata describing its origin.\n",
+        "*   `tdata.uns` contains additional unstructured metadata as a `dict`."
+      ]
+    },
+    {
+      "metadata": {
+        "id": "I3HTL-NTZR6n"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### From scratch\n",
+        "\n",
+        "You can create your own `track_data.TrackData` object\n",
+        "from scratch by specifying the values and metadata manually. The metadata must\n",
+        "contain at least the columns name (the names of the tracks) and strand (the\n",
+        "strands of DNA that the tracks are on):\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 58,
+          "status": "ok",
+          "timestamp": 1749822651961,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "uwsbveEvZBbt"
+      },
+      "cell_type": "code",
+      "source": [
+        "from alphagenome.data import track_data\n",
+        "\n",
+        "# Array has shape (4,3) -\u003e sequence is length 4 and there are 3 tracks.\n",
+        "values = np.array([[0, 1, 2], [3, 4, 5], [6, 7, 8], [9, 10, 11]]).astype(\n",
+        "    np.float32\n",
+        ")\n",
+        "\n",
+        "# We have both the positive and negative strand values for track1, while track2\n",
+        "# contains unstranded data.\n",
+        "metadata = pd.DataFrame({\n",
+        "    'name': ['track1', 'track1', 'track2'],\n",
+        "    'strand': ['+', '-', '.'],\n",
+        "})\n",
+        "\n",
+        "tdata = track_data.TrackData(values=values, metadata=metadata)"
+      ],
+      "outputs": [],
+      "execution_count": 16
+    },
+    {
+      "metadata": {
+        "id": "qEc4ioZVZgR0"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Resolution\n",
+        "\n",
+        "It’s also useful to specify the resolution of the tracks and the genomic\n",
+        "interval that they come from, if you have this information available:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 55,
+          "status": "ok",
+          "timestamp": 1749822652304,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "JGnuY6g_ZaBL"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval = genome.Interval(chromosome='chr1', start=1_000, end=1_004)\n",
+        "\n",
+        "tdata = track_data.TrackData(\n",
+        "    values=values, metadata=metadata, resolution=1, interval=interval\n",
+        ")"
+      ],
+      "outputs": [],
+      "execution_count": 17
+    },
+    {
+      "metadata": {
+        "id": "QeN8D_yGZlVB"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "Note that the length of the values has to match up with the interval width and\n",
+        "resolution. Here is an example specifying that the values actually represent\n",
+        "128bp resolution tracks (i.e., each number is a summary over 128 base pairs of\n",
+        "DNA):\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 56,
+          "status": "ok",
+          "timestamp": 1749822652621,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "I-iPD_ZGZjMI"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval = genome.Interval(chromosome='chr1', start=1_000, end=1_512)\n",
+        "\n",
+        "tdata = track_data.TrackData(\n",
+        "    values=values, metadata=metadata, resolution=128, interval=interval\n",
+        ")"
+      ],
+      "outputs": [],
+      "execution_count": 18
+    },
+    {
+      "metadata": {
+        "id": "HhVG6w41ZqEp"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "####  Converting between resolutions\n",
+        "\n",
+        "We can also interconvert between resolutions. For example, given 1bp resolution\n",
+        "predictions, we can downsample the resolution (by summing adjacent values) and\n",
+        "return a sequence of length 2:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 64,
+          "status": "ok",
+          "timestamp": 1749822652955,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "Ce41uPkcZoWd",
+        "outputId": "38adb4cb-7a38-4cc3-8f12-af6ea95dfc0b"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval = genome.Interval(chromosome='chr1', start=1_000, end=1_004)\n",
+        "\n",
+        "tdata = track_data.TrackData(\n",
+        "    values=values, metadata=metadata, resolution=1, interval=interval\n",
+        ")\n",
+        "\n",
+        "tdata = tdata.change_resolution(resolution=2)\n",
+        "tdata.values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[ 3.,  5.,  7.],\n",
+              "       [15., 17., 19.]], dtype=float32)"
+            ]
+          },
+          "execution_count": 19,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 19
+    },
+    {
+      "metadata": {
+        "id": "23Ehe3duZqC3"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "We can also upsample track data to get back to 1bp resolution and a sequence of\n",
+        "length 4 by repeating values while preserving the sum:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 65,
+          "status": "ok",
+          "timestamp": 1749822653280,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "dDi9OWWWZzq_",
+        "outputId": "51f3878b-d71e-48f7-f6c7-7a87830704ed"
+      },
+      "cell_type": "code",
+      "source": [
+        "tdata = tdata.change_resolution(resolution=1)\n",
+        "tdata.values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[1.5, 2.5, 3.5],\n",
+              "       [1.5, 2.5, 3.5],\n",
+              "       [7.5, 8.5, 9.5],\n",
+              "       [7.5, 8.5, 9.5]], dtype=float32)"
+            ]
+          },
+          "execution_count": 20,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 20
+    },
+    {
+      "metadata": {
+        "id": "Rkne2GEwZ82L"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "####  Filtering\n",
+        "\n",
+        "`track_data.TrackData` objects can be filtered by the\n",
+        "type of DNA strand the tracks are on:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 71,
+          "status": "ok",
+          "timestamp": 1749822653638,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "RoIaGXLtaBbz",
+        "outputId": "75db5fc1-a5a6-4798-e26f-9d62443abbeb"
+      },
+      "cell_type": "code",
+      "source": [
+        "print(\n",
+        "    'Positive strand tracks:',\n",
+        "    tdata.filter_to_positive_strand().metadata.name.values,\n",
+        ")\n",
+        "print(\n",
+        "    'Negative strand tracks:',\n",
+        "    tdata.filter_to_negative_strand().metadata.name.values,\n",
+        ")\n",
+        "print('Unstranded tracks:', tdata.filter_to_unstranded().metadata.name.values)"
+      ],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "Positive strand tracks: ['track1']\n",
+            "Negative strand tracks: ['track1']\n",
+            "Unstranded tracks: ['track2']\n"
+          ]
+        }
+      ],
+      "execution_count": 21
+    },
+    {
+      "metadata": {
+        "id": "xogO-bWVaatH"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Resizing\n",
+        "\n",
+        "We can resize the `track_data.TrackData` to be either\n",
+        "smaller (by cropping):"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 61,
+          "status": "ok",
+          "timestamp": 1749822654145,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "clj536M9abBp",
+        "outputId": "f7819f36-70c7-4b78-cb04-b0e2e030ff6e"
+      },
+      "cell_type": "code",
+      "source": [
+        "# Re-instantiating the original trackdata.\n",
+        "tdata = track_data.TrackData(\n",
+        "    values=values, metadata=metadata, resolution=1, interval=interval\n",
+        ")\n",
+        "\n",
+        "# Resize from width (sequence length) of 4 down to 2.\n",
+        "tdata.resize(width=2).values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[3., 4., 5.],\n",
+              "       [6., 7., 8.]], dtype=float32)"
+            ]
+          },
+          "execution_count": 22,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 22
+    },
+    {
+      "metadata": {
+        "id": "wl3aNKu-akaO"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "Or bigger (by padding with zeros):\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 61,
+          "status": "ok",
+          "timestamp": 1749822654456,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "pHWZRppBaeC1",
+        "outputId": "087a212d-ca6f-4490-fe59-408e9a157ee2"
+      },
+      "cell_type": "code",
+      "source": [
+        "tdata.resize(width=8).values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[ 0.,  0.,  0.],\n",
+              "       [ 0.,  0.,  0.],\n",
+              "       [ 0.,  1.,  2.],\n",
+              "       [ 3.,  4.,  5.],\n",
+              "       [ 6.,  7.,  8.],\n",
+              "       [ 9., 10., 11.],\n",
+              "       [ 0.,  0.,  0.],\n",
+              "       [ 0.,  0.,  0.]], dtype=float32)"
+            ]
+          },
+          "execution_count": 23,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 23
+    },
+    {
+      "metadata": {
+        "id": "SRkggBayar2r"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Slicing\n",
+        "\n",
+        "We can slice into specific positions of the\n",
+        "`track_data.TrackData`:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 56,
+          "status": "ok",
+          "timestamp": 1749822654784,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "yHcMdzN1amMz",
+        "outputId": "73a293d2-279c-4709-b79c-cfd24235e19d"
+      },
+      "cell_type": "code",
+      "source": [
+        "# Get the final 2 positions only.\n",
+        "print('slice by position: ', tdata.slice_by_positions(start=2, end=4).values)\n",
+        "# Same, but using slice_interval:\n",
+        "print(\n",
+        "    'slice by interval: ',\n",
+        "    tdata.slice_by_interval(\n",
+        "        genome.Interval(chromosome='chr1', start=1_002, end=1_004)\n",
+        "    ).values,\n",
+        ")"
+      ],
+      "outputs": [
+        {
+          "name": "stdout",
+          "output_type": "stream",
+          "text": [
+            "slice by position:  [[ 6.  7.  8.]\n",
+            " [ 9. 10. 11.]]\n",
+            "slice by interval:  [[ 6.  7.  8.]\n",
+            " [ 9. 10. 11.]]\n"
+          ]
+        }
+      ],
+      "execution_count": 24
+    },
+    {
+      "metadata": {
+        "id": "p1OiFpXGa-Ja"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### Subsetting tracks\n",
+        "\n",
+        "Subset (and reorder) to specific track names:"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 63,
+          "status": "ok",
+          "timestamp": 1749822655084,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "_l9bKsuvaxtu",
+        "outputId": "abed781e-42d7-4c55-85fe-754ac8351905"
+      },
+      "cell_type": "code",
+      "source": [
+        "# Get only tracks with the name 'track1'.\n",
+        "track1_tdata = tdata.select_tracks_by_name(names='track1')\n",
+        "track1_tdata.values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[ 0.,  1.],\n",
+              "       [ 3.,  4.],\n",
+              "       [ 6.,  7.],\n",
+              "       [ 9., 10.]], dtype=float32)"
+            ]
+          },
+          "execution_count": 25,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 25
+    },
+    {
+      "metadata": {
+        "id": "bdTrjm4pbLIC"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "The metadata gets automatically filtered to `track1` too:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 58,
+          "status": "ok",
+          "timestamp": 1749822655417,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "aErYz_nRbCID",
+        "outputId": "59679dd0-7f08-44d9-dfb8-3f5a34e7380c"
+      },
+      "cell_type": "code",
+      "source": [
+        "track1_tdata.metadata.name.values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array(['track1', 'track1'], dtype=object)"
+            ]
+          },
+          "execution_count": 26,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 26
+    },
+    {
+      "metadata": {
+        "id": "lgprEnpIbPtR"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "Finally, if we pass in a stranded `genome.Interval` or\n",
+        "leave unspecified as `None` when constructing a\n",
+        "`track_data.TrackData`, we can reverse complement\n",
+        "transform our track values in a strand-aware manner:\n"
+      ]
+    },
+    {
+      "metadata": {
+        "executionInfo": {
+          "elapsed": 58,
+          "status": "ok",
+          "timestamp": 1749822655727,
+          "user": {
+            "displayName": "",
+            "userId": ""
+          },
+          "user_tz": -60
+        },
+        "id": "HeZXB4K3bMyJ",
+        "outputId": "1d6250e5-f1c3-471a-b347-c73664d056a5"
+      },
+      "cell_type": "code",
+      "source": [
+        "interval = genome.Interval(\n",
+        "    chromosome='chr1', start=1_000, end=1_004, strand='+'\n",
+        ")\n",
+        "\n",
+        "tdata = track_data.TrackData(\n",
+        "    values=values, metadata=metadata, resolution=1, interval=interval\n",
+        ")\n",
+        "\n",
+        "tdata.reverse_complement().values"
+      ],
+      "outputs": [
+        {
+          "data": {
+            "text/plain": [
+              "array([[10.,  9., 11.],\n",
+              "       [ 7.,  6.,  8.],\n",
+              "       [ 4.,  3.,  5.],\n",
+              "       [ 1.,  0.,  2.]], dtype=float32)"
+            ]
+          },
+          "execution_count": 27,
+          "metadata": {},
+          "output_type": "execute_result"
+        }
+      ],
+      "execution_count": 27
+    },
+    {
+      "metadata": {
+        "id": "Hb8duvxibcXW"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "### Variant scoring output\n",
+        "\n",
+        "# \u003ca href=\"https://services.google.com/fh/files/misc/anndata.png\"\u003e\u003cimg src=\"https://services.google.com/fh/files/misc/anndata.png\" alt=\"anndata\" border=\"0\" height=500\u003e\u003c/a\u003e\n",
+        "\n",
+        "The output of variant scoring is in `anndata.AnnData` format, which is a\n",
+        "way of scoring data together with annotation metadata. Originally developed in\n",
+        "the single-cell RNA-seq field, `anndata.AnnData` is useful when you have\n",
+        "metadata associated with an array of data.\n",
+        "\n",
+        "`anndata.AnnData` objects have the following properties (using\n",
+        "`variant_scores` as an example `anndata.AnnData` object):\n",
+        "\n",
+        "*   `variant_scores.X` contains a `numpy.ndarray` containing the variant\n",
+        "    scores per each gene in the region. This matrix has shape (`num_genes`,\n",
+        "    `num_tracks`), where `num_tracks` is the number of output tracks in your\n",
+        "    requested OutputType (such as `RNA_SEQ`, `DNASE`, etc.). Note that if you\n",
+        "    did not use a gene-centric scorer, then `variant_scores.X` will have shape\n",
+        "    (1, `num_tracks`), reflecting the fact that the variant has a single global\n",
+        "    score and not per-gene score.\n",
+        "*   `variant_scores.var` contains the track metadata as a\n",
+        "    `pandas.DataFrame`. For every track in the scores (`num_genes`,\n",
+        "    `num_tracks`), there will be a row in the track metadata explaining the\n",
+        "    track (its cell type, strand, etc.).\n",
+        "*   `variant_scores.obs` contains the gene metadata as a\n",
+        "    `pandas.DataFrame`. Note that the gene metadata is None in the case\n",
+        "    of non gene-centric variant scorers.\n",
+        "*   `variant_scores.uns` contains some additional unstructured metadata that\n",
+        "    logs the origin of the variant scores, namely:\n",
+        "    *   The `genome.Variant` that was scored\n",
+        "        (variant\\_scores.uns\\[‘variant’\\])\n",
+        "    *   The `genome.Interval` containing the interval\n",
+        "        (variant\\_scores.uns\\[‘interval’\\])\n",
+        "    *   The [`variant scorer`](https://www.alphagenomedocs.com/api/models.html#variant-scorers) that was used to\n",
+        "        generate the scores (variant\\_scores.uns\\[‘scorer’\\])"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "wxew4DE0bmLO"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "#### From scratch\n",
+        "\n",
+        "You are unlikely to need to create an `anndata.AnnData` object from\n",
+        "scratch, but just for reference, here is how it would be done:"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "e3jeE3HVbpof"
+      },
+      "cell_type": "code",
+      "source": [
+        "import anndata\n",
+        "import numpy as np\n",
+        "import pandas as pd\n",
+        "\n",
+        "# Creating a small matrix of variant scores (3 genes x 2 tracks).\n",
+        "scores = np.array([[0.1, 0.2], [0.3, 0.4], [0.5, 0.6]])\n",
+        "\n",
+        "gene_metadata = pd.DataFrame({'gene_id': ['ENSG0001', 'ENSG0002', 'ENSG0003']})\n",
+        "\n",
+        "track_metadata = pd.DataFrame(\n",
+        "    {'name': ['track1', 'track2'], 'strand': ['+', '-']}\n",
+        ")\n",
+        "\n",
+        "variant_scores = anndata.AnnData(\n",
+        "    X=scores, obs=gene_metadata, var=track_metadata\n",
+        ")"
+      ],
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {
+        "id": "7IHNdc_BbttW"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "## Methods: making predictions\n",
+        "\n",
+        "The main commands for making model predictions are:\n",
+        "\n",
+        "*   `dna_client.DnaClient.predict_sequence` to predict\n",
+        "    from a raw DNA string\n",
+        "*   `dna_client.DnaClient.predict_interval` to predict\n",
+        "    from a genome interval (a `genome.Interval`)\n",
+        "*   `dna_client.DnaClient.predict_variant` to make\n",
+        "    predictions for ref and alt sequences of a variant (a\n",
+        "    `genome.Variant` object)\n",
+        "*   `dna_client.DnaClient.score_variant` to score the\n",
+        "    effects of a variant by comparing ref and alt predictions.\n",
+        "*   `dna_client.DnaClient.score_variants` the same as\n",
+        "    the above, but for scoring a list of multiple variants.\n"
+      ]
+    },
+    {
+      "metadata": {
+        "id": "lJ17YLKRQ6nq"
+      },
+      "cell_type": "code",
+      "source": [],
+      "outputs": [],
+      "execution_count": null
+    },
+    {
+      "metadata": {
+        "id": "X10M3ojgbw4a"
+      },
+      "cell_type": "markdown",
+      "source": [
+        "## Methods: visualization\n",
+        "\n",
+        "The main command for visualizing model predictions is:\n",
+        "\n",
+        "*   `alphagenome.visualization.plot_components.plot`, to turn a list of\n",
+        "    of [plot components](https://www.alphagenomedocs.com/api/visualization.html#plot-components) into a\n",
+        "    `matplotlib.figure.Figure`.\n",
+        "\n",
+        "See the [visualization basics guide](https://www.alphagenomedocs.com/visualization_library_basics.html) and [visualizing predictions tutorial](https://www.alphagenomedocs.com/colabs/visualization_modality_tour.html) for more details."
+      ]
+    }
+  ],
+  "metadata": {
+    "colab": {
+      "last_runtime": {},
+      "provenance": [
+        {
+          "file_id": "1hJ2uMZ3sA8pu_UvSNikENLECC-X5XrR8",
+          "timestamp": 1749822158925
+        }
+      ]
+    },
+    "kernelspec": {
+      "display_name": "Python 3",
+      "name": "python3"
+    },
+    "language_info": {
+      "name": "python"
+    }
+  },
+  "nbformat": 4,
+  "nbformat_minor": 0
+}

alphagenome/source/conftest.py

@@ -0,0 +1,22 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configure FLAGS with default values for absltest."""
+
+from absl import app
+
+try:
+  app.run(lambda argv: None)
+except SystemExit:
+  pass

alphagenome/source/docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

alphagenome/source/docs/README.md

@@ -0,0 +1,6 @@
+AlphaGenome API is a service that provides comprehensive and accurate AI
+predictions for genome interpretation.
+
+AlphaGenome is a deep learning genomics model that takes a genomic (DNA)
+sequence as input and predicts various molecular properties of DNA & RNA, many
+at single base pair resolution.

alphagenome/source/docs/make.bat

@@ -0,0 +1,49 @@
+@rem Copyright 2024 Google LLC.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      http://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

alphagenome/source/docs/source/_templates/autosummary/class.rst

@@ -0,0 +1,55 @@
+{{ fullname | escape | underline }}
+
+.. currentmodule:: {{ module }}
+
+.. autoclass:: {{ objname }}
+
+{% block attributes %}
+{% if attributes %}
+
+
+Attributes
+~~~~~~~~~~
+
+.. rubric:: Table
+
+.. autosummary::
+{% for item in attributes %}
+{%- if item not in inherited_members%}
+    ~{{ name }}.{{ item }}
+{%- endif -%}
+{%- endfor %}
+
+{% for item in attributes %}
+.. autoattribute:: {{ [objname, item] | join(".") }}
+{%- endfor %}
+
+{% endif %}
+{% endblock %}
+
+{% block methods %}
+
+{% if methods %}
+
+Methods
+~~~~~~~
+
+.. rubric:: Table
+
+.. autosummary::
+{% for item in methods %}
+{%- if item != '__init__' %}
+    ~{{ name }}.{{ item }}
+{%- endif -%}
+
+{%- endfor %}
+
+{% for item in methods %}
+{%- if item != '__init__'%}
+.. automethod:: {{ [objname, item] | join(".") }}
+{%- endif %}
+{%- endfor %}
+{% endif %}
+
+{% endblock %}
+

alphagenome/source/docs/source/api/data.md

@@ -0,0 +1,89 @@
+# Data
+
+Classes and utilities for manipulating genomics data.
+
+## Fold Intervals
+
+``` {eval-rst}
+.. currentmodule:: alphagenome
+```
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.fold_intervals.Subset
+    data.fold_intervals.get_all_folds
+    data.fold_intervals.get_fold_names
+    data.fold_intervals.get_fold_intervals
+```
+
+## Genome
+
+``` {eval-rst}
+.. currentmodule:: alphagenome
+```
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.genome.Strand
+    data.genome.Interval
+    data.genome.Variant
+    data.genome.Junction
+```
+
+## Gene annotation
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.gene_annotation.TranscriptType
+    data.gene_annotation.extract_tss
+    data.gene_annotation.filter_transcript_type
+    data.gene_annotation.filter_protein_coding
+    data.gene_annotation.filter_to_longest_transcript
+    data.gene_annotation.filter_transcript_support_level
+```
+
+## Ontology
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.ontology.OntologyType
+    data.ontology.OntologyTerm
+```
+
+## Track data
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.track_data.TrackData
+    data.track_data.concat
+    data.track_data.interleave
+    data.track_data.metadata_to_proto
+    data.track_data.metadata_from_proto
+    data.track_data.from_protos
+```
+
+## Transcript
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    data.transcript.Transcript
+    data.transcript.TranscriptExtractor
+```

alphagenome/source/docs/source/api/index.md

@@ -0,0 +1,46 @@
+# API
+
+``` {toctree}
+:maxdepth: 1
+:hidden:
+
+data
+models
+interpretation
+visualization
+```
+
+<!-- mdformat off(Turn off mdformat to retain grid card syntax.) -->
+
+::::{grid} 1 1 2 3
+:gutter: 2
+
+:::{grid-item-card} Data
+:link: data
+:link-type: doc
+
+Classes and utilities for manipulating genomics data.
+:::
+
+:::{grid-item-card} Models
+:link: models
+:link-type: doc
+
+AlphaGenome client and variant scorers.
+:::
+
+:::{grid-item-card} Interpretation
+:link: interpretation
+:link-type: doc
+
+Sequence interpretation tools (like in silico mutagenesis).
+:::
+
+:::{grid-item-card} Visualization
+:link: visualization
+:link-type: doc
+
+Visualization and plotting tools.
+:::
+
+<!-- mdformat on -->

alphagenome/source/docs/source/api/interpretation.md

@@ -0,0 +1,16 @@
+# Interpretation
+
+Sequence interpretation tools (like in silico mutagenesis).
+
+## ISM
+
+``` {eval-rst}
+.. module:: alphagenome.interpretation
+.. currentmodule:: alphagenome
+
+.. autosummary::
+    :toctree: generated
+
+    interpretation.ism.ism_variants
+    interpretation.ism.ism_matrix
+```

alphagenome/source/docs/source/api/models.md

@@ -0,0 +1,55 @@
+# Models
+
+AlphaGenome client and variant scorers.
+
+## DNA Client
+
+``` {eval-rst}
+.. currentmodule:: alphagenome
+```
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    models.dna_client.create
+    models.dna_client.ModelVersion
+    models.dna_client.Organism
+    models.dna_client.validate_sequence_length
+    models.dna_client.DnaClient
+```
+
+## DNA Output
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    models.dna_output.OutputType
+    models.dna_output.Output
+    models.dna_output.OutputMetadata
+    models.dna_output.VariantOutput
+```
+
+## Variant Scorers
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    models.variant_scorers.AggregationType
+    models.variant_scorers.BaseVariantScorer
+    models.variant_scorers.CenterMaskScorer
+    models.variant_scorers.ContactMapScorer
+    models.variant_scorers.GeneMaskLFCScorer
+    models.variant_scorers.GeneMaskActiveScorer
+    models.variant_scorers.GeneMaskSplicingScorer
+    models.variant_scorers.PolyadenylationScorer
+    models.variant_scorers.SpliceJunctionScorer
+    models.variant_scorers.get_recommended_scorers
+    models.variant_scorers.tidy_anndata
+    models.variant_scorers.tidy_scores
+```

alphagenome/source/docs/source/api/visualization.md

@@ -0,0 +1,60 @@
+# Visualization
+
+Visualization and plotting tools.
+
+## Plot
+
+``` {eval-rst}
+.. currentmodule:: alphagenome
+```
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    visualization.plot.seqlogo
+    visualization.plot.plot_contact_map
+    visualization.plot.plot_track
+    visualization.plot.plot_tracks
+    visualization.plot.sashimi_plot
+    visualization.plot.pad_track
+```
+
+(visualization/plot-components)=
+
+## Plot components
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    visualization.plot_components.plot
+    visualization.plot_components.AbstractComponent
+    visualization.plot_components.Tracks
+    visualization.plot_components.OverlaidTracks
+    visualization.plot_components.ContactMaps
+    visualization.plot_components.ContactMapsDiff
+    visualization.plot_components.TranscriptAnnotation
+    visualization.plot_components.SeqLogo
+    visualization.plot_components.Sashimi
+    visualization.plot_components.EmptyComponent
+    visualization.plot_components.AbstractAnnotation
+    visualization.plot_components.IntervalAnnotation
+    visualization.plot_components.VariantAnnotation
+```
+
+## Plot transcripts
+
+``` {eval-rst}
+
+.. autosummary::
+    :toctree: generated
+
+    visualization.plot_transcripts.TranscriptStyle
+    visualization.plot_transcripts.TranscriptStylePreset
+    visualization.plot_transcripts.plot_transcripts
+    visualization.plot_transcripts.draw_interval
+    visualization.plot_transcripts.draw_transcript
+```

alphagenome/source/docs/source/conf.py

@@ -0,0 +1,206 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configuration file for the Sphinx documentation builder."""
+
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import importlib.metadata
+import inspect
+import os
+import sys
+
+# The package is installed by Readthedocs before sphinx building.
+import alphagenome  # pylint: disable=unused-import, g-import-not-at-top
+import alphagenome.models.dna_client  # pylint: disable=unused-import, g-import-not-at-top
+
+# -- Project information -----------------------------------------------------
+
+project = 'alphagenome'
+project_info = importlib.metadata.metadata(project)
+author = project_info['Author']
+copyright = f'2024, {author}'  # pylint: disable=redefined-builtin
+version = project_info['Version']
+repository_url = f'https://github.com/google-deepmind/{project}'
+
+
+# The full version, including alpha/beta/rc tags
+release = version
+# Warn if links are broken
+nitpicky = True
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    'myst_nb',
+    'sphinx_design',
+    'sphinx.ext.autodoc',
+    'sphinx.ext.intersphinx',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.napoleon',
+    'sphinxcontrib.bibtex',
+    'sphinx_autodoc_typehints',
+    'sphinx.ext.mathjax',
+    'IPython.sphinxext.ipython_console_highlighting',
+    'sphinx.ext.coverage',
+    'sphinx_copybutton',
+    'sphinx_remove_toctrees',
+    'sphinx.ext.linkcode',
+]
+
+autosummary_generate = True
+autodoc_member_order = 'groupwise'
+default_role = 'literal'
+bibtex_reference_style = 'author_year'
+napoleon_google_docstring = True
+napoleon_numpy_docstring = False
+napoleon_include_init_with_doc = False
+napoleon_use_rtype = True
+napoleon_use_param = True
+myst_heading_anchors = 6  # Create heading anchors for h1-h6
+autodoc_mock_imports = [
+    'google.protobuf.runtime_version',
+    'google.protobuf.internal.builder',
+    'absl',
+    'alphagenome.protos',
+]
+remove_from_toctrees = ['api/generated/*']
+bibtex_bibfiles = ['refs.bib']
+
+myst_enable_extensions = [
+    'amsmath',
+    'colon_fence',
+    'deflist',
+    'dollarmath',
+    'html_image',
+    'html_admonition',
+    'attrs_inline',
+    'attrs_block',
+]
+
+# TODO(b/372225132): Resolve showing notebook output without executing.
+# TODO(b/372226231): Resolve not modifying notebook when building docs.
+myst_url_schemes = ['http', 'https', 'mailto']
+nb_output_stderr = 'remove'
+nb_execution_mode = 'off'
+nb_merge_streams = True
+typehints_defaults = 'braces'
+
+source_suffix = {
+    '.rst': 'restructuredtext',
+    '.ipynb': 'myst-nb',
+    '.myst': 'myst-nb',
+}
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'anndata': ('https://anndata.readthedocs.io/en/stable/', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'jax': ('https://jax.readthedocs.io/en/latest/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None),
+    'matplotlib': ('https://matplotlib.org/stable/', None),
+}
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'protos']
+
+# -- Options for autodoc -----------------------------------------------------
+
+autodoc_default_options = {
+    'member-order': 'bysource',
+    'special-members': True,
+    'exclude-members': '__repr__, __str__, __weakref__',
+}
+
+
+# -- Source code links -----------------------------------------------------
+
+
+def linkcode_resolve(domain, info):
+  """Resolve a GitHub URL corresponding to Python object."""
+  if domain != 'py':
+    return None
+
+  try:
+    mod = sys.modules[info['module']]
+  except ImportError:
+    return None
+
+  obj = mod
+  try:
+    for attr in info['fullname'].split('.'):
+      obj = getattr(obj, attr)
+  except AttributeError:
+    return None
+  else:
+    obj = inspect.unwrap(obj)
+
+  try:
+    filename = inspect.getsourcefile(obj)
+  except TypeError:
+    return None
+
+  try:
+    source, lineno = inspect.getsourcelines(obj)
+  except OSError:
+    return None
+
+  path = os.path.relpath(filename, start=os.path.dirname(alphagenome.__file__))
+  return (
+      f'{repository_url}/tree/main/src/{project}/'
+      f'{path}#L{lineno}#L{lineno + len(source) - 1}'
+  )
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+
+html_theme = 'sphinx_book_theme'
+html_title = 'AlphaGenome'
+pygments_style = 'default'
+html_theme_options = {
+    'repository_url': repository_url,
+    'repository_branch': 'main',
+    'use_repository_button': True,
+    'launch_buttons': {
+        'colab_url': 'https://colab.research.google.com',
+    },
+    'article_header_start': ['toggle-primary-sidebar.html', 'breadcrumbs'],
+    'show_prev_next': False,
+}
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+# html_static_path = ['_static']
+
+# TODO: b/377291190 - Look at adding notebook support (see haiku example)

alphagenome/source/docs/source/exploring_model_metadata.md

@@ -0,0 +1,93 @@
+# Model output metadata
+
+AlphaGenome returns predictions for 11 different output types, covering a
+variety of modalities. Here we provide details about the human model outputs and
+associated metadata to help users make informed decisions about the parameters
+of their API requests (e.g., ontology term; output types).
+
+For further details on dataset processing and precise definitions of each output
+type, including their respective units and normalization methods, please refer
+to the Methods section of the AlphaGenome paper.
+
+<!-- mdformat off(Turn off mdformat to retain grid card syntax.) -->
+<!-- mdlint off(LINK_ID) -->
+
+{#model_metadata-table1-target}
+**Table 1**: Descriptions of output types predicted by AlphaGenome.
+
+| OutputType name | Description | Units | Resolution | Unique biosamples | Total tracks |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| [RNA\_SEQ](#alphagenome.models.dna_output.OutputType.RNA_SEQ) | RNA expression as measured by RNA-seq. Includes a mixture of PolyA+ RNA and Total RNA assays. Some tracks are also stranded. | Normalized read signal | 1bp | 285 | 667 |
+| [CAGE](#alphagenome.models.dna_output.OutputType.CAGE) | RNA expression at transcription start-sites as measured by Cap Analysis Gene Expression (CAGE) assay. | Normalized read signal | 1bp | 264 | 546 |
+| [PROCAP](#alphagenome.models.dna_output.OutputType.PROCAP) | RNA expression at transcription start-sites as measured by Precision Run-On sequencing and capping (PROCAP) assay. | Normalized read signal | 1bp | 6 | 12 |
+| [DNASE](#alphagenome.models.dna_output.OutputType.DNASE) | Chromatin accessibility as measured by DNase I hypersensitive sites sequencing (DNase-seq) assay. | Normalized insertion signal | 1bp | 305 | 305 |
+| [ATAC](#alphagenome.models.dna_output.OutputType.ATAC) | Chromatin accessibility as measured by the transposase-accessible chromatin (ATAC-seq) assay. | Normalized insertion signal | 1bp | 167 | 167 |
+| [CHIP\_HISTONE](#alphagenome.models.dna_output.OutputType.CHIP_HISTONE) | Relative abundance of histone modification marks as measured by chromatin immunoprecipitation (ChIP-seq) for 24 different markers e.g. H3k27ac (see ENCODE [documentation](https://www.encodeproject.org/chip-seq/histone/)). | Fold-change over control | 128bp | 219 | 1116 |
+| [CHIP\_TF](#alphagenome.models.dna_output.OutputType.CHIP_TF) | Relative abundance of DNA-bound transcription factors as measured by ChIP-seq targeting 43 different proteins (see ENCODE [documentation](https://www.encodeproject.org/chip-seq/transcription_factor/)). | Fold-change over control | 128bp | 163 | 1617 |
+| [SPLICE\_SITES](#alphagenome.models.dna_output.OutputType.SPLICE_SITES) | Predicted location of donor or acceptor splice sites, for both the positive and negative strand, expressed as a probability (higher numbers indicate higher probability of the base being a splice site). | Predicted probability | 1bp | NA | 4 |
+| [SPLICE\_JUNCTIONS](#alphagenome.models.dna_output.OutputType.SPLICE_JUNCTIONS) | Splice junction spliced read counts, as measured by RNA-Seq. Predictions are for all possible pairings of at most 512 donors and 512 acceptors from each strand in the requested interval, where the position of donors and acceptors along the input sequence is given by predictions of splice site positions. | Normalized junction signal | 1bp | 282 | 734 |
+| [SPLICE\_SITE\_USAGE](#alphagenome.models.dna_output.OutputType.SPLICE_SITE_USAGE) | Fraction of transcripts using a splice site, as measured by RNA-seq. All reads that span a given splice site are considered, and we predict the fraction of these that use the site (donor or acceptor). | Fraction | 1bp | 282 | 734 |
+| [CONTACT\_MAPS](#alphagenome.models.dna_output.OutputType.CONTACT_MAPS) | Relative frequency of physical contact between pairwise positions (symmetric), derived from chromatin contact maps (Micro-C and Hi-C assays). Values are coarse-grained and normalized by removing the off-diagonal power law decay (as also done in [Zhou, J. 2022](https://www.nature.com/articles/s41588-022-01065-4)). | Log-fold over genomic distance-based expectation | 2048bp | 12 | 28 |
+<!-- mdlint on -->
+<!-- mdformat on -->
+
+## Track metadata
+
+To access the metadata describing each track for human outputs use:
+
+```py
+output_metadata = dna_model.output_metadata(
+    organism=dna_client.Organism.HOMO_SAPIENS
+)
+```
+
+Each predicted output type (e.g., RNA\_SEQ) contains metadata in a
+{py:class}`~pandas.DataFrame`: {py:class}`output_metadata.rna_seq
+<alphagenome.models.dna_output.OutputMetadata.rna_seq>`
+
+Each row of the {class}`~pandas.DataFrame` corresponds to a ‘track’, and each
+column contains key information for biological interpretation such as:
+
+*   `name`: Name of the track. Example: `CL:0000047 polyA plus RNA-seq`.
+*   `strand` Strand of the track, either positive (`+`), negative (`-`), or
+    unstranded (`.`).
+*   `ontology_curie`: A string ID representing the ontology term corresponding
+    to the biosample. Example: `CL:0000100`.
+*   `biosample_name`: Plain text description of the biosample. Example: `motor
+    neuron`.
+
+For a full list of metadata columns available for each output type, please see
+the [navigating data ontologies notebook](colabs/tissue_ontology_mapping), which
+demonstrates how to access and browse track metadata.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+:::{note} For `SPLICE_JUNCTION` outputs the strand information is a property of
+a junction rather than a track, so the metadata for this output type will show
+half as many rows as reported in the above table.
+:::
+
+<!-- mdformat on -->
+
+## Additional track metadata
+
+Some output types contain additional columns. For example,
+{py:class}`OutputMetadata.rna_seq
+<alphagenome.models.dna_output.OutputMetadata.rna_seq>` and
+{py:class}`OutputMetadata.splice_sites
+<alphagenome.models.dna_output.OutputMetadata.splice_sites>` also contain a
+`gtex_tissue` column, which is populated for the tracks that make predictions
+for the tissues sampled in the
+[GTEx project](https://gtexportal.org/home/samplingSitePage)
+{cite:t}`gtex2020gtex`.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+:::{note} For one tissue,
+’Brain \- Cerebellar hemisphere’, we used an alternative Uberon ID to that was
+provided in the
+[GTEx documentation](https://gtexportal.org/home/samplingSitePage)
+(‘UBERON:0002037’), to reflect Uberon’s ID for cerebellar hemisphere:
+[‘UBERON:0002245'](https://www.ebi.ac.uk/ols4/ontologies/uberon/classes/http%253A%252F%252Fpurl.obolibrary.org%252Fobo%252FUBERON_0002245).
+:::
+
+<!-- mdformat on -->

alphagenome/source/docs/source/faqs.md

@@ -0,0 +1,378 @@
+# FAQ
+
+Frequently asked questions.
+
+## Model inputs
+
+### How do I make predictions for a specific genomic region?
+
+You can define any region in either the human or mouse genome, and use the API
+to predict various outputs. See the [quick start colab](colabs/quick_start) for
+a demonstration.
+
+### How do I specify a genomic region?
+
+Using the {class}`genome.Interval<alphagenome.data.genome.Interval>` class,
+which is initialized with a chromosome, a start, and an end position.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+:::{note}
+AlphaGenome classes such as {class}`genome.Interval<alphagenome.data.genome.Interval>`
+uses 0-based indexing, consistent with the underlying Python implementations.
+
+This means an
+{class}`genome.Interval<alphagenome.data.genome.Interval>` includes the base
+pair at the `start` position up to the base pair at the `end-1` position.
+
+For example, to specify the first base pair of chromosome 1, use
+`genome.Interval('chr1', 0, 1)`. This interval has a width of 1, and contains
+only the base pair at the first position of chromosome 1.
+
+To interpret interval overlaps, remember that 0-based indexing excludes the base
+pair at the `end` position itself, such that
+`genome.Interval('chr1', 0, 1).overlaps(genome.Interval('chr1', 1, 2))`
+returns `False`.
+:::
+
+<!-- mdformat on -->
+
+### What are the reference genome versions used by the model?
+
+We use human genome assembly hg38 (GRCh38.p13.genome.fa) and mouse assembly mm10
+(GRCm38.p6.genome.fa). For other genome builds (such as hg19, for example), the
+[LiftOver](https://genome.ucsc.edu/cgi-bin/hgLiftOver) tool can be used to
+convert from hg38 coordinates to the desired assembly.
+
+### Can I make a prediction for any arbitrary DNA sequence?
+
+Yes, you can make predictions for any sequence, provided it is within the range
+of sequence lengths supported by the model. Note that model predictions have
+only been evaluated using sequences that vary by a relatively small amount from
+the reference genome (SNPs and indels), so very large differences from the human
+reference genome (for example, structural variants, sequences with a large
+amount of padding, synthetic sequences, or artificial DNA constructs) may result
+in predictions that are not as reliable.
+
+### Can I make predictions for DNA from other species?
+
+Yes, with the caveat that the model has only been trained on mouse and human
+DNA. Prediction quality is likely to degrade as evolutionary distance from these
+two species increases, but note that this has not been formally benchmarked.
+
+### What is the longest sequence the model can take as input?
+
+1MB (precisely 2^20 base-pairs long). Other sequence lengths are also supported:
+\~2KB, \~16KB, \~100KB, \~500KB.
+
+### How do I request predictions for a sequence with a length that is not in the list of supported lengths?
+
+You can use
+{func}`genome.Interval.resize<alphagenome.data.genome.Interval.resize>` to crop
+or expand your sequence length to the nearest supported length.
+
+Note that `.resize` expands sequences using the actual surrounding genomic data,
+not by adding padding.
+
+## Model outputs
+
+### How many tracks are there per output type and what do they represent?
+
+This varies from 5 to over 600. Each of the tracks refers to a particular
+cell-type or tissue, as well as other properties, such as strand or a specific
+transcription factor (for the `CHIP_TF` output type). See the
+[output metadata documentation](project:exploring_model_metadata.md#Exploring-model-metadata)
+for a full list of the output types.
+
+### How do I find out what tissue or cell-type an output ‘track’ refers to?
+
+Using the [navigating data ontologies notebook](colabs/tissue_ontology_mapping),
+you can look at the output metadata where biosample names and ontology CURIEs
+(IDs) for each track are described.
+
+### What is an ontology CURIE?
+
+CURIEs (Compact Uniform Resource Identifiers) are standardized, abbreviated
+codes (e.g., ‘UBERON:0001114’ for liver) that uniquely identify specific
+ontology terms.
+
+### Where are your ontology CURIEs sourced from?
+
+We source these from the IDs provided in the source training data. We also
+restricted the ontology types to UBERON, CL, CLO and EFO, following ENCODE
+practices. We recommend using EBI's
+[Ontology Lookup Service](https://www.ebi.ac.uk/ols4) to understand
+relationships between the ontology IDs for different tracks.
+
+### What is strandedness?
+
+DNA is double-stranded, meaning that there are two nucleotide strands that form
+the double helix. By convention, one of those molecules is designated the
+forward, or positive strand (5'->3'), and the other is designated the reverse,
+or negative strand (3'->5').
+
+Genomic assays can either be unstranded or stranded (also called
+strand-specific).
+
+*   Unstranded assays return results that do not distinguish whether a
+    measurement came from the positive or negative strand. Certain assays do not
+    generate stranded information – for example, ATAC-seq generates unstranded
+    accessibility information.
+*   Stranded (or strand-specific) assays annotate each measurement as coming
+    from the positive or negative strand. This is important for transcriptional
+    assays to distinguish between strand-specific transcripts (for example, two
+    transcripts that share a transcriptional start site but are on different
+    strands).
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+:::{note}
+Not all RNA-seq samples will be stranded, especially those that are
+from older experiments. For example, GTEx RNA-seq data is unstranded.
+:::
+
+<!-- mdformat on -->
+
+For more general information about the difference between non-stranded and
+stranded protocols and how to interpret them, there is a helpful tutorial
+[here](https://www.ecseq.com/support/ngs/how-do-strand-specific-sequencing-protocols-work).
+
+### How is strandedness handled in model outputs?
+
+In the model output metadata, we use the following symbols to designate the
+strand of a track:
+
+*   positive: `+`
+*   negative: `-`
+*   unstranded `.`
+
+For assays that were performed in a stranded (or strand-specific) manner, the
+assay will have two tracks per cell or tissue type: one for the positive (`+`)
+and another for the negative (`-`) strand.
+
+For unstranded assays, there will be a single track per cell or tissue type,
+annotated as unstranded (`.`).
+
+We provide convenience operations for manipulating
+{class}`~alphagenome.data.track_data.TrackData` based on strand information,
+such as
+{func}`~alphagenome.data.track_data.TrackData.filter_to_negative_strand`, etc.
+
+### How can I save the model outputs?
+
+For *variant effect predictions*: We recommend converting the scores into a
+pandas DataFrame. This DataFrame can then be easily exported to a common file
+format, such as a CSV file, for use with other tools or for record-keeping.
+Specific instructions and examples for this process are provided in our 'Variant
+Scoring UI' tutorial.
+
+For *genome track predictions (e.g., RNA-seq levels)*: The predicted track data
+is provided as NumPy arrays within TrackData objects. These arrays can be
+directly saved to disk using standard NumPy functions, such as `numpy.save` (for
+saving a single array to a `.npy` file) or `numpy.savez_compressed` (for saving
+multiple arrays into a single compressed `.npz` file).
+
+### What are some of the limitations of the model?
+
+AlphaGenome has several key limitations:
+
+-   *Tissue-specificity and long-range interactions*: While AlphaGenome shows
+    improvements in these areas compared to previous models, accurately
+    capturing tissue-specific effects and long-range genomic interactions
+    remains challenging for deep learning models in genomics, requiring further
+    research.
+-   *Species scope*: The model is trained and evaluated on human and mouse DNA.
+    Its performance on DNA from other species has not been determined.
+-   *Personal genomes*: The model has not yet been benchmarked for predicting
+    individual (personal) human genomes.
+-   *Molecular scope*: AlphaGenome predicts the molecular consequences of
+    genetic variations. Its direct applicability to complex trait analysis is
+    limited, as these traits also involve broader biological processes (e.g.,
+    gene function, development, environmental factors) beyond the model's
+    primary focus.
+-   *Unphased training and single sequence input*: The model processes a single
+    DNA sequence at a time and is therefore not inherently 'diploid-aware'. It
+    was trained using unphased data, meaning it could not learn to distinguish
+    between alleles inherited from the mother versus the father. Consequently,
+    its variant effect predictions do not inherently model heterozygous states
+    (i.e., the presence of both a reference and a variant allele at a site
+    simultaneously).
+
+## Visualizing predictions
+
+### How do I visualize the predicted output?
+
+You can use any tool to visualize the numerical output, but we provide a Python
+[visualization library](project:api/visualization.md#Visualization) so you can
+easily visualize the output immediately. You can use our
+[visualization basics guide](project:visualization_library_basics.md) and see
+examples of how to plot different modalities in our
+[visualizing predictions tutorial](colabs/visualization_modality_tour).
+
+### Can I design my own visualizations to work with this library?
+
+Yes. The returned figures are based on matplotlib, so should be extendible.
+Additionally, you can choose to work with the raw output data and design your
+own visualizations.
+
+### Where are the plotted transcript annotations from?
+
+Transcript annotations are sourced from standard Gene Transfer Format (GTF)
+files from GENCODE: the hg38 reference assembly (release 46) for human and the
+mm10 reference assembly (release M23) for mouse.
+
+### Am I limited to only plotting protein-coding genes, and only the longest transcript?
+
+No. If you wish to include other gene types or all transcripts (not just the
+longest), you can remove the respective calls to
+`gene_annotation.filter_protein_coding(gtf)` and
+`gene_annotation.filter_to_longest_transcript(gtf)` in your code. Note that
+including more transcripts can make the plot appear busy; you can adjust the
+`fig_height` parameter of the `TranscriptAnnotation` plot component to improve
+legibility.
+
+## Variant scoring
+
+### How do I define a variant?
+
+By creating a {class}`~alphagenome.data.genome.Variant` object.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+:::{note}
+:name: variant-position-is-1-based
+As mentioned above, AlphaGenome classes such as
+{class}`~alphagenome.data.genome.Variant` use 0-indexing, and Variant's
+{func}`~alphagenome.data.genome.Variant.start` and
+{func}`~alphagenome.data.genome.Variant.end` contain 0-indexed values.
+
+However, most variants in public databases, such as dbSNP, are provided as
+1-indexed.
+
+To enable compatibility with these annotations, the
+{class}`~alphagenome.data.genome.Variant` object is initialized with a
+1-indexed {attr}`~alphagenome.data.genome.Variant.position` attribute, which is
+then converted to 0-indexing internally. (i.e.,
+{func}`~alphagenome.data.genome.Variant.start` returns
+{attr}`~alphagenome.data.genome.Variant.position` - 1).
+
+See the {class}`~alphagenome.data.genome.Variant` docstring for more details.
+:::
+
+<!-- mdformat on -->
+
+### Are there tools to help me define variants, and run inference for them?
+
+See the
+[scoring and visualizing a single variant notebook](colabs/variant_scoring_ui)
+which walks through how to define a {class}`~alphagenome.data.genome.Variant`
+object and perform inference. Batch inference over many variants can be
+performed using the
+[batch variant scoring notebook](colabs/batch_variant_scoring) which takes a
+variant call file (VCF) as input.
+
+### Can I pass any sequence to {class}`~alphagenome.data.genome.Variant.reference_bases` or does it have to match the reference genome sequence at the variant location?
+
+You can pass any sequence to
+{class}`~alphagenome.data.genome.Variant.reference_bases`. Note that
+{func}`~alphagenome.models.dna_client.DnaClient.predict_variant` is agnostic to
+the alleles in the reference genome, but rather uses the REF/ALT alleles
+specified by the user.
+
+### Are variant predictions for insertions and deletions (indels) supported?
+
+Yes. We use left-alignment to specify indels. See
+{class}`~alphagenome.data.genome.Variant` for more details. For scoring indels,
+we adopt SpliceAI's {cite:p}`spliceai` indel alignment strategy: inserted bases
+are summarized by taking the maximum value over the inserted segment, while
+deleted bases are treated as having zero signal in the `ALT` context, thereby
+enabling consistent positional comparisons.
+
+### Which variant scorer should I use for a given modality?
+
+In practice, you can use most variant scoring strategies for any modality.
+However, we provide a recommendation for the best strategies based on our
+evaluations in the
+[variant scoring documentation](project:variant_scoring.md#variant-scoring).
+
+### Can I write my own variant scoring strategy?
+
+We do not currently support users writing their own variant scoring strategy.
+However, since variant scoring is simply aggregating REF and ALT track
+predictions, you can write your own methods for handling these values.
+
+### What is the difference between a 'quantile_score' and 'raw_score'?
+
+The 'raw_score' is the output for a particular variant scoring strategy.
+However, different tracks and modalities yield scores that are on different
+scales. For instance, the
+[Splice Sites Usage scorer](project:variant_scoring.md#splicing-splice-site-usage)
+returns values between 0 and 1, whereas the
+[Gene Expression (RNA-seq)](project:variant_scoring.md#gene-expression-rna-seq)
+scorer returns negative or positive values without bounds. To facilitate
+comparisons across tracks and different variant scoring strategies, we use an
+empirical quantiles approach (see {cite:p}`alphagenome` for full details).
+Briefly, we estimate a background distribution for each variant scorer and track
+using scores for common variants (MAF>0.01 in any GnomAD v3 population). We can
+then convert any 'raw score' into a 'quantile score', representing its rank
+within this background distribution. E.g. a variant with a quantile score of
+0.99 has a score equivalent to the 99th percentile of common variants. This
+provides a measure of predicted impact that is standardized to the same scale
+across different variant scorers and tracks. The maximum (or minimum) value
+never exceeds 0.999990 (or -0.999990), due to the number of variants used to
+compute the quantiles (~300K). Because of this, we recommend using quantile
+scores as an indicator of whether the raw score is unusually large, and use the
+'raw scores' as a measure of magnitude of the effect for a given scorer and
+track.
+
+For signed variant scores (which indicate effect direction like up-regulation or
+down-regulation), their [0,1] quantile probabilities – derived directly from the
+rank order of the original signed raw scores – are linearly transformed to a
+[-1,1] range. This rescaling ensures the quantile score reflects the
+directionality of the raw score. For instance, the 0th percentile (representing
+the most negative raw scores) maps to -1, the 50th percentile (raw scores around
+zero) to 0, and the 100th percentile (most positive raw scores) to +1.
+
+Note that quantile scores are only available for the suite of recommended
+scorers.
+
+## Other
+
+### What terms of use apply to AlphaGenome outputs?
+
+The AlphaGenome API is provided for non-commercial use only and is subject to
+the AlphaGenome
+[Terms of Service](https://deepmind.google.com/science/alphagenome/terms).
+Outputs generated by AlphaGenome should not be used for the training of other
+machine learning models.
+
+### How should I cite AlphaGenome?
+
+If you use AlphaGenome in your research, please cite using:
+
+<!-- disableFinding(SNIPPET_INVALID_LANGUAGE) -->
+
+```bibtex
+@article{alphagenome,
+  title={{AlphaGenome}: advancing regulatory variant effect prediction with a unified {DNA} sequence model},
+  author={Avsec, {\v Z}iga and Latysheva, Natasha and Cheng, Jun and Novati, Guido and Taylor, Kyle R. and Ward, Tom and Bycroft, Clare and Nicolaisen, Lauren and Arvaniti, Eirini and Pan, Joshua and Thomas, Raina and Dutordoir, Vincent and Perino, Matteo and De, Soham and Karollus, Alexander and Gayoso, Adam and Sargeant, Toby and Mottram, Anne and Wong, Lai Hong and Drot{\'a}r, Pavol and Kosiorek, Adam and Senior, Andrew and Tanburn, Richard and Applebaum, Taylor and Basu, Souradeep and Hassabis, Demis and Kohli, Pushmeet},
+  year={2025},
+  doi={https://doi.org/10.1101/2025.06.25.661532},
+  publisher={Cold Spring Harbor Laboratory},
+  journal={bioRxiv}
+}
+```
+
+<!-- enableFinding(SNIPPET_INVALID_LANGUAGE) -->
+
+### Who should I contact with issues, enquiries and feedback?
+
+Submit bugs and any code-related issues on
+[GitHub](https://github.com/google-deepmind/alphagenome). For general feedback,
+questions about usage, and/or feature requests, please use the
+[community forum](https://www.alphagenomecommunity.com) – it's actively
+monitored by our team so you're likely to find answers and insights faster. If
+you can't find what you're looking for, please get in touch with the AlphaGenome
+team at <alphagenome@google.com> and we will be happy to assist you with
+questions. We're working hard to answer all inquiries but there may be a short
+delay in our response due to the high volume we are receiving.

alphagenome/source/docs/source/index.md

@@ -0,0 +1,82 @@
+# Exploring the genome with AlphaGenome
+
+This API provides access to AlphaGenome, Google DeepMind’s unifying model for
+deciphering the regulatory code within DNA sequences.
+
+AlphaGenome offers multimodal predictions, encompassing diverse functional
+outputs such as gene expression, splicing patterns, chromatin features, and
+contact maps (see diagram below). The model analyzes DNA sequences of up to 1
+million base pairs in length and can deliver predictions at single base-pair
+resolution for most outputs. AlphaGenome achieves state-of-the-art performance
+across a range of genomic prediction benchmarks, including numerous diverse
+variant effect prediction tasks (detailed in {cite:p}`alphagenome`).
+
+The API is offered as a free service for
+[non-commercial use](https://deepmind.google.com/science/alphagenome/terms).
+Query rates vary based on demand – it is well suited for smaller to medium-scale
+analyses such as analysing a limited number of genomic regions or variants
+requiring 1000s of predictions, but is likely not suitable for large scale
+analyses requiring more than 1 million predictions.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+```{figure} /_static/model_overview.png
+:width: 600px
+:alt: overview of AlphaGenome
+:name: overview-figure
+```
+<!-- mdformat on -->
+
+## Getting started
+
+You can get started by
+[getting an API key](https://deepmind.google.com/science/alphagenome), and
+following our [Quick Start Guide](./colabs/quick_start.ipynb), or watching our
+[AlphaGenome 101 tutorial](https://youtu.be/Xbvloe13nak). Please also check out
+our installation guide, tutorials with comprehensive overviews of plotting,
+variant scoring and other use cases, and our API reference documentation.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+::::{grid} 1 1 2 3
+:gutter: 2
+
+:::{grid-item-card}
+:link: installation
+:link-type: doc
+Installation
+^^^^^^^^^^^^
+
+Install `alphagenome` locally.
+:::
+
+:::{grid-item-card}
+:link: tutorials/index
+:link-type: doc
+Tutorials
+^^^^^^^^^
+The tutorials walk through example usage of the AlphaGenome model.
+:::
+
+:::{grid-item-card}
+:link: api/index
+:link-type: doc
+API reference
+^^^^^^^^^^^^^
+
+Reference documentation for the `alphagenome` package.
+:::
+::::
+<!-- mdformat on -->
+
+``` {toctree}
+:maxdepth: 2
+:hidden: False
+
+../colabs/quick_start
+installation
+api/index
+tutorials/index
+user_guides/index
+faqs
+Community <https://www.alphagenomecommunity.com>
+references
+```

alphagenome/source/docs/source/installation.md

@@ -0,0 +1,73 @@
+# Installation
+
+The easiest way to install AlphaGenome is via the published
+[PyPi package](https://pypi.org/project/alphagenome).
+
+```bash
+$ pip install -U alphagenome
+```
+
+This will install the latest version of the `alphagenome` package.
+
+You may optionally wish to create a
+[Python Virtual Environment](https://docs.python.org/3/tutorial/venv.html) to
+prevent conflicts with your system's Python environment.
+
+## Google Colab
+
+The tutorial notebooks include a cell with the commands necessary to install
+`alphagenome` into a colab runtime.
+
+### Add API key to secrets
+
+To make model requests using the tutorial notebooks, you need to add the
+AlphaGenome API key to Colab secrets:
+
+1.  Open your Google Colab notebook and click on the 🔑 **Secrets** tab in the
+    left panel.
+1.  Create a new secret with the name `ALPHA_GENOME_API_KEY`.
+1.  Copy/paste your API key into the `Value` input box of
+    `ALPHA_GENOME_API_KEY`.
+1.  Toggle the button on the left to allow notebook access to the secret.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/secrets.png
+:width: 600px
+:alt: Image of secrets tab found on left panel.
+:name: secrets-screenshot
+```
+<!-- mdformat on -->
+
+## Running locally
+
+To install a local copy of `alphagenome`, clone a local copy of the repository
+and run `pip install`:
+
+```bash
+$ rm -rf ./alphagenome
+$ git clone https://github.com/google-deepmind/alphagenome.git
+$ pip install -e ./alphagenome
+```
+
+We strongly recommend using a virtual environment management system such as
+[miniconda](https://docs.anaconda.com/miniconda/) or
+[uv](https://docs.astral.sh/uv/pip/environments/).
+
+In the case of miniconda, installation would be achieved with the following:
+
+```bash
+conda create -n alphagenome-env python=3.11
+conda activate alphagenome-env
+pip install -e ./alphagenome
+```
+
+### Updating `alphagenome`
+
+Assuming the relevant virtual environment is already activated:
+
+```bash
+cd ./alphagenome
+git pull
+pip install --upgrade .
+```

alphagenome/source/docs/source/references.md

@@ -0,0 +1,7 @@
+# References
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+```{bibliography}
+:cited:
+```
+<!-- mdformat on -->

alphagenome/source/docs/source/refs.bib

@@ -0,0 +1,50 @@
+@article{alphagenome,
+  title={{AlphaGenome}: advancing regulatory variant effect prediction with a unified {DNA} sequence model},
+  author={Avsec, {\v Z}iga and Latysheva, Natasha and Cheng, Jun and Novati, Guido and Taylor, Kyle R. and Ward, Tom and Bycroft, Clare and Nicolaisen, Lauren and Arvaniti, Eirini and Pan, Joshua and Thomas, Raina and Dutordoir, Vincent and Perino, Matteo and De, Soham and Karollus, Alexander and Gayoso, Adam and Sargeant, Toby and Mottram, Anne and Wong, Lai Hong and Drot{\'a}r, Pavol and Kosiorek, Adam and Senior, Andrew and Tanburn, Richard and Applebaum, Taylor and Basu, Souradeep and Hassabis, Demis and Kohli, Pushmeet},
+  year={2025},
+  doi={https://doi.org/10.1101/2025.06.25.661532},
+  publisher={Cold Spring Harbor Laboratory},
+  journal={bioRxiv}
+}
+
+@article{gtex2020gtex,
+  title={The GTEx Consortium atlas of genetic regulatory effects across human tissues},
+  author={GTEx Consortium},
+  journal={Science},
+  volume={369},
+  number={6509},
+  pages={1318--1330},
+  year={2020},
+  publisher={American Association for the Advancement of Science}
+}
+
+@article{zhou2022sequence,
+  title={Sequence-based modeling of three-dimensional genome architecture from kilobase to chromosome scale},
+  author={Zhou, Jian},
+  journal={Nature genetics},
+  volume={54},
+  number={5},
+  pages={725--734},
+  year={2022},
+  publisher={Nature Publishing Group US New York}
+}
+
+@article{borzoi,
+  title={Predicting RNA-seq coverage from DNA sequence as a unifying model of gene regulation},
+  author={Linder, Johannes and Srivastava, Divyanshi and Yuan, Han and Agarwal, Vikram and Kelley, David R},
+  journal={Nature Genetics},
+  pages={1--13},
+  year={2025},
+  publisher={Nature Publishing Group US New York}
+}
+
+@article{spliceai,
+  title={Predicting splicing from primary sequence with deep learning},
+  author={Jaganathan, Kishore and Panagiotopoulou, Sofia Kyriazopoulou and McRae, Jeremy F and Darbandi, Siavash Fazel and Knowles, David and Li, Yang I and Kosmicki, Jack A and Arbelaez, Juan and Cui, Wenwu and Schwartz, Grace B and others},
+  journal={Cell},
+  volume={176},
+  number={3},
+  pages={535--548},
+  year={2019},
+  publisher={Elsevier}
+}

alphagenome/source/docs/source/tutorials/index.md

@@ -0,0 +1,55 @@
+# Tutorials
+
+``` {toctree}
+:maxdepth: 1
+:hidden:
+
+../colabs/visualization_modality_tour
+../colabs/variant_scoring_ui
+../colabs/tissue_ontology_mapping
+../colabs/batch_variant_scoring
+../colabs/example_analysis_workflow
+```
+
+<!-- mdformat off(Turn off mdformat to retain grid card syntax.) -->
+
+::::{grid} 1 1 2 3
+:gutter: 2
+
+:::{grid-item-card} Visualizing predictions
+:link: ../colabs/visualization_modality_tour
+:link-type: doc
+
+How to visualize different output modalities.
+:::
+
+:::{grid-item-card} Scoring and visualizing a single variant
+:link: ../colabs/variant_scoring_ui
+:link-type: doc
+
+Tool for scoring and visualizing a single variant across multiple modalities.
+:::
+
+:::{grid-item-card} Navigating data ontologies
+:link: ../colabs/tissue_ontology_mapping
+:link-type: doc
+
+Tool for fetching ontology IDs for a given tissue.
+
+:::
+
+:::{grid-item-card} Batch variant scoring
+:link: ../colabs/batch_variant_scoring
+:link-type: doc
+
+Tool for scoring many variants at once.
+:::
+
+:::{grid-item-card} Example analysis workflow
+:link: ../colabs/example_analysis_workflow
+:link-type: doc
+
+Example analysis of TAL1 locus.
+:::
+
+<!-- mdformat on -->

alphagenome/source/docs/source/user_guides/index.md

@@ -0,0 +1,46 @@
+# User guides
+
+``` {toctree}
+:maxdepth: 1
+:hidden:
+
+../colabs/essential_commands
+../exploring_model_metadata
+../variant_scoring
+../visualization_library_basics
+```
+
+<!-- mdformat off(Turn off mdformat to retain grid card syntax.) -->
+
+::::{grid} 1 1 2 3
+:gutter: 2
+
+:::{grid-item-card} Essential commands
+:link: ../colabs/essential_commands
+:link-type: doc
+
+Essential commands for navigating AlphaGenome.
+:::
+
+:::{grid-item-card} Model output metadata
+:link: ../exploring_model_metadata
+:link-type: doc
+
+A summary of model outputs and associated metadata.
+:::
+
+:::{grid-item-card} Variant scoring
+:link: ../variant_scoring
+:link-type: doc
+
+Overview of how variant scores are calculated.
+:::
+
+:::{grid-item-card} Visualization basics
+:link: ../visualization_library_basics
+:link-type: doc
+
+Guide to visualization tools.
+:::
+
+<!-- mdformat on -->

alphagenome/source/docs/source/variant_scoring.md

@@ -0,0 +1,257 @@
+# How variant scoring works
+
+A genomic variant is a difference identified in an individual's genome sequence
+when compared to the reference genome sequence. Many genomic variants likely
+have no appreciable impact, but it can be challenging to identify those that do
+have a particular molecular effect. AlphaGenome predictions can be used to score
+variants and help bridge this gap.
+
+To do so, the variant is treated as a pair of sequences: reference (`REF`) and
+alternate (`ALT`). The variant effect is estimated by comparing AlphaGenome
+predictions for these two sequences across different modalities returned by the
+model.
+
+## Detailed steps
+
+Variant scoring is implemented as follows:
+
+### Make `REF` and `ALT` predictions for given modality
+
+Variant scoring begins by generating predictions for both the reference and
+alternative alleles of a variant, restricted to a given modality of interest
+(ex: `RNA-SEQ`, `ATAC`, etc.).
+
+The model input at this stage are `REF` and `ALT` sequences, whose sequence
+interval contains the variant of interest.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/variant_scoring_ref_alt.png
+:width: 500px
+:alt: Make `REF` and `ALT` predictions for given modality.
+:name: variant-scoring-1
+```
+
+<!-- mdformat on -->
+
+### Optional - perform indel alignment
+
+For insertion or deletion (indel) variants, the `ALT` allele's prediction
+profile is aligned to the `REF` allele's coordinate space. Inserted bases are
+summarized by taking the maximum value over the inserted segment, while deleted
+bases are treated as having zero signal in the `ALT` context, thereby enabling
+consistent positional comparisons.
+
+### Apply spatial mask
+
+A spatial mask defines regions of interest within the interval containing the
+variant. This mask can be centered on the variant or encompass a gene (gene
+body, exons, or TSS, based on annotations from a GTF file).
+
+At this stage, values outside of the mask are discarded.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/variant_scoring_spatial_mask.png
+:width: 500px
+:alt: Apply spatial mask.
+:name: variant-scoring-2
+```
+
+<!-- mdformat on -->
+
+### Aggregate spatially and compute `ALT - REF`
+
+Aggregation occurs at this stage, which includes the following:
+
+*   reduction along the spatial axis, using `mean` or `sum`, etc.
+*   (optional) scaling, such as a $log$ or $l^2$ transform.
+*   difference between `ALT - REF`.
+
+The final outcome is a single scalar value per track.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/variant_scoring_spatial_compute.png
+:width: 500px
+:alt: Aggregate spatially and compute `ALT - REF`.
+:name: variant-scoring-3
+```
+
+<!-- mdformat on -->
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{note}
+Aggregation logic is encapsulated in the options listed in
+{class}`~alphagenome.models.variant_scorers.AggregationType`.
+
+The naming of the options reflects the order of operations of each of the above
+steps, with the right-most operation applied first to the model predictions.
+
+For example,
+{class}`~alphagenome.models.variant_scorers.AggregationType.DIFF_SUM_LOG2`,
+applies a log transform, then a sum, to track data. It then returns the
+difference between `ALT - REF`.
+
+Some aggregation options may apply the exact same steps, but in a different order.
+
+Regardless of the order of operations, each aggregation type returns one single
+scalar value per track.
+```
+
+<!-- mdformat on -->
+
+### Optional - aggregate tracks
+
+After variant scoring is completed, optional track selection and additional
+aggregation can be applied.
+
+Suggestions include additional aggregation (mean, max, sum, etc.) over:
+
+*   All tracks
+*   Subsets of tracks
+
+Or, a single track of interest can be chosen, i.e., from a particular sample.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/variant_scoring_aggregate.png
+:width: 500px
+:alt: Optional - aggregate tracks.
+:name: variant-scoring-4
+```
+
+<!-- mdformat on -->
+
+## Modality-specific recommended variant scorers
+
+We have established a set of recommended variant scorers, available via
+{func}`~alphagenome.models.variant_scorers.get_recommended_scorers`, covering
+diverse genomic modalities as outlined below:
+
+### Gene Expression (RNA-seq)
+
+Variant scores quantify the impact on overall gene transcript abundance.
+
+*   comparison: predicted RNA coverage between `REF` and `ALT` alleles
+*   mask: exons for a gene of interest
+*   aggregation: Log-fold change of gene expression level between the `ALT` and
+    `REF` alleles: {math}`\log(mean(ALT) + 0.001) - log(mean(REF) + 0.001)`
+
+### Polyadenylation Site (PAS) Usage
+
+This follows Borzoi's {cite:p}`borzoi` methodology for scoring polyadenylation
+quantitative trait loci (paQTLs), which captures the variant's impact on RNA
+isoform production.
+
+*   comparison: predicted RNA coverage between `REF` and `ALT` alleles
+*   mask: local 400-bp windows around 3' cleavage junctions
+*   aggregation: Maximum absolute log-fold change of isoform ratios
+    (distal/proximal PAS usage) between `REF` and `ALT`, considering all
+    proximal/distal splits.
+
+### TSS Activity (CAGE, PRO-cap)
+
+Variant scores quantify local changes at TSSs.
+
+*   comparison: predicted CAGE or PRO-cap coverage between `REF` and `ALT`
+    alleles
+*   mask: local 501-bp window centered at the variant
+*   aggregation: Log2-ratio of summed signals: {math}`log2[(sum(ALT) + 1) /
+    (sum(REF) + 1)]`
+
+### Chromatin Accessibility (ATAC-seq, DNase-seq)
+
+Variant scores quantify local accessibility changes.
+
+*   comparison: predicted ATAC-seq or DNase-cap coverage between `REF` and `ALT`
+    alleles
+*   mask: local 501-bp window centered at the variant
+*   aggregation: Log2-ratio of summed signals: {math}`log2[(sum(ALT) + 1) /
+    (sum(REF) + 1)]`
+
+### Transcription Factor Binding (ChIP-TF)
+
+Variant scores quantify changes in TF binding intensity.
+
+*   comparison: predicted ChIP-TF coverage between `REF` and `ALT` alleles
+*   mask: local 501-bp window centered at the variant
+*   aggregation: Log2-ratio of summed signals: {math}`log2[(sum(ALT) + 1) /
+    (sum(REF) + 1)]`
+
+### Histone Modifications (ChIP-Histone)
+
+Variant scores quantify changes in histone modifications.
+
+*   comparison: predicted ChIP-Histone coverage between `REF` and `ALT` alleles
+*   mask: local 2001-bp window centered at the variant
+*   aggregation: Log2-ratio of summed signals: {math}`log2[(sum(ALT) + 1) /
+    (sum(REF) + 1)]`
+
+### Splicing (Splice Sites)
+
+Variant scores quantify changes in the class assignment probabilities (acceptor,
+donor) at all potential splice sites within a gene body.
+
+*   comparison: class assignment probabilities for `REF` and `ALT` alleles
+*   mask: gene body for a gene of interest
+*   aggregation: Maximum absolute difference of predicted splice site
+    probabilities across the gene body: {math}`max(|ALT - REF|)`
+
+### Splicing (Splice Site Usage)
+
+Variant scores quantify changes in the usage of splice sites (i.e., increased or
+decreased fractions).
+
+*   comparison: predicted splice site usage between `REF` and `ALT` alleles
+*   mask: gene body for a gene of interest
+*   aggregation: Maximum absolute difference of predicted splice site usage
+    across the gene body: {math}`max(|ALT - REF|)`
+
+### Splicing (Splice Junctions)
+
+Variant scores quantify changes in the predicted RNA-seq reads spanning a
+junction, which is a function of both expression level, splice site usage and
+splicing efficiency.
+
+*   comparison: predicted paired junction counts between `REF` and `ALT` alleles
+*   mask: top-k splice sites for a gene of interest (including annotated and
+    predicted splice sites)
+*   aggregation: Maximum absolute log-fold change of predicted junction counts
+    across splice site pairs of interest: {math}`max(|log(ALT) - log(REF)|)`
+
+### 3D Genome Contact (Contact Maps)
+
+Variant scores quantify local contact disruption.
+
+*   comparison: predicted contact frequencies between `REF` and `ALT` alleles
+*   mask: local 1MB window centered at the variant
+*   aggregation: Mean absolute difference of contact frequencies, for all
+    interactions involving the variant-containing bin.
+
+### Active Allele Scorers
+
+In addition to the differential scores described above, we also provide scoring
+configurations that capture the absolute activity level associated with one of
+the alleles, rather than quantifying the change between `REF` and `ALT`. This is
+calculated by taking the maximum of the aggregated signals from the `REF` and
+`ALT` alleles over the masked central window or gene region.
+
+We provide recommended active allele scorers for the following modalities:
+
+*   Gene expression (RNA-seq): {math}`max(mean(ALT), mean(REF))` across exons
+    for a gene of interest
+*   TSS activity (CAGE, PRO-cap): {math}`max(sum(ALT), sum(REF))` within a local
+    501-bp window centered at the variant
+*   Chromatin Accessibility (ATAC-seq, DNase-seq): {math}`max(sum(ALT),
+    sum(REF))` within a local 501-bp window centered at the variant
+*   Transcription Factor binding (ChIP-TF): {math}`max(sum(ALT), sum(REF))`
+    within a local 501-bp window centered at the variant
+*   Histone modifications (ChIP-Histone): {math}`max(sum(ALT), sum(REF))` within
+    a local 2001-bp window centered at the variant
+
+## Available variant scorers
+
+For more on the types of variant scorers and how they work, visit the
+[API documentation](api/models.md#variant-scorers).

alphagenome/source/docs/source/visualization_library_basics.md

@@ -0,0 +1,153 @@
+# Visualization basics
+
+<!-- disableFinding(LINK_ID) -->
+
+AlphaGenome predicts a variety of output types with different data shapes and
+biological interpretations ([table](#viz-table)). We provide
+[`alphagenome.visualization`](project:api/visualization.md) to generate
+matplotlib figures from model API outputs, which we outline here.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{tip}
+See the {doc}`visualizing predictions tutorial </colabs/visualization_modality_tour>`
+for worked examples of plotting different modalities.
+```
+
+<!-- mdformat on -->
+
+## Plot
+
+The key function, {func}`~alphagenome.visualization.plot_components.plot`, takes
+as input a list of components and returns a {class}`matplotlib.figure.Figure`.
+
+## Components
+
+A component is a light wrapper around a model output (such as predicted genomic
+tracks, splice junctions, etc) and specifies plot aesthetics. Each component
+maps to one vertically stacked subplot in the final figure (see blue text in the
+[figure](#viz-figure)). Each component has an independent y-axis but shares a
+common x-axis, corresponding to the length of the DNA interval, in base pairs
+(bp).
+
+Several default components are available, each designed to best visually
+represent different modalities and data shapes returned by the model API (see
+[table](#viz-table)).
+
+## Annotations
+
+Additional figure elements specific to the DNA interval, but outside of
+components -- such as locations of promoters or variants -- can be overlaid via
+a list of annotations that are passed to
+{func}`~alphagenome.visualization.plot_components.plot`.
+
+## Custom plotting
+
+For users interested in configuring novel components, extend the
+{func}`~alphagenome.visualization.plot_components.AbstractComponent` and
+{func}`~alphagenome.visualization.plot_components.AbstractAnnotation` base
+classes.
+
+Any other data supplied by the user can be visualized using this library as is,
+as long as it is provided to
+[`plot_components`](project:api/visualization.md#plot-components) in the format
+required e.g. {class}`~alphagenome.data.track_data.TrackData` for
+{class}`~alphagenome.visualization.plot_components.Tracks`.
+
+<!-- mdformat off(Turn off mdformat to retain myst syntax.) -->
+
+```{figure} /_static/visualization_overview.png
+:height: 600px
+:alt: visualization library description/overview
+:name: viz-figure
+
+Illustrative diagram of visualization library. Blue text indicates
+[`plot_components`](<project:api/visualization.md#plot-components>) classes, and purple text indicates arguments to
+[`plot_components`](<project:api/visualization.md#plot-components>) that adjust figure-wide aesthetics
+```
+
+```{list-table} Plotting components and annotation classes.
+:widths: 10 30 10 10 30 10
+:header-rows: 1
+:name: viz-table
+
+*   - Component name plot\_components.\*
+    -   Description
+    -   Example figure
+    -   Data shape supported
+    -   Recommended model outputs
+    -   Good for visualising variants?
+*   - {class}`~alphagenome.visualization.plot_components.Tracks`
+    -   A line-plot visualizing a scalar value at each genomic position (or
+        coarser resolution) e.g. predictions of RNA\_SEQ for a specific
+    -   Colab cell
+    -   1D
+    -   All except SPLICE\_JUNCTIONS; CONTACT\_MAPS
+    -   No
+*   - {class}`~alphagenome.visualization.plot_components.OverlaidTracks`
+    -   A line-plot as for Tracks, but with two separate lines on the same axis
+        with different colors e.g. predictions of RNA\_SEQ for the Reference and
+        Alternative sequence defined by a variant.
+    -   Colab cell
+    -   1D x 2
+    -   All except SPLICE\_JUNCTIONS; CONTACT\_MAPS
+    -   Yes
+*   - {class}`~alphagenome.visualization.plot_components.Sashimi`
+    -   A series of arcs, each representing a scalar value for a pair of genomic
+        positions (e.g. splice junctions). The thickness of the arcs are
+        determined by the relative sizes of the scalars.
+    -   Colab cell
+    -   2D (sparse)
+    -   SPLICE\_JUNCTIONS
+    -   Yes
+*   - {class}`~alphagenome.visualization.plot_components.SeqLogo`
+    -   A sequence of letters (bases) with heights corresponding to a single
+        scalar value per genomic position (e.g. from contribution scores).
+    -   Colab cell
+    -   1D \+ sequence
+    -   ISM contribution scores
+    -   Yes
+*   - {class}`~alphagenome.visualization.plot_components.ContactMaps`
+    -   A heatmap visualizing a matrix of scalars (e.g. predicted DNA-DNA
+        contacts), one for each pair of genomic positions in an interval.
+    -   Colab cell
+    -   2D
+    -   CONTACT\_MAPS
+    -   No
+*   - {class}`~alphagenome.visualization.plot_components.ContactMapsDiff`
+    -   A heatmap as for ContactMaps, but with a diverging color map centered on
+        zero (white) to represent values derived from differences (e.g. ALT \-
+        REF)
+    -   Colab cell
+    -   2D
+    -   CONTACT\_MAPS
+    -   Yes
+*   - {class}`~alphagenome.visualization.plot_components.TranscriptAnnotation`
+    -   Horizontal lines representing locations of transcripts. Exons, introns,
+        untranslated regions, and direction of transcription are indicated by
+        differences in line thickness.
+    -   Colab cell
+    -   Interval(s)
+    -   N/A
+    -   No
+*   - {class}`~alphagenome.visualization.plot_components.VariantAnnotation`
+    -   A semi-transparent rectangle (or vertical line if a variant) spanning
+        all plot components, indicating the location of an interval (or
+        variant). The interval (variant) is optionally labeled.
+    -   Colab cell
+    -   Interval(s) or Variant(s)
+    -   N/A
+    -   Yes
+*   - {class}`~alphagenome.visualization.plot_components.AbstractComponent`
+    -   This is an abstract class, which is the parent class of most
+        plot\_components.\*. A user can define their own component class,
+        provided it adheres to the structure specified by AbstractComponent. The
+        workhorse method is plot\_ax(), which populates a matplotlib.axes.Axes
+        object with visuals defined by the input data.
+    -   N/A
+    -   N/A
+    -   N/A
+    -   N/A
+```
+
+<!-- mdformat on -->

alphagenome/source/hatch_build.py

@@ -0,0 +1,49 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Hatch build hook to generate Python bindings for protos."""
+
+import os
+from typing import Any
+from grpc_tools import protoc
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface  # pylint: disable=g-importing-member
+
+
+_ROOT_DIR = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'src')
+
+# Tuple of proto message definitions to build Python bindings for. Paths must
+# be relative to root directory.
+_ALPHAGENOME_PROTOS = (
+    'alphagenome/protos/dna_model.proto',
+    'alphagenome/protos/dna_model_service.proto',
+    'alphagenome/protos/tensor.proto',
+)
+
+
+class GenerateProtos(BuildHookInterface):
+  """Generates Python protobuf bindings for alphagenome.protos."""
+
+  def initialize(self, version: str, build_data: dict[str, Any]) -> None:
+    del version, build_data  # Unused.
+
+    for proto_path in _ALPHAGENOME_PROTOS:
+      proto_args = [
+          'grpc_tools.protoc',
+          f'--proto_path={_ROOT_DIR}',
+          f'--python_out={_ROOT_DIR}',
+          f'--grpc_python_out={_ROOT_DIR}',
+          os.path.join(_ROOT_DIR, proto_path),
+      ]
+      if protoc.main(proto_args) != 0:
+        raise RuntimeError(f'ERROR: {proto_args}')

alphagenome/source/pyproject.toml

@@ -0,0 +1,131 @@
+[build-system]
+build-backend = 'hatchling.build'
+requires = ['hatchling', 'grpcio-tools<=1.67.1', 'importlib-resources']
+
+
+[project]
+name = 'alphagenome'
+description = 'A Python SDK for interacting and visualizing genomic models.'
+readme = 'README.md'
+dynamic = ['version']
+license = { file = 'LICENSE' }
+requires-python = '>=3.10'
+authors = [
+    {name = 'Google LLC'},
+    {email = 'alphagenome@google.com'},
+]
+keywords = [
+    'python',
+    'machine learning',
+    'genomics'
+]
+classifiers=[
+    'Development Status :: 4 - Beta',
+    'Environment :: Console',
+    'Intended Audience :: Science/Research',
+    'License :: OSI Approved :: Apache Software License',
+    'Operating System :: OS Independent',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Topic :: Scientific/Engineering :: Artificial Intelligence',
+]
+dependencies=[
+    # keep-sorted start
+    'absl-py',
+    'anndata',
+    'grpcio>=1.67.1',
+    'immutabledict',
+    'intervaltree',
+    'jaxtyping',
+    'matplotlib',
+    'ml_dtypes',
+    'numpy',
+    'pandas',
+    'protobuf>=5.28.3',
+    'pyarrow',
+    'scipy',
+    'seaborn',
+    'tqdm',
+    'typeguard',
+    'typing_extensions',
+    'zstandard',
+    # keep-sorted end
+]
+
+[project.urls]
+Repository = 'https://github.com/google-deepmind/alphagenome'
+Documentation = 'https://www.alphagenomedocs.com/'
+
+[project.optional-dependencies]
+dev = [
+  'hatch',
+]
+docs = [
+    'ipykernel',
+    'ipython',
+    'myst-nb',
+    'sphinx>=5.0',
+    'sphinx-autodoc-typehints',
+    'sphinx-book-theme',
+    'sphinx-copybutton',
+    'sphinx-remove-toctrees',
+    'sphinx-design',
+    'sphinxcontrib-bibtex>=1.0.0',
+]
+scripts = [
+    'absl-py',
+    'pyarrow',
+    'pyranges',
+]
+
+# Calls hatch_build.py to generate Python bindings for protos.
+[tool.hatch.build.hooks.custom]
+
+[tool.hatch.version]
+path = 'src/alphagenome/__init__.py'
+
+[tool.hatch.envs.default]
+installer = 'uv'
+
+[tool.setuptools.packages.find]
+include = ['README.md', 'LICENSE']
+exclude = ['*_test.py', 'examples']
+
+[tool.hatch.envs.hatch-test]
+default-args = []
+extra-dependencies=['google-benchmark', 'typeguard==2.13.3']
+parallel = true
+
+
+[tool.hatch.envs.hatch-test.env-vars]
+MPLBACKEND = 'agg'
+
+[[tool.hatch.envs.hatch-test.matrix]]
+# Use hatch test --all to run tests on all supported Python versions.
+python = ['3.13', '3.12', '3.11', '3.10']
+
+[tool.hatch.envs.check]
+dependencies = [
+  'pyink>=24.3.0',
+  'pylint>=2.6.0',
+]
+# Do not install dependencies for the check environment.
+detached = true
+
+[tool.hatch.envs.check.scripts]
+format = 'pyink . --check'
+lint = 'pylint .'
+all = [
+  'format',
+  'lint',
+]
+
+[tool.pyink]
+# Formatting configuration to follow Google style-guide
+line-length = 80
+unstable = true
+pyink-indentation = 2
+pyink-use-majority-quotes = true
+exclude = 'src/alphagenome/protos'

alphagenome/source/scripts/process_gtf.py

@@ -0,0 +1,42 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Script to process GTF into feather file."""
+
+from absl import app
+from absl import flags
+from absl import logging
+import pyranges
+
+
+_GTF_PATH = flags.DEFINE_string(
+    'gtf_path', None, 'Path to GTF file.', required=True
+)
+_OUTPUT_PATH = flags.DEFINE_string(
+    'output_path', None, 'Path to output feather file.', required=True
+)
+
+
+def main(_) -> None:
+  logging.info('Reading GTF from %s', _GTF_PATH.value)
+  gtf = pyranges.read_gtf(_GTF_PATH.value, as_df=True)
+
+  gtf['gene_id_nopatch'] = gtf['gene_id'].str.split('.', expand=True)[0]
+
+  logging.info('Writing GTF to %s', _OUTPUT_PATH.value)
+  gtf.to_feather(_OUTPUT_PATH.value)
+
+
+if __name__ == '__main__':
+  app.run(main)

alphagenome/source/src/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+src Package Initialization File
+"""

alphagenome/source/src/alphagenome/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A Python SDK for interacting and visualizing genomic models."""
+
+
+__version__ = '0.2.0'

alphagenome/source/src/alphagenome/colab_utils.py

@@ -0,0 +1,62 @@
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Utility functions for Google Colab."""
+
+import os
+
+
+def get_api_key(secret: str = 'ALPHA_GENOME_API_KEY'):
+  """Returns API key from environment variable or Colab secrets.
+
+  Tries to retrieve the API key from the environment first. If not found,
+  attempts to retrieve it from Colab secrets (if running in Colab).
+
+  Args:
+    secret: The name of the environment variable or Colab secret key to
+      retrieve.
+
+  Raises:
+    ValueError: If the API key cannot be found in the environment or Colab
+      secrets.
+  """
+
+  if api_key := os.environ.get(secret):
+    return api_key
+
+  try:
+    # pylint: disable=g-import-not-at-top, import-outside-toplevel
+    from google.colab import userdata  # pytype: disable=import-error
+    # pylint: enable=g-import-not-at-top, import-outside-toplevel
+
+    try:
+      api_key = userdata.get(secret)
+      return api_key
+    except (
+        userdata.NotebookAccessError,
+        userdata.SecretNotFoundError,
+        userdata.TimeoutException,
+    ) as e:
+      raise ValueError(
+          f'Cannot find or access API key in Colab secrets with {secret=}. Make'
+          ' sure you have added the API key to Colab secrets and enabled'
+          ' access. See'
+          ' https://www.alphagenomedocs.com/installation.html#add-api-key-to-secrets'
+          ' for more details.'
+      ) from e
+  except ImportError:
+    # Not running in Colab.
+    pass
+
+  raise ValueError(f'Cannot find API key with {secret=}.')

alphagenome/source/src/alphagenome/colab_utils_test.py

@@ -0,0 +1,68 @@
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+from unittest import mock
+
+from absl.testing import absltest
+from alphagenome import colab_utils
+
+
+_TEST_SECRET_KEY = '_TEST_ALPHAGENOME_API_KEY'
+
+
+class ColabUtilsTest(absltest.TestCase):
+
+  def test_get_api_key_from_environment(self):
+    with mock.patch.dict(os.environ, {_TEST_SECRET_KEY: 'foo'}):
+      self.assertEqual(colab_utils.get_api_key(_TEST_SECRET_KEY), 'foo')
+
+  def test_get_api_key_from_environment_not_found_raises_error(self):
+    with self.assertRaisesRegex(
+        ValueError,
+        f"Cannot find API key with secret='{_TEST_SECRET_KEY}'.",
+    ):
+      _ = colab_utils.get_api_key(_TEST_SECRET_KEY)
+
+  def test_get_api_key_from_colab_secrets(self):
+    mock_colab = mock.MagicMock()
+    mock_colab.userdata.get.return_value = 'bar'
+
+    with mock.patch.dict(
+        sys.modules, {'google': mock.MagicMock(), 'google.colab': mock_colab}
+    ):
+      self.assertEqual(colab_utils.get_api_key(), 'bar')
+
+  def test_get_api_key_from_colab_secrets_not_found_raises_error(self):
+    mock_colab = mock.MagicMock()
+    mock_colab.userdata.NotebookAccessError = Exception
+    mock_colab.userdata.SecretNotFoundError = Exception
+    mock_colab.userdata.TimeoutException = Exception
+
+    mock_colab.userdata.get.side_effect = Exception()
+
+    with mock.patch.dict(
+        sys.modules, {'google': mock.MagicMock(), 'google.colab': mock_colab}
+    ):
+      secret = 'my_secret'
+      with self.assertRaisesRegex(
+          ValueError,
+          f'Cannot find or access API key in Colab secrets with {secret=}.',
+      ):
+        _ = colab_utils.get_api_key(secret)
+
+
+if __name__ == '__main__':
+  absltest.main()

alphagenome/source/src/alphagenome/data/__init__.py

@@ -0,0 +1,15 @@
+# Copyright 2024 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Data classes for interacting and visualizing genomic models."""

alphagenome/source/src/alphagenome/data/fold_intervals.py

@@ -0,0 +1,115 @@
+# Copyright 2025 Google LLC.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Genomics intervals used for training model folds."""
+
+import enum
+
+from alphagenome.models import dna_client
+import immutabledict
+import pandas as pd
+
+
+_DEFAULT_EXAMPLE_REGIONS = immutabledict.immutabledict({
+    dna_client.Organism.HOMO_SAPIENS: (
+        'https://github.com/calico/borzoi/raw/'
+        '5c9358222b5026abb733ed5fb84f3f6c77239b37/data/sequences_human.bed.gz'
+    ),
+    dna_client.Organism.MUS_MUSCULUS: (
+        'https://github.com/calico/borzoi/raw/'
+        '5c9358222b5026abb733ed5fb84f3f6c77239b37/data/sequences_mouse.bed.gz'
+    ),
+})
+
+
+class Subset(enum.Enum):
+  """Subset of the data."""
+
+  TRAIN = 0
+  VALID = 1
+  TEST = 2
+
+
+# Fold ONE is aligned with all trained Borzoi checkpoints: 3 and 4 are held out.
+_VALID_FOLD = immutabledict.immutabledict({
+    0: 'fold0',
+    1: 'fold3',
+    2: 'fold2',
+    3: 'fold6',
+    -1: 'fold0',
+})
+
+_TEST_FOLD = immutabledict.immutabledict({
+    0: 'fold1',
+    1: 'fold4',
+    2: 'fold5',
+    3: 'fold7',
+    -1: 'fold1',
+})
+
+_MODEL_VERSION_TO_FOLD = immutabledict.immutabledict({
+    dna_client.ModelVersion.FOLD_0: 0,
+    dna_client.ModelVersion.FOLD_1: 1,
+    dna_client.ModelVersion.FOLD_2: 2,
+    dna_client.ModelVersion.FOLD_3: 3,
+    dna_client.ModelVersion.ALL_FOLDS: -1,
+})
+
+
+def get_all_folds() -> list[str]:
+  """Returns the names of all data folds."""
+  return [f'fold{i}' for i in range(8)]
+
+
+def get_fold_names(
+    model_version: dna_client.ModelVersion, subset: Subset
+) -> list[str]:
+  """Returns the data folds used for the model version."""
+  match subset:
+    case Subset.VALID:
+      return [_VALID_FOLD[_MODEL_VERSION_TO_FOLD[model_version]]]
+    case Subset.TEST:
+      return [_TEST_FOLD[_MODEL_VERSION_TO_FOLD[model_version]]]
+    case Subset.TRAIN:
+      all_folds = get_all_folds()
+      if _MODEL_VERSION_TO_FOLD[model_version] == -1:
+        return all_folds
+      remove_folds = get_fold_names(
+          model_version, Subset.VALID
+      ) + get_fold_names(model_version, Subset.TEST)
+      for fold in remove_folds:
+        all_folds.remove(fold)
+      return all_folds
+    case _:
+      raise ValueError(f'Unknown {subset=}')
+
+
+def get_fold_intervals(
+    model_version: dna_client.ModelVersion,
+    organism: dna_client.Organism,
+    subset: Subset,
+    example_regions_path: str | None = None,
+) -> pd.DataFrame:
+  """Returns the training intervals for the model version."""
+  if example_regions_path is None:
+    example_regions_path = _DEFAULT_EXAMPLE_REGIONS[organism]
+
+  example_regions = pd.read_csv(
+      example_regions_path,
+      sep='\t',
+      names=['chromosome', 'start', 'end', 'fold'],
+  )
+  return example_regions[
+      example_regions.fold.isin(get_fold_names(model_version, subset))
+  ]