{"id":13688947,"url":"https://github.com/neuronets/nobrainer","last_synced_at":"2026-04-02T18:50:25.124Z","repository":{"id":28823372,"uuid":"94588639","full_name":"neuronets/nobrainer","owner":"neuronets","description":"A framework for developing neural network models for 3D image processing.","archived":false,"fork":false,"pushed_at":"2025-03-31T18:05:50.000Z","size":2541,"stargazers_count":160,"open_issues_count":61,"forks_count":43,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-08T13:11:12.679Z","etag":null,"topics":["machine-learning","medical-imaging","neuroimaging","semantic-segmentation","tensorflow"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/neuronets.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":"CITATION","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-06-16T23:38:47.000Z","updated_at":"2025-04-03T01:27:00.000Z","dependencies_parsed_at":"2023-02-16T12:00:49.480Z","dependency_job_id":"c041e32f-5036-4e52-abbf-e56c57c449c9","html_url":"https://github.com/neuronets/nobrainer","commit_stats":{"total_commits":777,"total_committers":23,"mean_commits":33.78260869565217,"dds":0.7631917631917632,"last_synced_commit":"976691d685824fd4bba836498abea4184cffd798"},"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronets%2Fnobrainer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronets%2Fnobrainer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronets%2Fnobrainer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/neuronets%2Fnobrainer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/neuronets","download_url":"https://codeload.github.com/neuronets/nobrainer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254459083,"owners_count":22074604,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["machine-learning","medical-imaging","neuroimaging","semantic-segmentation","tensorflow"],"created_at":"2024-08-02T15:01:28.484Z","updated_at":"2026-04-02T18:50:25.110Z","avatar_url":"https://github.com/neuronets.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Nobrainer\n\n![Build status](https://github.com/neuronets/nobrainer/actions/workflows/ci.yml/badge.svg)\n\n_Nobrainer_ is a deep learning framework for 3D brain image processing built on\n**PyTorch** and **MONAI**. It provides segmentation models (deterministic and\nBayesian), generative models, a MONAI-native data pipeline, block-based\nprediction with uncertainty quantification, and CLI tools for inference and\nautomated hyperparameter search.\n\nPre-trained models for brain extraction, segmentation, and generation are\navailable in the [trained-models](https://github.com/neuronets/trained-models)\nrepository.\n\nThe _Nobrainer_ project is supported by NIH RF1MH121885 and is distributed\nunder the Apache 2.0 license.\n\n## Models\n\n### Segmentation\n\n| Model | Backend | Application |\n|-------|---------|-------------|\n| [UNet](nobrainer/models/segmentation.py) | MONAI | segmentation |\n| [VNet](nobrainer/models/segmentation.py) | MONAI | segmentation |\n| [Attention U-Net](nobrainer/models/segmentation.py) | MONAI | segmentation |\n| [UNETR](nobrainer/models/segmentation.py) | MONAI | segmentation |\n| [MeshNet](nobrainer/models/meshnet.py) | PyTorch | segmentation |\n| [HighResNet](nobrainer/models/highresnet.py) | PyTorch | segmentation |\n\n### Bayesian (uncertainty quantification)\n\n| Model | Backend | Application |\n|-------|---------|-------------|\n| [Bayesian VNet](nobrainer/models/bayesian/bayesian_vnet.py) | Pyro | segmentation + uncertainty |\n| [Bayesian MeshNet](nobrainer/models/bayesian/bayesian_meshnet.py) | Pyro | segmentation + uncertainty |\n\n### Generative\n\n| Model | Backend | Application |\n|-------|---------|-------------|\n| [Progressive GAN](nobrainer/models/generative/progressivegan.py) | PyTorch Lightning | brain generation |\n| [DCGAN](nobrainer/models/generative/dcgan.py) | PyTorch Lightning | brain generation |\n\n### Other\n\n| Model | Application |\n|-------|-------------|\n| [Autoencoder](nobrainer/models/autoencoder.py) | representation learning |\n| [SimSiam](nobrainer/models/simsiam.py) | self-supervised learning |\n\n### Custom layers\n\n- `BernoulliDropout`, `ConcreteDropout`, `GaussianDropout` — stochastic regularization\n- `BayesianConv3d`, `BayesianLinear` — Pyro-based weight uncertainty layers\n- `MaxPool4D` — 4D max pooling via reshape\n\n### Losses and metrics\n\n**Losses**: Dice, Generalized Dice, Jaccard, Tversky, ELBO (Bayesian), Wasserstein, Gradient Penalty\n\n**Metrics**: Dice, Jaccard, Hausdorff distance (all via MONAI)\n\n## Installation\n\n### pip / uv\n\n```bash\nuv venv --python 3.14\nsource .venv/bin/activate\nuv pip install nobrainer\n```\n\nFor Bayesian and generative model support:\n\n```bash\nuv pip install \"nobrainer[bayesian,generative]\" monai pyro-ppl\n```\n\n### Docker\n\nGPU image (requires NVIDIA driver on host):\n\n```bash\ndocker pull neuronets/nobrainer:latest-gpu-pt\ndocker run --gpus all --rm neuronets/nobrainer:latest-gpu-pt predict --help\n```\n\nCPU-only image:\n\n```bash\ndocker pull neuronets/nobrainer:latest-cpu-pt\ndocker run --rm neuronets/nobrainer:latest-cpu-pt predict --help\n```\n\n## Quick start\n\n### Tutorials\n\nSee the [Nobrainer Book](https://neuronets.dev/nobrainer-book/) for 11\nprogressive tutorials — from installation to contributing.\n\n### sr-tests (somewhat realistic tests)\n\n`nobrainer/sr-tests/` contains pytest integration tests that exercise the\nreal API with real brain data. They run in CI on every push:\n\n```bash\npytest nobrainer/sr-tests/ -v -m \"not gpu\" --tb=short\n```\n\n### Simple API (3 lines)\n\n```python\nfrom nobrainer.processing import Segmentation, Dataset\n\nds = Dataset.from_files(filepaths, block_shape=(128, 128, 128), n_classes=2).batch(2)\nresult = Segmentation(\"unet\").fit(ds, epochs=5).predict(\"brain.nii.gz\")\n```\n\nModels are saved with [Croissant-ML](https://mlcommons.org/croissant/) metadata\nfor reproducibility:\n\n```python\nseg.save(\"my_model\")  # Creates model.pth + croissant.json\nseg = Segmentation.load(\"my_model\")\n```\n\n### Brain segmentation (CLI)\n\n```bash\nnobrainer predict \\\n  --model unet_brainmask.pth \\\n  --model-type unet \\\n  --n-classes 2 \\\n  input_T1w.nii.gz output_mask.nii.gz\n```\n\n### Brain segmentation (Python)\n\n```python\nimport torch\nimport nobrainer\nfrom nobrainer.prediction import predict\n\nmodel = nobrainer.models.unet(n_classes=2)\nmodel.load_state_dict(torch.load(\"unet_brainmask.pth\"))\nmodel.eval()\n\nresult = predict(\n    inputs=\"input_T1w.nii.gz\",\n    model=model,\n    block_shape=(128, 128, 128),\n    device=\"cuda\",\n)\nresult.to_filename(\"output_mask.nii.gz\")\n```\n\n### Bayesian inference with uncertainty maps\n\n```python\nfrom nobrainer.prediction import predict_with_uncertainty\n\nmodel = nobrainer.models.bayesian_vnet(n_classes=2)\nmodel.load_state_dict(torch.load(\"bayesian_vnet.pth\"))\n\nlabel, variance, entropy = predict_with_uncertainty(\n    inputs=\"input_T1w.nii.gz\",\n    model=model,\n    n_samples=10,\n    block_shape=(128, 128, 128),\n    device=\"cuda\",\n)\nlabel.to_filename(\"label.nii.gz\")\nvariance.to_filename(\"variance.nii.gz\")\nentropy.to_filename(\"entropy.nii.gz\")\n```\n\n### Brain generation\n\n```bash\nnobrainer generate \\\n  --model progressivegan.ckpt \\\n  --model-type progressivegan \\\n  output_synthetic.nii.gz\n```\n\n### Zarr v3 data pipeline\n\n```python\nfrom nobrainer.io import nifti_to_zarr, zarr_to_nifti\n\n# Convert NIfTI to sharded Zarr v3 with multi-resolution pyramid\nnifti_to_zarr(\"brain_T1w.nii.gz\", \"brain.zarr\", chunk_shape=(64, 64, 64), levels=3)\n\n# Load Zarr stores directly in the training pipeline\nfrom nobrainer.dataset import get_dataset\n\nloader = get_dataset(\n    data=[{\"image\": \"brain.zarr\", \"label\": \"label.zarr\"}],\n    batch_size=2,\n)\n\n# Round-trip back to NIfTI\nzarr_to_nifti(\"brain.zarr\", \"brain_roundtrip.nii.gz\")\n```\n\n### Training a model\n\n```python\nimport torch\nfrom nobrainer.dataset import get_dataset\nfrom nobrainer.losses import dice\n\ndata_files = [\n    {\"image\": f\"sub-{i:03d}_T1w.nii.gz\", \"label\": f\"sub-{i:03d}_label.nii.gz\"}\n    for i in range(1, 101)\n]\nloader = get_dataset(data=data_files, batch_size=2, augment=True, cache=True)\n\nmodel = nobrainer.models.unet(n_classes=2).cuda()\noptimizer = torch.optim.Adam(model.parameters(), lr=1e-4)\ncriterion = dice()\n\nfor epoch in range(50):\n    model.train()\n    for batch in loader:\n        images, labels = batch[\"image\"].cuda(), batch[\"label\"].cuda()\n        optimizer.zero_grad()\n        loss = criterion(model(images), labels)\n        loss.backward()\n        optimizer.step()\n\ntorch.save(model.state_dict(), \"unet_trained.pth\")\n```\n\n## Automated research (autoresearch)\n\nNobrainer includes an automated hyperparameter search loop that uses an LLM\nto propose training modifications overnight:\n\n```bash\nnobrainer research run \\\n  --working-dir ./research/bayesian_vnet \\\n  --model-family bayesian_vnet \\\n  --max-experiments 15 \\\n  --budget-hours 8\n```\n\nImproved models are versioned via DataLad:\n\n```bash\nnobrainer research commit \\\n  --run-dir ./research/bayesian_vnet \\\n  --trained-models-path ~/trained-models \\\n  --model-family bayesian_vnet\n```\n\n## GPU test dispatch (nobrainer-runner)\n\n[nobrainer-runner](https://github.com/neuronets/nobrainer-runner) submits GPU\ntest suites to Slurm clusters or cloud instances (AWS Batch, GCP Batch):\n\n```bash\nnobrainer-runner submit --profile mycluster --gpus 1 \"pytest tests/ -m gpu\"\nnobrainer-runner status $JOB_ID\nnobrainer-runner results --format json $JOB_ID\n```\n\n## Package layout\n\n- `nobrainer.models` — segmentation, Bayesian, and generative `torch.nn.Module` models\n- `nobrainer.losses` — Dice, Jaccard, Tversky, ELBO, Wasserstein (MONAI-backed)\n- `nobrainer.metrics` — Dice, Jaccard, Hausdorff (MONAI-backed)\n- `nobrainer.dataset` — MONAI `CacheDataset` + `DataLoader` pipeline\n- `nobrainer.prediction` — block-based `predict()` and `predict_with_uncertainty()`\n- `nobrainer.io` — `convert_tfrecords()`, `convert_weights()` (TF → PyTorch migration)\n- `nobrainer.layers` — dropout layers, Bayesian layers, MaxPool4D\n- `nobrainer.research` — autoresearch loop and DataLad model versioning\n- `nobrainer.cli` — Click CLI (`predict`, `generate`, `research`, `commit`, `info`)\n\n## Development and releases\n\nNobrainer uses a two-branch release workflow:\n\n| Branch | Purpose | PyPI version |\n|--------|---------|--------------|\n| `master` | Stable releases | `uv pip install nobrainer` |\n| `alpha` | Pre-releases for testing | `uv pip install --pre nobrainer` |\n\n**Alpha workflow**: Feature branches merge to `alpha`. Each merge triggers\nbook tutorial validation (using a matching branch on\n[nobrainer-book](https://github.com/neuronets/nobrainer-book) if available,\notherwise the book's `alpha` branch) followed by an automatic pre-release\ntag (e.g., `0.5.0-alpha.0`).\n\n**Stable workflow**: When `alpha` is merged to `master` with the `release`\nlabel, a stable version is tagged and published to PyPI.\n\n**GPU CI**: PRs to `master` can request GPU testing on EC2 by adding the\n`gpu-test-approved` label. Instance type and spot pricing are configurable\nvia `gpu-instance:\u003ctype\u003e` and `gpu-spot:true` labels.\n\n## Citation\n\nIf you use this package, please [cite](https://github.com/neuronets/nobrainer/blob/master/CITATION) it.\n\n## Questions or issues\n\nPlease [submit a GitHub issue](https://github.com/neuronets/helpdesk/issues/new/choose).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuronets%2Fnobrainer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fneuronets%2Fnobrainer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fneuronets%2Fnobrainer/lists"}