Skip to content
This repository was archived by the owner on Sep 2, 2026. It is now read-only.

README.md

Latest commit

 

History

History
214 lines (153 loc) · 6.9 KB

README.md

File metadata and controls

214 lines (153 loc) · 6.9 KB
Raw

NILS - Neuroimaging Intelligent Linked System

Archived 2026-09-02. This repository is the public mirror of NILS v0, the 0.x line, kept read-only for its history and its forks. NILS v1, a rewrite, is developed in the open at https://github.com/kineuro/nils. v0 receives bug fixes only; they are not mirrored here.

NILS Logo

A comprehensive system for DICOM classification, sorting, anonymization, and BIDS export

Developed at Karolinska Institutet
Department of Clinical Neuroscience, Neuroradiology

Documentation License: GPL v3 Version

Features

Six-Axis Classification System

NILS classifies MRI series using six orthogonal axes, each backed by its own YAML-driven detector:

Axis Description Examples
Base Contrast weighting T1w, T2w, PD, DWI, BOLD, SWI
Technique Pulse sequence family MPRAGE, TSE, FLASH, EPI, GRASE
Modifier Acquisition enhancements FLAIR, FatSat, MT, IR, PhaseContrast
Construct Derived/map type ADC, FA, T1Map, QSM, CBF, MyelinMap
Provenance Processing pipeline SyMRI, SWIRecon, DTIRecon, EPIMix
Acceleration Parallel imaging GRAPPA, SMS, CAIPIRINHA, CompressedSensing

Specialized branch pipelines handle multi-output acquisitions (SWI, SyMRI, EPIMix/NeuroMix, MP2RAGE) — provenance detection runs first and routes to the correct branch.

Complete Pipeline

  • Extraction — Import DICOM metadata with adaptive batching and per-instance stack creation
  • Sorting — 4-step pipeline: Checkup → Stack Fingerprint → Classification → Completion
  • QC Review — Draft-based quality control with Cornerstone.js DICOM viewer and rules engine
  • Anonymization — De-identify with configurable ID strategies and compression
  • BIDS Export — Self-describing filenames, cross-cohort resolution, field strength filtering

Clinical Data Management

  • CSV import for subjects, events, diseases, observation types, and identifiers
  • Longitudinal tracking: link imaging sessions to diagnoses and clinical timelines
  • Preview/validate before applying any import

Quick Start

Prerequisites

  • Docker & Docker Compose
  • 4GB RAM minimum (8GB recommended)

Start NILS

# Clone the repository
git clone https://github.com/NeuroGranberg/NILS.git
cd NILS

# Start services with your DICOM data
./scripts/manage.sh start --data /path/to/your/dicom/data

# Access the web interface
open http://localhost:5173

Network Options

Mode Command Access
Default start Localhost only (secure)
External start --forward Network/Tailscale accessible

Documentation

Full documentation available at: neurogranberg.github.io/NILS

Usage

Options

Option Description
--data PATH Mount DICOM directory (can specify multiple)
--forward Expose ports externally (default: localhost only)
--clean Remove containers and volumes before starting
--db-dir PATH Override database storage directory
--podman Use Podman instead of Docker (adds :Z SELinux labels)

Examples

# Start with localhost access (default - secure)
./scripts/manage.sh start --data /srv/dicom

# Mount multiple data directories
./scripts/manage.sh start \
  --data /srv/dicom/ct \
  --data /srv/dicom/mr

# Clean start with network access
./scripts/manage.sh start --clean --forward --data /srv/dicom

# Stop services
./scripts/manage.sh stop

Remote Access

SSH tunnel (recommended for default mode):

ssh -L 5173:localhost:5173 user@server
# Then open http://localhost:5173 locally

Tailscale (with --forward mode):

http://your-server.ts.net:5173

Configuration

Environment variables in .env:

Variable Description
APP_ACCESS_TOKEN Secret key for login protection
DB_DATA_DIR Database storage directory
METADATA_DB_DATA_DIR Metadata database directory

Architecture

┌───────────────────────────────────────────────────────┐
│                   Docker Network                       │
│  ┌──────────┐  ┌───────────┐  ┌───────────────────┐  │
│  │    db    │  │ metadata  │  │     backend       │  │
│  │ postgres │  │    db     │  │  FastAPI + Async  │  │
│  └──────────┘  └───────────┘  └───────────────────┘  │
│       │              │                ▲               │
│       │              │       ┌────────┴────────┐     │
│       └──────────────┘       │    frontend     │     │
│     Dual Database System     │  Vite + React   │     │
│  (app state + DICOM metadata)│  + Cornerstone  │     │
│                              └─────────────────┘     │
└───────────────────────────────────────────────────────┘

Testing

# Frontend unit tests
./scripts/manage.sh test-frontend

# Backend unit tests
./scripts/manage.sh test-backend

License

GNU General Public License v3.0 - see LICENSE file.

Citation

If you use NILS in your research, please cite:

Chamyani, N. (2025-2026). NILS - Neuroimaging Intelligent Linked System. Karolinska Institutet, Department of Clinical Neuroscience. https://github.com/NeuroGranberg/NILS

Karolinska Institutet, Department of Clinical Neuroscience, Neuroradiology