deepscenic 0.1.0__tar.gz

deepscenic-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,48 @@
+name: Bug report
+description: Report something that is broken or incorrect
+labels: bug
+body:
+  - type: markdown
+    attributes:
+      value: |
+        **Note**: Please read [this guide](https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports)
+        detailing how to provide the necessary information for us to reproduce your bug. In brief:
+          * Please provide exact steps how to reproduce the bug in a clean Python environment.
+          * In case it's not clear what's causing this bug, please provide the data or the data generation procedure.
+          * Sometimes it is not possible to share the data, but usually it is possible to replicate problems on publicly
+            available datasets or to share a subset of your data.
+
+  - type: textarea
+    id: report
+    attributes:
+      label: Report
+      description: A clear and concise description of what the bug is.
+    validations:
+      required: true
+
+  - type: textarea
+    id: versions
+    attributes:
+      label: Versions
+      description: |
+        Which version of packages are you using?
+        Please install `session-info2` and run the following command in a notebook:
+        ```python
+        import session_info2
+        session_info2.session_info(
+            "deepscenic", "anndata", "mudata",
+            "torch", "enformer_pytorch",
+            "scanpy", "numpy", "scipy", "pandas",
+        )
+        ```
+      render: python
+      placeholder: |
+        deepscenic    0.1.0
+        anndata       0.11.3
+        mudata        0.3.1
+        torch         2.6.0
+        enformer_pytorch 0.8.12
+        scanpy        1.10.4
+        numpy         2.2.2
+        scipy         1.15.0
+        pandas        2.2.3

deepscenic-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Scverse Community Forum
+    url: https://discourse.scverse.org/
+    about: If you have questions about "How to do X", please ask them here.

deepscenic-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,11 @@
+name: Feature request
+description: Propose a new feature for deepSCENIC
+labels: enhancement
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description of feature
+      description: Please describe your suggestion for a new feature. It might help to describe a problem or use case, plus any alternatives that you have considered.
+    validations:
+      required: true

deepscenic-0.1.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  # Keep the SHA-pinned actions in .github/workflows up to date
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    groups:
+      actions:
+        patterns: ["*"]

deepscenic-0.1.0/.github/workflows/build.yaml

@@ -0,0 +1,38 @@
+name: Check Build
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Cancel superseded PR runs, but let every push to main finish
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    # to fail on error in multiline statements (-e), in pipes (-o pipefail), and on unset variables (-u).
+    shell: bash -euo pipefail {0}
+
+jobs:
+  package:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          cache-dependency-glob: pyproject.toml
+      - name: Build package
+        run: uv build
+      - name: Check package
+        run: uvx twine check --strict dist/*

deepscenic-0.1.0/.github/workflows/release.yaml

@@ -0,0 +1,33 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+# Use "trusted publishing", see https://docs.pypi.org/trusted-publishers/
+permissions: {}
+
+jobs:
+  release:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/deepscenic
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      - name: Build package
+        run: uv build
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2

deepscenic-0.1.0/.github/workflows/ruff.yaml

@@ -0,0 +1,33 @@
+name: Ruff
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Cancel superseded PR runs, but let every push to main finish
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+jobs:
+  ruff:
+    name: Lint and format check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          enable-cache: false
+      # Config (incl. pydocstyle "D" rules, numpy convention) lives in pyproject.toml
+      - name: Ruff lint
+        run: uvx ruff check --output-format=github src tests
+      - name: Ruff format
+        run: uvx ruff format --check src tests

deepscenic-0.1.0/.github/workflows/test.yaml

@@ -0,0 +1,95 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  # Cancel superseded PR runs, but let every push to main finish
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+permissions:
+  contents: read
+
+defaults:
+  run:
+    # to fail on error in multiline statements (-e), in pipes (-o pipefail), and on unset variables (-u).
+    shell: bash -euo pipefail {0}
+
+jobs:
+  get-environments:
+    runs-on: ubuntu-latest
+    outputs:
+      envs: ${{ steps.get-envs.outputs.envs }}
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+      - name: Get test environments
+        id: get-envs
+        run: |
+          ENVS_JSON=$(uvx hatch env show --json | jq -c 'to_entries
+            | map(
+                select(.key | startswith("hatch-test"))
+                | {
+                    name: .key,
+                    label: (if (.key | contains("pre")) then .key + " (PRE-RELEASE DEPENDENCIES)" else .key end),
+                    python: .value.python
+                  }
+              )')
+          echo "envs=${ENVS_JSON}" | tee $GITHUB_OUTPUT
+
+  # Run tests through hatch. Spawns a separate runner for each environment defined in the hatch matrix obtained above.
+  test:
+    needs: get-environments
+
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        env: ${{ fromJSON(needs.get-environments.outputs.envs) }}
+
+    name: ${{ matrix.env.label }}
+    runs-on: ${{ matrix.os }}
+    env:
+      # Runners have no GPU: install CPU-only torch instead of the multi-GB CUDA build
+      UV_TORCH_BACKEND: cpu
+
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+        with:
+          filter: blob:none
+          fetch-depth: 0
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0
+        with:
+          python-version: ${{ matrix.env.python }}
+          cache-dependency-glob: pyproject.toml
+      - name: create hatch environment
+        run: uvx hatch env create ${{ matrix.env.name }}
+      - name: run tests using hatch
+        env:
+          MPLBACKEND: agg
+        run: uvx hatch run ${{ matrix.env.name }}:run -v --color=yes
+
+  # Check that all tests defined above pass. This makes it easy to set a single "required" test in branch
+  # protection instead of having to update it frequently. See https://github.com/re-actors/alls-green#why.
+  check:
+    name: Tests pass in all hatch environments
+    if: always()
+    needs:
+      - get-environments
+      - test
+    runs-on: ubuntu-latest
+    steps:
+        - uses: re-actors/alls-green@b5b5b37504aa4183270bd3d855c52a67f212be35 # v1.3.0
+          with:
+            jobs: ${{ toJSON(needs) }}

deepscenic-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Project-specific
+.claude
+thoughts/
+archived/
+scripts/
+*.slurm
+CLAUDE.md
+pyrightconfig.json
+docs/notebooks/data
+
+# Python
+*__pycache__*
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Jupyter
+*.ipynb_checkpoints*
+
+# Documentation
+docs/_build/
+docs/api/_autosummary/
+
+# Testing
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/
+
+# Environment
+.env
+.venv/
+venv/
+uv.lock

deepscenic-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,10 @@
+# Install once with `pre-commit install`; hooks then run on every commit.
+# Ruff config lives in pyproject.toml. Scope matches the CI ruff workflow (src/ and tests/).
+files: ^(src|tests)/
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.16.10
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format

deepscenic-0.1.0/.readthedocs.yaml

@@ -0,0 +1,16 @@
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+    nodejs: latest
+  jobs:
+    create_environment:
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
+    build:
+      html:
+        - uvx hatch run docs:build
+        - mv docs/_build $READTHEDOCS_OUTPUT

deepscenic-0.1.0/CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use deepSCENIC in your research, please cite the paper below."
+title: "deepSCENIC"
+abstract: "Deep learning for single-cell Gene Regulatory Networks"
+type: software
+authors:
+  - family-names: Partel
+    given-names: Gabriele
+repository-code: "https://github.com/aertslab/deepSCENIC"
+url: "https://deepscenic.readthedocs.io"
+keywords:
+  - single-cell
+  - gene regulatory networks
+  - deep learning
+  - multiomics
+  - scverse
+preferred-citation:
+  type: article
+  title: "DeepSCENIC: transfer learning from sequence-to-function models enables causal gene regulatory network inference"
+  authors:
+    - family-names: Partel
+      given-names: Gabriele
+    - family-names: De Winter
+      given-names: Seppe
+    - family-names: Konstantakos
+      given-names: Vasileios
+    - family-names: Blaauw
+      given-names: Casper H.
+    - family-names: Aerts
+      given-names: Stein
+  journal: "bioRxiv"
+  year: 2026
+  doi: "10.64898/2026.09.18.752607"
+  url: "https://www.biorxiv.org/content/10.64898/2026.09.18.752607v1"

deepscenic-0.1.0/LICENSE

@@ -0,0 +1,60 @@
+
+Academic Non-commercial Software License Agreement
+
+The Licensed Software is developed by and on behalf of the Laboratory of Computational Biology of VIB-KU Leuven and is owned by VIB vzw, located at Rijvisschestraat 120, B-9052 Zwijnaarde, Belgium (hereinafter referred to as "VIB"). By downloading or installing the Licensed Software, the user agrees with the terms and conditions below.
+
+Definitions 
+
+“Licensed Software” shall mean deepSCENIC as available on GitHub.
+
+"Effective Date" shall mean the date on which you download or install deepSCENIC (as available on GitHub) on your system and which provide you access to the deepSCENIC tool.
+
+“Commercial Purposes” shall include (1) the use of Licensed Software to provide a service, information or data that is directly or indirectly conveyed to any third party against compensation, (2) any type of transfer of the Licensed Software for compensation, and (3) any other use of Licensed Software that supports commercial entities. 
+
+License
+
+1.	Licensed Software is the work of the Aerts lab. The copyright in Licensed Software is owned by VIB.
+
+2.	Subject to the terms and conditions of this Agreement, VIB hereby grants and the user accepts a non-exclusive, non-transferable license to use the Licensed Software for strictly internal academic research use only, on your own behalf or on behalf of your institution, and not for Commercial Purposes. 
+
+3.	The user confirms to be an academic user. For academic users, there is no license fee.
+
+4.	The user shall acknowledge VIB as the provider of Licensed Software and shall include the following reference “SCENIC+: single-cell multiomic inference of enhancers and gene regulatory networks Carmen Bravo González-Blas, Seppe De Winter, Gert Hulselmans, Nikolai Hecker, Irina Matetovici, Valerie Christiaens, Suresh Poovathingal, Jasper Wouters, Sara Aibar, Stein Aerts bioRxiv 2022.08.19.504505 (doi: https://doi.org/10.1101/2022.08.19.504505)” in any manuscript describing data obtained using Licensed Software. 
+
+5.	This license does not entitle the user to receive from VIB hard-copy documentation, technical support, telephone assistance, or enhancements or updates to the Licensed Software, and nothing contained herein shall be interpreted as to require VIB, its faculty, employees or students to provide maintenance, installation services, debugging, consultation or end-user support of any kind.
+
+6.	The title and copyright to Licensed Software and any associated programs and documentation shall remain with VIB. The user agrees to preserve the same.
+
+7.	The user agrees not to make any copies of Licensed Software except for use in the user’s laboratory, without VIB’s prior written consent.  The user agrees to place the appropriate copyright notice on any such copies.
+
+8.	The user shall not distribute Licensed Software to other laboratories within user’s institution. The user shall not transfer Licensed Software to another location or person outside of user’s institution without VIB’s prior and written permission.
+
+9.	The user shall not market or otherwise benefit commercially from any product utilizing any portion of Licensed Software, nor any derivative works of Licensed Software, without first entering into a separate commercial license with VIB.
+
+10.	Except as otherwise expressly permitted in this Agreement, the user must not (i) modify or create any derivative works of the Licensed Software or documentation, including customization, translation or localization; (ii) decompile, disassemble, reverse engineer, or otherwise attempt to derive the source code for the Licensed Software; (iii) remove or alter any trademark, logo, copyright or other proprietary notices, legends, symbols or labels in the Licensed Software.
+
+11.	The user acknowledges that the Licensed Software is proprietary to VIB. The software code shall be treated as trade secrets and confidential information of VIB, and the user agrees to use all reasonable efforts to hold the same in confidence. The user’s obligation for confidentiality shall not extend to any information which (i) is or becomes generally available to the public, (ii) is already known to or subsequently disclosed by third parties to the user and at its free disposal, or (iii) is independently developed by the user or its affiliates without the use of the confidential information disclosed by VIB, or (iv) is required by law or legal process to be disclosed.
+
+12.	The user acknowledges that Licensed Software is a research tool and provided free of charge, it is only provided “as is”. VIB makes no representations or warranties of any type whatsoever, express or implied, regarding the Licensed Software. VIB expressly disclaims all representations and warranties regarding the Licensed Software, including but not limited to any representations or warranties of merchantability or fitness for any particular application or that the use of the Licensed Software will not infringe any patents, copyrights or trademarks or other rights of third parties, or any warranty that the rights and licenses granted hereunder comprise all the rights and licenses necessary or desirable to use the Licensed Software for internal non-commercial research purposes as permitted by this Agreement. The entire risk as to the quality and performance of the Licensed Software is borne by the user. 
+
+13.	VIB shall not be responsible for losses of any kind resulting from the use of Licensed Software, and can in no way provide compensation for any losses sustained, including but not limited to, any obligation, liability, right, claim or remedy for tort, or for any actual or alleged infringement of patents, copyrights, trade secrets, or similar rights of third parties, nor any business expense, machine downtime or damages caused by any deficiency, defect or error in Licensed Software or mal-function thereof, nor any incidental or consequential damages, however caused.
+
+14.	The user will indemnify, defend and hold harmless VIB, its directors, officers, employees and agents from and against all liability, losses, damages and expenses (including attorney’s fees and costs) arising out of any claims, demands, actions or other proceedings made or instituted by any third party against any of them and arising out of or relating to any breach of this Agreement by the user, or any use of the Licensed Software by the user, except insofar as such claims or liability result from VIB’s gross negligence or willful misconduct.  
+
+15.	This Agreement and the license rights granted herein shall become effective as of the date the user downloaded the Licensed Software and shall continue in full force until the user deletes the Licensed Software and any and all related files from the user’s computing system, unless terminated in accordance with this Section. Upon one party's breach of any agreement, covenant, or representation made in this Agreement, the agreement will automatically end thirty (30) days after such breach. Either party shall have the right, at any time, to terminate this Agreement without cause by written notice to the other party specifying the date of termination. Upon termination, the user shall destroy all full and partial copies of the Licensed Software. The user shall forward written notice to VIB that all programs containing Licensed Software have been deleted from all computer libraries and storage or memory devices and are no longer stored therein.
+
+16.	This Agreement shall be construed in accordance with the laws of Belgium. The courts of Belgium shall have exclusive jurisdiction. 
+
+17.	The parties agree that this Agreement is the complete and exclusive agreement among the parties and supersedes all proposals and prior agreements whether written or oral, and all other communications among the parties relating to the subject matter of this Agreement. This Agreement cannot be modified except in writing and signed by both parties. Failure by either party at any time to enforce any of the provisions of this Agreement shall not constitute a waiver by such party of such provision nor in any way affect the validity of this Agreement.
+
+18.	The invalidity of singular provisions does not affect the validity of the entire understanding. The parties are obligated, however, to replace the invalid provisions by a regulation, which comes closest to the economic intent of the invalid provision. The same shall apply mutatis mutandis in case of a gap.
+
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+

deepscenic-0.1.0/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.5
+Name: deepscenic
+Version: 0.1.0
+Summary: Deep learning for single-cell Gene Regulatory Networks
+Project-URL: Homepage, https://github.com/aertslab/deepSCENIC
+Project-URL: Documentation, https://deepscenic.readthedocs.io
+Project-URL: Repository, https://github.com/aertslab/deepSCENIC
+Project-URL: Issues, https://github.com/aertslab/deepSCENIC/issues
+Author-email: Gabriele Partel <gabriele.partel@kuleuven.be>
+Maintainer-email: Gabriele Partel <gabriele.partel@kuleuven.be>, Lukas Mahieu <lukas.mahieu@kuleuven.be>
+License-File: LICENSE
+Keywords: GRN,deep-learning,gene-regulation,multiomics,scverse,single-cell
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.12
+Requires-Dist: anndata>=0.12
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: mudata>=0.2.3
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=2.1
+Requires-Dist: pandas<3.0,>=2.0
+Requires-Dist: pooch>=1.6
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pybiomart>=0.2
+Requires-Dist: pyfaidx>=0.9
+Requires-Dist: requests>=2.28
+Requires-Dist: scanpy>=1.11
+Requires-Dist: scikit-learn>=1.2
+Requires-Dist: scipy>=1.14
+Requires-Dist: seaborn>=0.12
+Requires-Dist: torch-geometric>=2.7
+Requires-Dist: torch>=2.6
+Requires-Dist: tqdm>=4.65
+Provides-Extra: dev
+Requires-Dist: pre-commit>=3.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: twine>=4.0; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: docutils!=0.18.*,!=0.19.*,>=0.8; extra == 'doc'
+Requires-Dist: enformer-pytorch>=0.8.12; extra == 'doc'
+Requires-Dist: ipykernel; extra == 'doc'
+Requires-Dist: ipython; extra == 'doc'
+Requires-Dist: ipywidgets; extra == 'doc'
+Requires-Dist: myst-nb>=1.1; extra == 'doc'
+Requires-Dist: pandas; extra == 'doc'
+Requires-Dist: setuptools; extra == 'doc'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'doc'
+Requires-Dist: sphinx-book-theme>=1; extra == 'doc'
+Requires-Dist: sphinx-copybutton; extra == 'doc'
+Requires-Dist: sphinx-tabs; extra == 'doc'
+Requires-Dist: sphinx>=8.1; extra == 'doc'
+Requires-Dist: sphinxcontrib-bibtex>=1; extra == 'doc'
+Requires-Dist: sphinxext-opengraph; extra == 'doc'
+Provides-Extra: enformer
+Requires-Dist: enformer-pytorch>=0.8.12; extra == 'enformer'
+Provides-Extra: test
+Requires-Dist: debugpy; extra == 'test'
+Requires-Dist: enformer-pytorch>=0.8.12; extra == 'test'
+Requires-Dist: pytest>=7.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# deepSCENIC
+
+**Deep learning for single-cell Gene Regulatory Networks**
+
+[![Documentation](https://readthedocs.org/projects/deepscenic/badge/?version=latest)](https://deepscenic.readthedocs.io)
+[![PyPI](https://img.shields.io/pypi/v/deepscenic.svg)](https://pypi.org/project/deepscenic)
+[![Python](https://img.shields.io/pypi/pyversions/deepscenic.svg)](https://pypi.org/project/deepscenic)
+
+<img src="https://raw.githubusercontent.com/aertslab/deepSCENIC/main/docs/deepSCENIC.png" width=100%>
+
+deepSCENIC learns hierarchical TF→region→gene regulatory cascades by integrating scRNA-seq, scATAC-seq, and DNA sequence data. It combines a VAE-based multimodal framework with Enformer-derived sequence embeddings to infer cell-type-specific gene regulatory networks.
+
+## Key Features
+
+- **Multimodal integration**: Jointly models RNA expression and chromatin accessibility
+- **Sequence-informed**: Uses Enformer to learn TF binding patterns from DNA sequence
+- **Perturbation prediction**: Simulates TF knockdown/overexpression effects
+- **scverse compatible**: Works with AnnData, MuData, and scanpy workflows
+
+## Installation
+
+```bash
+pip install deepscenic
+```
+If you want to use the [enformer](https://github.com/lucidrains/enformer-pytorch) model as the sequence model (this is the default):
+
+```bash
+pip install deepscenic[enformer]
+```
+
+**Requirements**: Python ≥3.12, PyTorch ≥2.6
+
+## Documentation
+
+Full documentation including tutorials and API reference: [deepscenic.readthedocs.io](https://deepscenic.readthedocs.io)
+
+## Quick Start
+
+deepSCENIC follows the scanpy-style API with modules for preprocessing (`ds.pp`), tools (`ds.tl`), and plotting (`ds.pl`).
+
+### Data Preparation
+
+```python
+import deepscenic as ds
+
+# Annotate transcription factors on the RNA data
+tfs = ds.fetch_tf_collection(species="human")
+ds.pp.mark_tfs(adata_rna, tf_list=tfs)
+
+# Add gene annotations (for chromosome-based splitting)
+annot, chromsizes = ds.fetch_gene_annotation(species="hsapiens")
+ds.pp.add_gene_annotation(adata_rna, gene_annotation=annot)
+
+mdata = ds.pp.create_mudata(rna=adata_rna, atac=adata_atac)
+
+# Compute region-to-gene search space (regions within 1Mb of gene TSS)
+ds.pp.compute_r2g_penalty(mdata)
+
+# Split cells and features for training/evaluation
+ds.pp.split_cells(mdata, test_fraction=0.2, stratify_key="cell_type")
+ds.pp.split_features_by_chromosome(mdata, test_chromosomes=["chr7", "chr11"])
+```
+
+### Model Training
+
+```python
+# Register genome for sequence extraction
+ds.register_genome("/path/to/hg38.fa")
+
+# Phase 1: Train full model (VAE + MotifNet + Enformer)
+model = ds.tl.train(mdata, epochs=100, device="cuda")
+
+# Phase 2: Recompute tf2r and finetune all r2g links
+model = ds.tl.finetune_r2g(
+    model,
+    mdata,
+    epochs=500,
+)
+
+# Save trained model
+model.save("my_model.pt")
+```
+
+### GRN Extraction & Analysis
+
+```python
+# Extract gene regulatory network
+grn = ds.tl.extract_grn(model)
+
+# Get targets of a specific TF
+targets = ds.tl.get_tf_targets(model, tf_name="SOX10", top_k=100)
+
+# Visualize GRN heatmap
+ds.pl.heatmap_grn(model, tfs=["SOX10", "MITF", "PAX3"])
+```
+
+### Perturbation Simulation
+
+```python
+# Simulate TF knockdown (level=0) or overexpression (level=2)
+perturbed, logFC = ds.tl.simulate_perturbation(
+    model,
+    mdata,
+    tf_name="SOX10",
+    level=0,  # knockdown
+)
+
+# Summarize and visualize perturbation effects
+results = ds.tl.process_perturbation_results(logFC, mdata, tf_name="SOX10")
+ds.pl.waterfall_perturbation(results)
+```
+
+For complete workflows, see the [tutorials](https://deepscenic.readthedocs.io/en/latest/tutorials.html).
+
+## Citation
+
+If you use deepSCENIC in your research, please cite:
+
+> Partel G, et al. DeepSCENIC: transfer learning from sequence-to-function models enables causal gene regulatory network inference. *bioRxiv* (2026). [doi:10.64898/2026.09.18.752607](https://doi.org/10.64898/2026.09.18.752607)
+
+```bibtex
+@article{partel2026deepscenic,
+  title={DeepSCENIC: transfer learning from sequence-to-function models enables causal gene regulatory network inference},
+  author={Partel, Gabriele and De Winter, Seppe and Konstantakos, Vasileios and Blaauw, Casper H. and Aerts, Stein},
+  journal={bioRxiv},
+  year={2026},
+  doi={10.64898/2026.09.18.752607}
+}
+```
+
+## Links
+
+- [Documentation](https://deepscenic.readthedocs.io)
+- [GitHub Repository](https://github.com/aertslab/deepSCENIC)
+- [Issue Tracker](https://github.com/aertslab/deepSCENIC/issues)
+- [Enformer PyTorch](https://github.com/lucidrains/enformer-pytorch) - Sequence model implementation