[![DOI](https://zenodo.org/badge/1134680274.svg)](https://doi.org/10.5281/zenodo.18252017)


# NeuroTK: Dataset Validation for Neurology Brain Imaging

## Motivation
Neurology brain imaging datasets are heterogeneous and frequently contain inconsistencies. Geometry, spacing, orientation, and annotation issues occur commonly across CT and MRI collections. These problems often surface late in modeling, when remediation is costly and compromises reproducibility. NeuroTK surfaces issues early, explicitly, and reproducibly to support dataset hygiene prior to analysis.

## Scope
NeuroTK focuses on dataset quality assurance prior to downstream analysis. It provides dataset-level and file-level validation with structural and geometric consistency checks, and assessment of annotation presence and integrity.

- Dataset-level and file-level validation
- Structural and geometric consistency checks
- Annotation presence and integrity assessment

NeuroTK does not modify scientific data.

## Installation
```sh
pip install neurotk
```

## Quickstart
```sh
neurotk validate --images imagesTr --labels labelsTr --out report.json
```

Inputs are expected as flat directories of NIfTI files, and filenames must match exactly for image–label pairing.

```
dataset/
  imagesTr/
    case_001.nii.gz
    case_002.nii.gz
  labelsTr/
    case_001.nii.gz
    case_002.nii.gz
```

## Inference (MONAI bundles)
NeuroTK can run inference from external MONAI bundles via the optional inference extras:

```sh
pip install neurotk[inference]
```

Single image:
```sh
neurotk infer \
  --bundle-dir /path/to/bundle \
  --input image.nii.gz \
  --output-dir outputs/
```

Default bundle (uses `NEUROTK_DEFAULT_BUNDLE` or `UMNSHAMLAB/segresnet`):
```sh
neurotk infer \
  --input image.nii.gz \
  --output-dir outputs/
```
Default HF bundle repo: `UMNSHAMLAB/segresnet`.

From Hugging Face (auto-download + cache full bundle):
```sh
neurotk infer \
  --bundle-dir hf:UMNSHAMLAB/segresnet \
  --input image.nii.gz \
  --output-dir outputs/
```

You can also pass a Hugging Face repo URL:
```sh
neurotk infer \
  --bundle-dir https://huggingface.co/UMNSHAMLAB/segresnet \
  --input image.nii.gz \
  --output-dir outputs/
```

Batch mode:
```sh
neurotk infer \
  --bundle-dir /path/to/bundle \
  --input-list images.txt \
  --output-dir outputs/
```

Dice after inference:
```sh
neurotk dice \
  --preds outputs/ \
  --labels-dir labels/ \
  --output outputs/dice_scores.csv
```

Note: for full-bundle HF usage, the repo must contain a valid MONAI bundle layout (e.g., `configs/` with inference/evaluate config and `models/` checkpoints).

## Output
NeuroTK emits a JSON report containing a dataset-level summary, per-file diagnostics, and explicit listings of detected issues.
For validate+preprocess runs, the report includes a processed summary and preprocess traceability so original and processed
states are unambiguous.

```json
{
  "summary": {"scope": "original_inputs", "num_images": 100, "files_with_issues": 7},
  "summary_processed": {"scope": "processed_outputs", "num_images": 100},
  "files": {"case_001.nii.gz": {"issues": ["label_missing"]}}
}
```

### Validate vs preprocess semantics
- `summary` always reflects original inputs.
- `summary_processed` is present only for validate+preprocess runs and reflects outputs after preprocessing.
- `run_mode` indicates whether preprocessing was requested.

### Upgrading to v0.3.0
Reports now include explicit `scope` fields and preprocess traceability blocks. These additions are backward-compatible
for validation-only users.

## Web UI
The FastAPI app in `webapp/` is the primary landing page and execution interface. The older `site/` Next.js prototype
is deprecated and should not be used for deployment.

## Citation
If you use NeuroTK in your research, please cite it as follows:

```bibtex
@software{neurotk,
  title  = {NeuroTK: Dataset Validation for Neurology Brain Imaging},
  author = {Sakshi Rathi},
  year   = {2026},
  doi    = {10.5281/zenodo.18252017},
  url    = {https://github.com/SakshiRa/neurotk},
  note   = {Open-source toolkit for dataset validation and quality assurance in neurology brain imaging}
}
```
