# perslev/u-time architecture

> Architecture diagram of the GitHub repository perslev/u-time, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/perslev/u-time
- Repository: https://github.com/perslev/u-time

## Overview

U-Time is a command-line toolkit for training and evaluating U-Time and U-Sleep models for sleep staging and time-series segmentation. The documented workflow initializes a project, fetches PSG datasets, prepares data splits, trains a model, and predicts or evaluates results. Internally, dataset sequences form batches and apply augmentation; model-building and training utilities support optimization, while evaluation and prediction provide separate result paths. The README describes additional CLI capabilities, but several command implementations are unsampled, so only documented links are shown for them.

Main entry points: [`utime/bin/ut.py`](https://github.com/perslev/u-time/blob/main/utime/bin/ut.py) (U-Time CLI), [`utime/models/utime.py`](https://github.com/perslev/u-time/blob/main/utime/models/utime.py) (U-Time network), [`utime/utils/scriptutils/train.py`](https://github.com/perslev/u-time/blob/main/utime/utils/scriptutils/train.py) (Training workflow), [`utime/sequences/batch_sequence.py`](https://github.com/perslev/u-time/blob/main/utime/sequences/batch_sequence.py) (BatchSequence)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Project workflow"]
  node_cli["U-Time CLI<br/>[ut.py]"]
  node_project_init["Project initialization<br/>[init.py]"]
  node_data_fetch["Dataset fetching<br/>[fetch.py]"]
  node_hparams["Hyperparameters<br/>[__init__.py]"]
end

subgraph group_data["Data and batching"]
  node_data_prep["Data preparation<br/>[preprocess.py]"]
  node_data_splits["Dataset splits<br/>[cv_split.py]"]
  node_sequences["Batch sequences<br/>[base_sequence.py]"]
  node_batch_sequence["BatchSequence<br/>[batch_sequence.py]"]
  node_multi_sequence["Multi-dataset sequence<br/>[multi_sequence.py]"]
  node_random_sequence["Random sampling"]
  node_balanced_sequence["Balanced sampling"]
  node_augmenters["Signal augmentation<br/>[augmenters.py]"]
end

subgraph group_models["Models and training"]
  node_model_init["Model initialization<br/>[model_init.py]"]
  node_usleep["U-Sleep network<br/>[usleep.py]"]
  node_utime_model["U-Time network<br/>[utime.py]"]
  node_conv_utils["Convolution utilities"]
  node_trainer["Training engine<br/>[trainer.py]"]
  node_train_utils["Training utilities<br/>[utils.py]"]
  node_callbacks["Training callbacks<br/>[callbacks.py]"]
  node_train_scripts["Training workflow<br/>[train.py]"]
  node_gpu["GPU selection<br/>[system.py]"]
end

subgraph group_results["Prediction and evaluation"]
  node_predict["Prediction workflow<br/>[predict.py]"]
  node_predict_one["Single-study prediction<br/>[predict_one.py]"]
  node_evaluation["Evaluation workflow<br/>[evaluate.py]"]
  node_metrics["Evaluation metrics<br/>[metrics.py]"]
  node_confusion["Confusion analysis<br/>[cm.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"runs commands"| node_cli
node_cli -->|"initializes project"| node_project_init
node_cli -->|"fetches PSG"| node_data_fetch
node_cli -->|"splits datasets"| node_data_splits
node_cli -->|"trains models"| node_train_scripts
node_cli -->|"evaluates models"| node_evaluation
node_cli -.->|"predicts studies"| node_predict_one
node_train_scripts -->|"builds sequences"| node_sequences
node_batch_sequence -->|"inherits from"| node_sequences
node_sequences -->|"applies augmentation"| node_augmenters
node_multi_sequence -.->|"uses batches"| node_batch_sequence
node_random_sequence -.->|"specializes batching"| node_batch_sequence
node_balanced_sequence -.->|"specializes batching"| node_batch_sequence
node_train_scripts -->|"initializes model"| node_model_init
node_model_init -.->|"selects model"| node_utime_model
node_model_init -.->|"selects model"| node_usleep
node_utime_model -->|"uses arithmetic"| node_conv_utils
node_usleep -->|"uses arithmetic"| node_conv_utils
node_utime_model -->|"uses training utilities"| node_train_utils
node_usleep -->|"uses training utilities"| node_train_utils
node_trainer -->|"configures callbacks"| node_callbacks
node_trainer -->|"uses training utilities"| node_train_utils
node_train_scripts -.->|"selects GPUs"| node_gpu
node_evaluation -->|"predicts sequences"| node_predict
node_evaluation -->|"computes metrics"| node_metrics
node_predict_one -->|"loads model"| node_utime_model
node_confusion -->|"uses model"| node_utime_model

click node_cli "https://github.com/perslev/u-time/blob/main/utime/bin/ut.py"
click node_project_init "https://github.com/perslev/u-time/blob/main/utime/bin/init.py"
click node_data_fetch "https://github.com/perslev/u-time/blob/main/utime/bin/fetch.py"
click node_data_prep "https://github.com/perslev/u-time/blob/main/utime/bin/preprocess.py"
click node_data_splits "https://github.com/perslev/u-time/blob/main/utime/bin/cv_split.py"
click node_hparams "https://github.com/perslev/u-time/blob/main/utime/hyperparameters/__init__.py"
click node_sequences "https://github.com/perslev/u-time/blob/main/utime/sequences/base_sequence.py"
click node_batch_sequence "https://github.com/perslev/u-time/blob/main/utime/sequences/batch_sequence.py"
click node_multi_sequence "https://github.com/perslev/u-time/blob/main/utime/sequences/multi_sequence.py"
click node_random_sequence "https://github.com/perslev/u-time/blob/main/utime/sequences/random_batch_sequence.py"
click node_balanced_sequence "https://github.com/perslev/u-time/blob/main/utime/sequences/balanced_random_batch_sequence.py"
click node_augmenters "https://github.com/perslev/u-time/blob/main/utime/augmentation/augmenters.py"
click node_model_init "https://github.com/perslev/u-time/blob/main/utime/models/model_init.py"
click node_usleep "https://github.com/perslev/u-time/blob/main/utime/models/usleep.py"
click node_utime_model "https://github.com/perslev/u-time/blob/main/utime/models/utime.py"
click node_conv_utils "https://github.com/perslev/u-time/blob/main/utime/utils/conv_arithmetics.py"
click node_trainer "https://github.com/perslev/u-time/blob/main/utime/train/trainer.py"
click node_train_utils "https://github.com/perslev/u-time/blob/main/utime/train/utils.py"
click node_callbacks "https://github.com/perslev/u-time/blob/main/utime/callbacks/callbacks.py"
click node_train_scripts "https://github.com/perslev/u-time/blob/main/utime/utils/scriptutils/train.py"
click node_predict "https://github.com/perslev/u-time/blob/main/utime/utils/scriptutils/predict.py"
click node_predict_one "https://github.com/perslev/u-time/blob/main/utime/bin/predict_one.py"
click node_evaluation "https://github.com/perslev/u-time/blob/main/utime/bin/evaluate.py"
click node_metrics "https://github.com/perslev/u-time/blob/main/utime/evaluation/metrics.py"
click node_confusion "https://github.com/perslev/u-time/blob/main/utime/bin/cm.py"
click node_gpu "https://github.com/perslev/u-time/blob/main/utime/utils/system.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_cli,node_project_init,node_data_fetch,node_hparams toneBlue
class node_data_prep,node_data_splits,node_sequences,node_batch_sequence,node_multi_sequence,node_random_sequence,node_balanced_sequence,node_augmenters toneAmber
class node_model_init,node_usleep,node_utime_model,node_conv_utils,node_trainer,node_train_utils,node_callbacks,node_train_scripts,node_gpu toneMint
class node_predict,node_predict_one,node_evaluation,node_metrics,node_confusion toneRose
class node_researcher toneIndigo
```

## Components

### Project workflow

- [U-Time CLI](https://github.com/perslev/u-time/blob/main/utime/bin/ut.py): `utime/bin/ut.py`
- [Project initialization](https://github.com/perslev/u-time/blob/main/utime/bin/init.py): `utime/bin/init.py`
- [Dataset fetching](https://github.com/perslev/u-time/blob/main/utime/bin/fetch.py): `utime/bin/fetch.py`
- [Hyperparameters](https://github.com/perslev/u-time/blob/main/utime/hyperparameters/__init__.py): `utime/hyperparameters/__init__.py`

### Data and batching

- [Data preparation](https://github.com/perslev/u-time/blob/main/utime/bin/preprocess.py): `utime/bin/preprocess.py`
- [Dataset splits](https://github.com/perslev/u-time/blob/main/utime/bin/cv_split.py): `utime/bin/cv_split.py`
- [Batch sequences](https://github.com/perslev/u-time/blob/main/utime/sequences/base_sequence.py): `utime/sequences/base_sequence.py`
- [BatchSequence](https://github.com/perslev/u-time/blob/main/utime/sequences/batch_sequence.py): `utime/sequences/batch_sequence.py`
- [Multi-dataset sequence](https://github.com/perslev/u-time/blob/main/utime/sequences/multi_sequence.py): `utime/sequences/multi_sequence.py`
- [Random sampling](https://github.com/perslev/u-time/blob/main/utime/sequences/random_batch_sequence.py): `utime/sequences/random_batch_sequence.py`
- [Balanced sampling](https://github.com/perslev/u-time/blob/main/utime/sequences/balanced_random_batch_sequence.py): `utime/sequences/balanced_random_batch_sequence.py`
- [Signal augmentation](https://github.com/perslev/u-time/blob/main/utime/augmentation/augmenters.py): `utime/augmentation/augmenters.py`

### Models and training

- [Model initialization](https://github.com/perslev/u-time/blob/main/utime/models/model_init.py): `utime/models/model_init.py`
- [U-Sleep network](https://github.com/perslev/u-time/blob/main/utime/models/usleep.py): `utime/models/usleep.py`
- [U-Time network](https://github.com/perslev/u-time/blob/main/utime/models/utime.py): `utime/models/utime.py`
- [Convolution utilities](https://github.com/perslev/u-time/blob/main/utime/utils/conv_arithmetics.py): `utime/utils/conv_arithmetics.py`
- [Training engine](https://github.com/perslev/u-time/blob/main/utime/train/trainer.py): `utime/train/trainer.py`
- [Training utilities](https://github.com/perslev/u-time/blob/main/utime/train/utils.py): `utime/train/utils.py`
- [Training callbacks](https://github.com/perslev/u-time/blob/main/utime/callbacks/callbacks.py): `utime/callbacks/callbacks.py`
- [Training workflow](https://github.com/perslev/u-time/blob/main/utime/utils/scriptutils/train.py): `utime/utils/scriptutils/train.py`
- [GPU selection](https://github.com/perslev/u-time/blob/main/utime/utils/system.py): `utime/utils/system.py`

### Prediction and evaluation

- [Prediction workflow](https://github.com/perslev/u-time/blob/main/utime/utils/scriptutils/predict.py): `utime/utils/scriptutils/predict.py`
- [Single-study prediction](https://github.com/perslev/u-time/blob/main/utime/bin/predict_one.py): `utime/bin/predict_one.py`
- [Evaluation workflow](https://github.com/perslev/u-time/blob/main/utime/bin/evaluate.py): `utime/bin/evaluate.py`
- [Evaluation metrics](https://github.com/perslev/u-time/blob/main/utime/evaluation/metrics.py): `utime/evaluation/metrics.py`
- [Confusion analysis](https://github.com/perslev/u-time/blob/main/utime/bin/cm.py): `utime/bin/cm.py`

### Other components

- **Researcher**

## Connections

- Researcher → U-Time CLI: runs commands
- U-Time CLI → Project initialization: initializes project
- U-Time CLI → Dataset fetching: fetches PSG
- U-Time CLI → Dataset splits: splits datasets
- U-Time CLI → Training workflow: trains models
- U-Time CLI → Evaluation workflow: evaluates models
- U-Time CLI → Single-study prediction: predicts studies
- Training workflow → Batch sequences: builds sequences (evidence: `utime/utils/scriptutils/train.py`)
- BatchSequence → Batch sequences: inherits from (evidence: `utime/sequences/batch_sequence.py`)
- Batch sequences → Signal augmentation: applies augmentation (evidence: `utime/sequences/base_sequence.py`)
- Multi-dataset sequence → BatchSequence: uses batches
- Random sampling → BatchSequence: specializes batching
- Balanced sampling → BatchSequence: specializes batching
- Training workflow → Model initialization: initializes model (evidence: `utime/models/model_init.py`)
- Model initialization → U-Time network: selects model
- Model initialization → U-Sleep network: selects model
- U-Time network → Convolution utilities: uses arithmetic (evidence: `utime/models/utime.py`)
- U-Sleep network → Convolution utilities: uses arithmetic (evidence: `utime/models/usleep.py`)
- U-Time network → Training utilities: uses training utilities (evidence: `utime/models/utime.py`)
- U-Sleep network → Training utilities: uses training utilities (evidence: `utime/models/usleep.py`)
- Training engine → Training callbacks: configures callbacks (evidence: `utime/train/trainer.py`)
- Training engine → Training utilities: uses training utilities (evidence: `utime/train/trainer.py`)
- Training workflow → GPU selection: selects GPUs
- Evaluation workflow → Prediction workflow: predicts sequences (evidence: `utime/bin/evaluate.py`)
- Evaluation workflow → Evaluation metrics: computes metrics (evidence: `utime/bin/evaluate.py`)
- Single-study prediction → U-Time network: loads model (evidence: `utime/bin/predict_one.py`)
- Confusion analysis → U-Time network: uses model (evidence: `utime/bin/cm.py`)
