Initial upload via tools/push_to_hf.py (architecture: ilex.models.syn_disco.SynDisCo)

README.md

@@ -0,0 +1,97 @@
+---
+library_name: ilex
+tags:
+- jax
+- equinox
+- ilex
+- neuroimaging
+- fieldmap-free
+license: mit
+license_link: https://opensource.org/licenses/MIT
+---
+
+# SynDisCo -- MASILab fieldmap-free EPI distortion correction (b0 + BOLD) -- Synb0-DisCo -- dMRI b0 distortion correction (5-fold)
+
+## Description
+
+SynDisCo is a JAX / Equinox port of MASILab's two
+distortion-correction nets -- Synb0-DisCo (dMRI b0) and
+SynBOLD-DisCo (fMRI BOLD) -- consolidated as a single
+multi-variant family class because the two upstream repos ship
+byte-identical model.py architectures and differ only by
+training corpus.
+
+Each modality is a 5-fold ensemble of a 3D U-Net with 3
+pooling stages, InstanceNorm3d + LeakyReLU(0.01) intra-block
+norm/activation, ConvTranspose3d throughout the decoder (not
+the more typical Conv+Upsample split), and bare 1x1
+Conv3d/ConvTranspose3d at the bottleneck and head. Input is a
+2-channel atlas-space (padded 80x96x80) volume stacking the
+distorted target (b0 or BOLD) with a co-registered T1w
+anatomical; output is a single-channel synthesised undistorted
+target ready to drive FSL TopUp for susceptibility distortion
+correction without reverse-PE acquisition or separate
+fieldmap.
+
+v0 ships two bundles (one per modality), each holding the
+upstream's full 5-fold weights stacked on a leading fold axis.
+The forward applies eqx.filter_vmap across the folds and means
+the output -- byte-equivalent to the upstream pipeline's
+fslmaths -Tmean ensemble step.
+
+
+## Intended use
+
+Synthesise an undistorted b0 from a co-registered T1w anatomical + the distorted b0, for FSL TopUp-driven susceptibility distortion correction when reverse-PE or separate fieldmap acquisition is not available. Input is atlas-space ``(2, 80, 96, 80)`` (channel 0 = distorted b0, channel 1 = T1w; normalised per upstream ``util.normalize_img``); output is the ensemble-mean synth undistorted b0 across all 5 folds. Pair with ANTs / FSL FLIRT for the atlas registration and TopUp + applytopup for the recovery step.
+
+## Usage
+
+```python
+from ilex.models.syn_disco import SynDisCo
+model = SynDisCo.from_pretrained('ilex-hub/syn_disco.b0.1')
+```
+
+## Authors
+
+Schilling K. G., Blaber J., Huo Y., Newton A., Hansen C., Nath V., Yao T., Newlin N. R., Cai L. Y., Yang Q., Landman B. A., et al. (MASILab, Vanderbilt University; Synb0-DisCo + SynBOLD-DisCo upstreams)
+
+## Citation
+
+Schilling K. G., Blaber J., Huo Y., Newton A., Hansen C., Nath V., et al. (2020). Synthesized b0 for diffusion distortion correction (Synb0-DisCo). PLoS One 15(7), e0236418. doi:10.1371/journal.pone.0236418. Yao T., Newlin N. R., Cai L. Y., Yang Q., Williams O., Beason-Held L. L., Resnick S. M., Schilling K. G., Landman B. A. (2023). SynBOLD-DisCo -- Synthetic BOLD images for distortion correction of fMRI without additional calibration scans. Imaging Neuroscience 1, 1-13.
+
+### References
+
+- Schilling K.G., Blaber J., Huo Y., Newton A., Hansen C., Nath V., Shafer A.T., Williams O., Resnick S.M., Rogers B., Anderson A.W., Landman B.A. (2020). Synthesized b0 for diffusion distortion correction (Synb0-DisCo). PLoS One 15(7):e0236418. doi:10.1371/journal.pone.0236418.
+- Yao T., Newlin N.R., Cai L.Y., Yang Q., Williams O., Beason- Held L.L., Resnick S.M., Schilling K.G., Landman B.A. (2023). SynBOLD-DisCo -- Synthetic BOLD images for distortion correction of fMRI without additional calibration scans. Imaging Neuroscience 1, 1-13.
+- Synb0-DisCo upstream code, weights, license - github.com/MASILab/Synb0-DISCO (MIT).
+- SynBOLD-DisCo upstream code, weights, license - github.com/MASILab/SynBOLD-DisCo (MIT).
+
+## License
+
+HF Hub license tag: `mit`
+
+**Effective terms:** MIT (copyright (c) MASILab, Vanderbilt University) on both the upstream code and the pretrained weights of Synb0-DisCo (github.com/MASILab/Synb0-DISCO) and SynBOLD-DisCo (github.com/MASILab/SynBOLD-DisCo). The ilex JAX / Equinox port code is separately licensed under Apache-2.0 / GPL-3.0.
+
+Upstream license reference: https://opensource.org/licenses/MIT
+
+### Copyright
+
+Synb0-DisCo and SynBOLD-DisCo upstreams are copyright (c) MASILab,
+Vanderbilt University, MIT-licensed. The JAX / Equinox port code
+in this package is separately licensed under Apache-2.0 / GPL-3.0
+per the wider ilex license boundary; the MIT terms on the upstream
+weights are preserved through the canonical bundle's _ilex.origin
+= 'pytorch' provenance.
+
+
+## Upstream source
+
+Original weights / reference implementation: https://github.com/MASILab/Synb0-DISCO
+
+## Provenance
+
+This artefact was produced by [ilex](https://github.com/hypercoil/ilex)'s
+save/load pipeline. The architecture is implemented in
+`ilex.models.syn_disco.SynDisCo` and the weights have been converted
+from their upstream format. See the upstream source above
+for the canonical reference.

config.json

@@ -0,0 +1,46 @@
+{
+  "_ilex": {
+    "architecture": "ilex.models.syn_disco.model.SynDisCo",
+    "constructor_kwargs": {
+      "input_channels": 2,
+      "num_folds": 5,
+      "output_channels": 1
+    },
+    "format": "ilex",
+    "framework_version": {
+      "equinox": "0.13.8",
+      "ilex": "0.0.0.dev0",
+      "jax": "0.10.0",
+      "jaxlib": "0.10.0",
+      "numpy": "2.4.4",
+      "safetensors": "0.7.0"
+    },
+    "has_state": false,
+    "origin": "ilex-native",
+    "weights_status": "bundled"
+  },
+  "authors": "Schilling K. G., Blaber J., Huo Y., Newton A., Hansen C., Nath V., Yao T., Newlin N. R., Cai L. Y., Yang Q., Landman B. A., et al. (MASILab, Vanderbilt University; Synb0-DisCo + SynBOLD-DisCo upstreams)",
+  "copyright": "Synb0-DisCo and SynBOLD-DisCo upstreams are copyright (c) MASILab,\nVanderbilt University, MIT-licensed. The JAX / Equinox port code\nin this package is separately licensed under Apache-2.0 / GPL-3.0\nper the wider ilex license boundary; the MIT terms on the upstream\nweights are preserved through the canonical bundle's _ilex.origin\n= 'pytorch' provenance.\n",
+  "data_type": "image",
+  "description": "SynDisCo is a JAX / Equinox port of MASILab's two\ndistortion-correction nets -- Synb0-DisCo (dMRI b0) and\nSynBOLD-DisCo (fMRI BOLD) -- consolidated as a single\nmulti-variant family class because the two upstream repos ship\nbyte-identical model.py architectures and differ only by\ntraining corpus.\n\nEach modality is a 5-fold ensemble of a 3D U-Net with 3\npooling stages, InstanceNorm3d + LeakyReLU(0.01) intra-block\nnorm/activation, ConvTranspose3d throughout the decoder (not\nthe more typical Conv+Upsample split), and bare 1x1\nConv3d/ConvTranspose3d at the bottleneck and head. Input is a\n2-channel atlas-space (padded 80x96x80) volume stacking the\ndistorted target (b0 or BOLD) with a co-registered T1w\nanatomical; output is a single-channel synthesised undistorted\ntarget ready to drive FSL TopUp for susceptibility distortion\ncorrection without reverse-PE acquisition or separate\nfieldmap.\n\nv0 ships two bundles (one per modality), each holding the\nupstream's full 5-fold weights stacked on a leading fold axis.\nThe forward applies eqx.filter_vmap across the folds and means\nthe output -- byte-equivalent to the upstream pipeline's\nfslmaths -Tmean ensemble step.\n",
+  "equinox_version": "0.13.8",
+  "ilex_version": "0.0.0.dev0",
+  "image_classes": "Input is a 2-channel atlas-space ``(2, D, H, W)`` volume,\nchannels-first:\n\n* Channel 0: distorted target. b0 (Synb0 variant) or mean BOLD\n  (SynBOLD variant), N4-bias-corrected, normalised to [-1, 1]\n  by ``2 * (img / p99(img)) - 1`` per upstream ``util.normalize_img``.\n* Channel 1: T1w anatomical. Co-registered to MNI ICBM-152\n  NLIN 2.5mm template\n  (``mni_icbm152_t1_tal_nlin_asym_09c_2_5.nii.gz``), normalised\n  to [-1, 1] with fixed max=150 / min=0.\n\nAtlas-space grid is ``(77, 91, 77)`` (2.5 mm isotropic), padded\nwith zeros to ``(80, 96, 80)`` so the 3 stride-2 MaxPools halve\ncleanly. Pipeline owns the pad/crop boilerplate.\n",
+  "intended_use": "Research / preprocessing use for cohorts where a separate field\nmap or reverse phase-encoded calibration scan was not acquired\nbut a T1w anatomical IS available. Produces a synthesised\nundistorted b0 or BOLD volume that downstream tools (FSL TopUp\n+ applytopup or eddy) consume as the \"calibration\" image for\nsusceptibility distortion correction.\n\nThe ilex port wraps the JAX forward only; consumers are\nresponsible for atlas-space co-registration (ANTs / FSL\nrequired), the eventual TopUp invocation, and the inverse\ntransform back to native subject space. Not a clinical\ndiagnostic tool; downstream validation in the consumer's own\npreprocessing pipeline is required.\n",
+  "jax_version": "0.10.0",
+  "network_data_format": {
+    "inputs": {},
+    "outputs": {}
+  },
+  "numpy_version": "2.4.4",
+  "pred_classes": "Output is a 1-channel atlas-space ``(1, D, H, W)`` volume\n(the synthesised undistorted target), un-normalised by inverting\nthe same p99 scaling applied to the input distorted target. The\npipeline then crops the ``(80, 96, 80)`` ensemble-meaned output\nback to ``(77, 91, 77)``, applies the inverse atlas transform\nvia ANTs to recover native subject space, and (downstream)\nfeeds the result to TopUp.\n",
+  "references": [
+    "Schilling K.G., Blaber J., Huo Y., Newton A., Hansen C., Nath V., Shafer A.T., Williams O., Resnick S.M., Rogers B., Anderson A.W., Landman B.A. (2020). Synthesized b0 for diffusion distortion correction (Synb0-DisCo). PLoS One 15(7):e0236418. doi:10.1371/journal.pone.0236418.",
+    "Yao T., Newlin N.R., Cai L.Y., Yang Q., Williams O., Beason- Held L.L., Resnick S.M., Schilling K.G., Landman B.A. (2023). SynBOLD-DisCo -- Synthetic BOLD images for distortion correction of fMRI without additional calibration scans. Imaging Neuroscience 1, 1-13.",
+    "Synb0-DisCo upstream code, weights, license - github.com/MASILab/Synb0-DISCO (MIT).",
+    "SynBOLD-DisCo upstream code, weights, license - github.com/MASILab/SynBOLD-DisCo (MIT)."
+  ],
+  "schema": "https://github.com/Project-MONAI/MONAI-extra-test-data/releases/download/0.8.1/meta_schema_20240725.json",
+  "task": "fieldmap-free EPI distortion correction (susceptibility-induced) for diffusion-weighted MRI (b0) and BOLD fMRI",
+  "version": "0.0.0"
+}

model.safetensors

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6ff41f947fdf5c0e686b80827ab17746c1774a177d6a3d76be3e1e55fa6bb17f
+size 386596220