# harvardnlp/regulatory-prediction architecture

> Architecture diagram of the GitHub repository harvardnlp/regulatory-prediction, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/harvardnlp/regulatory-prediction
- Repository: https://github.com/harvardnlp/regulatory-prediction

## Overview

1. **Project shape**
   - This is a single-purpose research training repo for genomic regulatory prediction.
   - The whole system is centered around one executable entrypoint, `train.py`, with supporting model, utility, and TensorFlow helper modules.

2. **Primary runtime**
   - The code is a Python 2.7 / TensorFlow 1.0-era project.
   - NumPy and SciPy are used as supporting numerical libraries.
   - There is no indication of a web service, database, or distributed system; the architecture is a local training pipeline.

3. **Top-level flow**
   - `train.py` is the orchestration layer.
   - It likely loads data, builds the model, runs optimization, and evaluates results.
   - Any experiment configuration is probably embedded in the training script or passed via command-line flags.

4. **Model subsystem**
   - `models.py` is the main model-definition boundary.
   - Based on the paper title, it likely contains the neural network architectures for modeling long-range genomic dependencies, probably including dilated convolution variants and task-specific heads.
   - This is where the core predictive logic lives.

5. **TensorFlow integration**
   - `tf_utils.py` appears to hold reusable TensorFlow 1.x helpers: session setup, variable initialization, loss/metric helpers, checkpointing, or graph utilities.
   - This layer separates training/model code from low-level TensorFlow boilerplate.

6. **Custom operators / low-level kernels**
   - `custom_ops.py` suggests there are project-specific TensorFlow ops or wrappers around nonstandard operations.
   - Architecturally, this is the “performance/primitive” layer beneath the model definitions, likely used when TensorFlow’s built-ins are insufficient or too slow.

7. **General utilities**
   - `util.py` is the shared support layer for non-model logic.
   - In a repo like this, that usually includes file handling, logging, metrics, sequence preprocessing, batching, and miscellaneous helpers used by `train.py` and `models.py`.

8. **Data flow**
   - Input data is not included in the repo; the README says data is “forthcoming.”
   - So the practical runtime flow is: external genomic dataset -> preprocessing/utilities -> TensorFlow input pipeline or in-memory batches -> model graph -> training/evaluation.
   - Any data schema or dataset-specific parsing is likely implemented in the utility layer rather than as a standalone subsystem.

9. **Training as the main control boundary**
   - There is no separate inference service or deployment layer visible.
   - The repo is organized around offline experimentation: build a graph, train it, and report metrics from the same process.

10. **Research-specific emphasis**
   - The architecture reflects a paper implementation rather than a product system.
   - The important boundary is between “experiment driver” code and “model/ops” code, not between frontend/backend components.

11. **Likely dependency boundaries**
   - Custom ops and model code depend on TensorFlow primitives.
   - Training code depends on both model construction and utility functions.
   - Utilities may also depend on NumPy/SciPy for numeric preprocessing and evaluation.

12. **What to draw in an architecture diagram**
   - A good diagram would show:
     - External genomic data feeding into `train.py`
     - `train.py` calling into `util.py`, `tf_utils.py`, and `models.py`
     - `models.py` optionally calling `custom_ops.py`
     - TensorFlow as the execution/runtime layer underneath all of them
   - The diagram should emphasize a single training pipeline with supporting libraries, not multiple services.

Main entry points: [`train.py`](https://github.com/harvardnlp/regulatory-prediction/blob/master/train.py) (train.py), [`models.py`](https://github.com/harvardnlp/regulatory-prediction/blob/master/models.py) (models.py), [`tf_utils.py`](https://github.com/harvardnlp/regulatory-prediction/blob/master/tf_utils.py) (tf_utils.py), [`custom_ops.py`](https://github.com/harvardnlp/regulatory-prediction/blob/master/custom_ops.py) (custom_ops.py)

## Diagram (Mermaid)

```mermaid
flowchart TD

node_external_data[("Genomic data<br/>external dataset")]
node_train_py["train.py<br/>experiment driver<br/>[train.py]"]
node_models_py["models.py<br/>model definitions<br/>[models.py]"]
node_tf_utils_py["tf_utils.py<br/>tf helpers<br/>[tf_utils.py]"]
node_custom_ops_py["custom_ops.py<br/>custom ops<br/>[custom_ops.py]"]
node_util_py["util.py<br/>shared utilities<br/>[util.py]"]
node_tensorflow(("TensorFlow<br/>runtime"))
node_numeric_libs(("NumPy/SciPy<br/>numeric libs"))

node_external_data -->|"inputs"| node_train_py
node_train_py -->|"uses"| node_util_py
node_train_py -->|"uses"| node_tf_utils_py
node_train_py -->|"builds"| node_models_py
node_models_py -->|"depends on"| node_custom_ops_py
node_models_py -->|"runs on"| node_tensorflow
node_tf_utils_py -->|"wraps"| node_tensorflow
node_custom_ops_py -->|"extends"| node_tensorflow
node_util_py -->|"uses"| node_numeric_libs
node_train_py -->|"orchestrates"| node_tensorflow
node_train_py -->|"uses"| node_numeric_libs

click node_train_py "https://github.com/harvardnlp/regulatory-prediction/blob/master/train.py"
click node_models_py "https://github.com/harvardnlp/regulatory-prediction/blob/master/models.py"
click node_tf_utils_py "https://github.com/harvardnlp/regulatory-prediction/blob/master/tf_utils.py"
click node_custom_ops_py "https://github.com/harvardnlp/regulatory-prediction/blob/master/custom_ops.py"
click node_util_py "https://github.com/harvardnlp/regulatory-prediction/blob/master/util.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_external_data,node_train_py,node_models_py,node_tf_utils_py,node_custom_ops_py,node_util_py,node_tensorflow,node_numeric_libs toneNeutral
```

## Components

### Other components

- **Genomic data**: external dataset · Training and evaluation inputs come from outside the repository.
- [train.py](https://github.com/harvardnlp/regulatory-prediction/blob/master/train.py): experiment driver · Main orchestration entrypoint for loading data, building the model, training, and evaluation. · `train.py`
- [models.py](https://github.com/harvardnlp/regulatory-prediction/blob/master/models.py): model definitions · Core neural architectures and task-specific prediction heads. · `models.py`
- [tf_utils.py](https://github.com/harvardnlp/regulatory-prediction/blob/master/tf_utils.py): tf helpers · TensorFlow 1.x utilities for graph setup, training support, and reusable boilerplate. · `tf_utils.py`
- [custom_ops.py](https://github.com/harvardnlp/regulatory-prediction/blob/master/custom_ops.py): custom ops · Project-specific low-level operations or wrappers used by the model code. · `custom_ops.py`
- [util.py](https://github.com/harvardnlp/regulatory-prediction/blob/master/util.py): shared utilities · General support code for preprocessing, batching, logging, and other shared helpers. · `util.py`
- **TensorFlow**: runtime · Execution framework underlying the model, training, and custom operation layers.
- **NumPy/SciPy**: numeric libs · Supporting numerical libraries used by utilities and training-time computations.

## Connections

- Genomic data → train.py: inputs · External genomic datasets flow into the training process.
- train.py → util.py: uses · Training relies on shared utilities for data handling and support logic.
- train.py → tf_utils.py: uses · Training uses TensorFlow helper routines and boilerplate support.
- train.py → models.py: builds · The driver constructs and runs the predictive model graph.
- models.py → custom_ops.py: depends on · Model definitions may call into project-specific low-level operations.
- models.py → TensorFlow: runs on · Model layers are implemented on top of TensorFlow primitives.
- tf_utils.py → TensorFlow: wraps · TensorFlow helper code manages graph/session-level behavior.
- custom_ops.py → TensorFlow: extends · Custom operations extend the TensorFlow execution layer.
- util.py → NumPy/SciPy: uses · Utility code may rely on NumPy and SciPy for preprocessing and metrics.
- train.py → TensorFlow: orchestrates · The training entrypoint coordinates execution within TensorFlow.
- train.py → NumPy/SciPy: uses · Training may use numerical libraries for data preparation and evaluation.
