README.md

---
library_name: ilex
tags:
- jax
- equinox
- ilex
- neuroimaging
- fmri
license: cc-by-nc-4.0
license_link: https://creativecommons.org/licenses/by-nc/4.0/
gated: auto
extra_gated_prompt: |
  CortexMAE is distributed under the Creative Commons
  Attribution-NonCommercial 4.0 International license
  (CC-BY-NC-4.0). Permission is granted to use, copy, modify,
  and distribute the weights solely for non-commercial
  research and educational purposes. Commercial use --
  including clinical decision support, clinical workflows,
  products, or services for a fee -- requires separate
  written authorisation from MedARC-AI.

  By requesting access you affirm that your intended use falls
  within the CC-BY-NC-4.0 terms.
extra_gated_fields:
  Name: text
  Affiliation: text
  Email: text
  Intended use: text
  I acknowledge the CC-BY-NC v4 terms: checkbox
extra_gated_button_content: Acknowledge and download
---

# CortexMAE (ViT-B MAE foundation model for fMRI) -- CortexMAE flat (2D flat brain map input)

## Description

CortexMAE (MedARC-AI, arXiv 2510.13768) is a ViT-B masked
autoencoder pretrained on 2.1K hours of HCP fMRI BOLD data.
The architecture is the standard MAE (encoder + lighter
decoder + MSE loss on reconstructed patches) with separate
Q/K/V Linears (the original MAE convention) and separable
spatial + temporal positional embeddings (mae-st style).

v0 ships **the parcel variant only** (``cortex_mae_parcel`` --
Schaefer-400 1D parcellation input). The flat (2D brain map)
and volume (3D MNI cortex) variants are queued as follow-ups
(#157 + #158) on top of the same shared transformer body.


## Intended use

Cortical flat-map 2D backbone. Input (1, 16, 224, 560): 1 BOLD channel, 16 temporal frames, 224x560 flat map. Output: cls embedding (1, 768) + patch embeddings (1960, 768) over 4 temporal x 14x35 spatial patches.

## Usage

```python
from ilex.models.cortex_mae import CortexMAE
model = CortexMAE.from_pretrained('ilex-hub/cortex_mae.flat.1')
```

## Authors

MedARC-AI (research collective)

## Citation

Adkinson R. et al. (2025). CortexMAE -- A masked autoencoder foundation model for fMRI. arXiv 2510.13768.

### References

- Adkinson R. et al. (2025). CortexMAE -- A masked autoencoder foundation model for fMRI. arXiv 2510.13768.
- Feichtenhofer C. et al. (2022). Masked autoencoders as spatiotemporal learners (MAE-ST). NeurIPS.
- Upstream code -- github.com/MedARC-AI/CortexMAE (Apache-2.0); weights -- huggingface.co/medarc/CortexMAE (CC-BY-NC-4.0).

## License

HF Hub license tag: `cc-by-nc-4.0`

**Effective terms:** CC-BY-NC-4.0 on the released checkpoint weights (huggingface.co/medarc/CortexMAE, LICENSE.models). The upstream code (github.com/MedARC-AI/CortexMAE) is separately Apache-2.0. Non-commercial restriction on the weights requires gated distribution with explicit acknowledgement. The ilex JAX / Equinox port code is separately Apache-2.0 / GPL-3.0; non-commercial use only continues to apply to the weights regardless of the port-code licence.

Upstream license reference: https://creativecommons.org/licenses/by-nc/4.0/

### Copyright

CortexMAE upstream code is copyright (c) MedARC-AI, Apache-2.0
on the code (github.com/MedARC-AI/CortexMAE, LICENSE) and
CC-BY-NC-4.0 on the released checkpoint weights
(huggingface.co/medarc/CortexMAE, LICENSE.models). The
non-commercial restriction on the weights is preserved through
gated HuggingFace distribution; the ilex JAX / Equinox port
code is separately Apache-2.0 / GPL-3.0.


## Upstream source

Original weights / reference implementation: https://github.com/MedARC-AI/CortexMAE

## Provenance

This artefact was produced by [ilex](https://github.com/hypercoil/ilex)'s
save/load pipeline. The architecture is implemented in
`ilex.models.cortex_mae.CortexMAE` and the weights have been converted
from their upstream format. See the upstream source above
for the canonical reference.