# stefanowoerner/medimeta-pytorch architecture

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

- Interactive diagram: https://gitdiagram.com/stefanowoerner/medimeta-pytorch
- Repository: https://github.com/stefanowoerner/medimeta-pytorch

## Overview

1. **Repository purpose**
   - This is a small PyTorch library, not a model repository.
   - Its main job is to expose the external **MedIMeta** medical imaging dataset through a unified Python API and make it usable for single-task, multi-task, few-shot, and cross-domain experiments.

2. **Core boundary: code vs. data**
   - The repository contains the **access layer** only.
   - The actual dataset lives outside the repo and is downloaded separately from **Zenodo**.
   - The library expects a local dataset root path and reads standardized task data from disk.

3. **Primary runtime dependency**
   - The package is built around **PyTorch** and specifically follows the `torch.utils.data.Dataset` pattern.
   - This means the central abstraction is a dataset object that returns `(image, label)` samples in a form directly consumable by PyTorch training loops.

4. **Main entry point**
   - `medimeta/medimeta.py` is the key module.
   - It likely defines the `MedIMeta` dataset class described in the README, which provides a unified interface for selecting:
     - a dataset/domain,
     - a task within that dataset,
     - and the corresponding labeled samples.

5. **Task and metadata layer**
   - `medimeta/tasks.py` appears to encode the task catalog and task-specific metadata.
   - This is where the repository likely standardizes the many underlying medical datasets into a common task format, including dataset names, task names, and class/label structure.

6. **Batching and sampling utilities**
   - `medimeta/batches.py` and `medimeta/task_presampling.py` support multi-task and few-shot workflows.
   - These modules are the bridge from “one dataset object” to “task-aware training episodes or batches,” which is important for cross-domain learning and meta-learning setups.

7. **Logging/support code**
   - `medimeta/logger.py` is a small supporting subsystem for runtime messages or experiment feedback.
   - It is auxiliary rather than architectural, but it likely helps surface dataset loading or sampling behavior during experiments.

8. **Package surface**
   - `medimeta/__init__.py` is the public API boundary.
   - It likely re-exports the main classes and helpers so users can import from `medimeta` directly instead of touching internal modules.

9. **Example-driven usage model**
   - The `examples/` directory shows the intended integration patterns:
     - plain supervised learning,
     - ImageNet-pretrained evaluation on few-shot tasks,
     - cross-domain pretraining,
     - cross-domain MAML.
   - These examples demonstrate that MedIMeta is designed to plug into broader ML pipelines rather than provide a full training framework itself.

10. **External integration point: TorchCross**
   - The README explicitly says MedIMeta integrates with **TorchCross**.
   - Architecturally, MedIMeta provides the dataset/task abstractions, while TorchCross provides the learning algorithms and experiment scaffolding for cross-domain and meta-learning.

11. **Standardization assumptions**
   - The dataset is already standardized to **224×224** images and comes with predefined splits.
   - This reduces preprocessing complexity inside the library; the architecture assumes consistent task formatting rather than performing heavy on-the-fly data harmonization.

12. **Overall data flow**
   - External dataset files on disk → `MedIMeta` dataset object → task-specific sample retrieval → optional task sampling/batching helpers → PyTorch/TorchCross training or evaluation code.
   - The repository’s main architectural role is to normalize many medical image tasks into one consistent access pattern.

13. **Suggested diagram focus**
   - Draw three main layers:
     - **Dataset storage**: local MedIMeta files from Zenodo,
     - **MedIMeta package**: dataset/task/sampling utilities,
     - **Experiment layer**: PyTorch and TorchCross consumers in the example scripts.
   - The most important boundaries are between stored data, standardized task metadata, and downstream learning workflows.

Main entry points: [`medimeta/__init__.py`](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/__init__.py) (API surface), [`medimeta/medimeta.py`](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/medimeta.py) (MedIMeta), [`medimeta/tasks.py`](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/tasks.py) (Task catalog), [`medimeta/batches.py`](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/batches.py) (Batches)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_dataset_storage["Dataset storage"]
  node_external_zenodo[("Zenodo data<br/>external dataset")]
end

subgraph group_medimeta_package["MedIMeta package"]
  node_medimeta_dataset["MedIMeta<br/>Dataset<br/>[medimeta.py]"]
  node_task_catalog["Task catalog<br/>metadata<br/>[tasks.py]"]
  node_batching["Batches<br/>sampling utils<br/>[batches.py]"]
  node_presampling["Presampling<br/>sampling utils"]
  node_logger["Logger<br/>support<br/>[logger.py]"]
  node_public_api["API surface<br/>package init<br/>[__init__.py]"]
end

subgraph group_experiments["Experiments"]
  node_supervised_example["Supervised<br/>example script"]
  node_imagenet_example["ImageNet eval<br/>example script"]
  node_pretrain_example["Pretraining<br/>example script"]
  node_maml_example["MAML<br/>example script"]
  node_torch_training(("PyTorch<br/>runtime"))
  node_torchcross(("TorchCross<br/>external framework"))
end

node_external_zenodo -->|"loaded by"| node_medimeta_dataset
node_task_catalog -->|"drives"| node_medimeta_dataset
node_medimeta_dataset -->|"feeds"| node_batching
node_medimeta_dataset -->|"feeds"| node_presampling
node_task_catalog -->|"configures"| node_batching
node_task_catalog -->|"configures"| node_presampling
node_medimeta_dataset -->|"reports"| node_logger
node_public_api -->|"exports"| node_medimeta_dataset
node_public_api -->|"exports"| node_task_catalog
node_public_api -->|"exports"| node_batching
node_public_api -->|"exports"| node_presampling
node_supervised_example -->|"uses"| node_torch_training
node_imagenet_example -->|"uses"| node_torch_training
node_pretrain_example -->|"uses"| node_torchcross
node_maml_example -->|"uses"| node_torchcross
node_supervised_example -->|"imports"| node_public_api
node_imagenet_example -->|"imports"| node_public_api
node_pretrain_example -->|"imports"| node_public_api
node_maml_example -->|"imports"| node_public_api

click node_medimeta_dataset "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/medimeta.py"
click node_task_catalog "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/tasks.py"
click node_batching "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/batches.py"
click node_presampling "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/task_presampling.py"
click node_logger "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/logger.py"
click node_public_api "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/__init__.py"
click node_supervised_example "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/fully_supervised.py"
click node_imagenet_example "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/imagenet_pretrained.py"
click node_pretrain_example "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/cross_domain_pretraining.py"
click node_maml_example "https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/cross_domain_maml.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_zenodo toneBlue
class node_medimeta_dataset,node_task_catalog,node_batching,node_presampling,node_logger,node_public_api toneAmber
class node_supervised_example,node_imagenet_example,node_pretrain_example,node_maml_example,node_torch_training,node_torchcross toneMint
```

## Components

### Dataset storage

External MedIMeta files downloaded from Zenodo and stored locally.

- **Zenodo data**: external dataset · Local MedIMeta dataset root populated from Zenodo downloads.

### MedIMeta package

Core dataset access, task metadata, batching, and support code.

- [MedIMeta](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/medimeta.py): Dataset · Main torch.utils.data.Dataset interface for selecting datasets, tasks, and samples. · `medimeta/medimeta.py`
- [Task catalog](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/tasks.py): metadata · Standardized mapping of dataset names, tasks, and label structure. · `medimeta/tasks.py`
- [Batches](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/batches.py): sampling utils · Helpers for task-aware batching and multi-task episode construction. · `medimeta/batches.py`
- [Presampling](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/task_presampling.py): sampling utils · Utilities for few-shot and task-presampled data access. · `medimeta/task_presampling.py`
- [Logger](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/logger.py): support · Lightweight runtime messaging and loading feedback. · `medimeta/logger.py`
- [API surface](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/medimeta/__init__.py): package init · Public import boundary that re-exports the main package objects. · `medimeta/__init__.py`

### Experiments

Example entry points showing how the library plugs into training and evaluation workflows.

- [Supervised](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/fully_supervised.py): example script · Plain supervised learning usage pattern. · `examples/fully_supervised.py`
- [ImageNet eval](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/imagenet_pretrained.py): example script · Few-shot evaluation with ImageNet-pretrained features. · `examples/imagenet_pretrained.py`
- [Pretraining](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/cross_domain_pretraining.py): example script · Cross-domain pretraining workflow. · `examples/cross_domain_pretraining.py`
- [MAML](https://github.com/stefanowoerner/medimeta-pytorch/blob/master/examples/cross_domain_maml.py): example script · Cross-domain MAML workflow. · `examples/cross_domain_maml.py`
- **PyTorch**: runtime · Downstream torch training loops consuming dataset samples.
- **TorchCross**: external framework · External framework for cross-domain and meta-learning experiments.

## Connections

- Zenodo data → MedIMeta: loaded by · The dataset object reads standardized samples from the local dataset root.
- Task catalog → MedIMeta: drives · Task metadata defines which dataset/task/labels the dataset object serves.
- MedIMeta → Batches: feeds · The base dataset is wrapped or organized into task-aware batches.
- MedIMeta → Presampling: feeds · Task-presampled access is built on top of the dataset interface.
- Task catalog → Batches: configures · Batching logic depends on standardized task definitions.
- Task catalog → Presampling: configures · Few-shot sampling uses task and class metadata.
- MedIMeta → Logger: reports · Loading and sampling events can be surfaced through logging.
- API surface → MedIMeta: exports · Public package imports expose the main dataset class.
- API surface → Task catalog: exports · Public package imports expose task metadata helpers.
- API surface → Batches: exports · Public package imports expose batching helpers.
- API surface → Presampling: exports · Public package imports expose task-presampling helpers.
- Supervised → PyTorch: uses · Example shows direct supervised consumption in PyTorch.
- ImageNet eval → PyTorch: uses · Example evaluates few-shot tasks inside a standard torch pipeline.
- Pretraining → TorchCross: uses · Example demonstrates cross-domain pretraining with TorchCross.
- MAML → TorchCross: uses · Example demonstrates meta-learning with TorchCross.
- Supervised → API surface: imports · Examples are intended to import from the package surface.
- ImageNet eval → API surface: imports · Examples are intended to import from the package surface.
- Pretraining → API surface: imports · Examples are intended to import from the package surface.
- MAML → API surface: imports · Examples are intended to import from the package surface.
