API Reference

MRITestData

Query and download free, open-access MRI k-space datasets and load them into MRIFiles.RawAcquisitionData.

Supported sources: MRIDATA (mridata.org), OCMR_SOURCE (the OCMR cardiac repository), CMRXRECON2024 (the CMRxRecon2024 challenge data), CMRXRECON300 (the CMRxRecon-300 undersampled cardiac dataset), USC_SPEECH (the USC SPAN 75-speaker spiral speech rtMRI dataset), M4RAW (the M4Raw 0.3 T low-field brain dataset), and FASTMRI (the NYU fastMRI knee/brain/prostate/breast k-space dataset). mridata.org, OCMR and USC Speech serve ISMRMRD .h5 files (USC Speech range-extracted from a figshare ZIP); the CMRxRecon sources ship MATLAB .mat k-space; M4Raw and fastMRI ship fastMRI-layout .h5 files (M4Raw range-extracted from Zenodo ZIPs; fastMRI range-extracted from .tar.xz archives via xz block-level HTTP range requests for knee/brain, and from .tar.gz archives via zran checkpoints for prostate/breast), all converted to a cached ISMRMRD file on first load. All are read via MRIFiles.

fastMRI access is gated: fill the form at https://fastmri.med.nyu.edu; the confirmation email contains 90-day pre-signed AWS S3 URLs for all archives. Pass the email body to set_fastmri_urls! once; credentials are persisted across sessions until they expire.

Quick start

using MRITestData
entries = list_datasets(OCMR_SOURCE; field_strength = 1.5)
MRITestData.set_download_path!(:cache)  # once per machine: where downloads go
path = download_dataset(entries[1])     # downloads (cached), returns path
raw  = load_raw(path)                   # MRIFiles.RawAcquisitionData

AbstractSource

Base type for a free MRI dataset repository. Concrete sources are singletons (MRIDATA, OCMR_SOURCE) that know how to enumerate their catalog (list_datasets) and build download URLs.

MridataOrg <: AbstractSource

The mridata.org repository. Datasets are identified by a UUID and downloaded as ISMRMRD .h5 from https://mridata.org/download/{uuid}. The shared instance is MRIDATA.

OCMR <: AbstractSource

The Open-access repository for Multi-coil k-space data (cardiac CMR). Files are ISMRMRD .h5 served from an S3 bucket. The shared instance is OCMR_SOURCE.

CMRxRecon2024 <: AbstractSource

The CMRxRecon2024 cardiac MRI challenge dataset, hosted on Synapse as a single ~835 GB archive (ChallengeData.zip) split into 210 raw 4 GB byte fragments. Rather than downloading the whole archive, individual k-space .mat files are extracted over the network with HTTP byte-range requests against a pre-computed offset map (see data/cmrxrecon2024_map.csv). Access requires a Synapse Personal Access Token (see set_synapse_token!). The shared instance is CMRXRECON2024.

CMRxRecon300 <: AbstractSource

The CMRxRecon-300 dataset (revised CMRxRecon-2023 challenge dataset): raw cardiac k-space from 300 healthy volunteers (cine + T1/T2 mapping). The _ks files are undersampled (regular k-t pattern, R≈3) with separate fully-sampled ACS _calib files; hosted on Synapse (syn52965326) as .tar.gz archives split into raw 16 GiB byte fragments. A .tar.gz cannot be range-extracted per member, so individual .mat files are recovered with a pre-built zran checkpoint index (see scripts/index_cmrxrecon300.jl) plus HTTP range requests. Access requires a free Synapse account / Personal Access Token (see set_synapse_token!); the data is CC-BY (no challenge registration). The shared instance is CMRXRECON300.

USCSpeech <: AbstractSource

The USC SPAN 75-speaker speech-production real-time MRI dataset (figshare 13725546, CC BY 4.0). Provides 2D sagittal-view raw spiral k-space of the vocal tract acquired on a GE Signa Excite 1.5 T scanner (13-interleaf spiral-out GRE, custom 8-channel upper-airway array) in vendor-agnostic MRD/ISMRMRD .h5. The whole corpus is a single ~570 GB dataset.zip; individual .h5 files are extracted over the network with HTTP byte-range requests against a pre-computed offset map (see data/usc_speech_map.csv). The data is public CC-BY — no account or token is required. The shared instance is USC_SPEECH.

M4Raw <: AbstractSource

The M4Raw low-field brain MRI dataset (Zenodo record 8056074, CC BY 4.0). Provides multi-contrast (T1w/T2w/FLAIR + T1 GRE), multi-repetition, multi-slice raw Cartesian k-space acquired on a 0.3 T whole-body scanner with a 4-channel head coil. Each .h5 member follows the fastMRI layout (kspace, reconstruction_rss, ismrmrd_header) and is converted to a cached ISMRMRD file on first load. The corpus ships as several multi-GB Zenodo ZIPs; individual .h5 files are extracted over the network with HTTP byte-range requests against a pre-computed offset map (see data/m4raw_map.csv). The data is public CC-BY — no account or token is required. The shared instance is M4RAW.

FastMRI <: AbstractSource

The fastMRI dataset (NYU / Facebook AI Research): knee, brain, prostate, and breast MRI k-space acquired on clinical Siemens/GE scanners and stored in the fastMRI HDF5 layout (kspace, reconstruction_rss, ismrmrd_header). Knee and brain are hosted as .tar.xz archives on AWS S3; prostate and breast as .tar.gz.

Access is gated: fill the request form at https://fastmri.med.nyu.edu; the confirmation email contains time-limited (90-day) AWS pre-signed download URLs. Provide them to this package via set_fastmri_urls!.

The catalog is a static offset map committed under data/fastmri_map.csv, built by the maintainer scripts scripts/index_fastmri.jl (.tar.xz) and scripts/index_fastmri_gz.jl (.tar.gz). Individual .h5 members are range-extracted from the .tar.xz archives via xz-block-level HTTP range requests (one block per member), and from the .tar.gz archives via zran checkpoints (data/fastmri_zran/) seeded into a raw-inflate decoder. Like M4Raw, the extracted files are in fastMRI layout and are converted to cached Cartesian ISMRMRD on first load. The shared instance is FASTMRI.

Shared MridataOrg source instance.

Shared OCMR source instance.

Shared CMRxRecon2024 source instance.

Shared CMRxRecon300 source instance.

Shared USCSpeech source instance.

Shared M4Raw source instance.

Shared FastMRI source instance.

list_sources() -> Vector{AbstractSource}

Return all dataset sources supported in this version.

terms_url(source) -> String

URL to the terms of use / data-use policy for source.

terms_notice() -> String

The data-source terms-of-use notice, one source_name → terms_url line per entry of list_sources. Generated rather than written out, so a new source cannot be added to the package while staying invisible in the startup warning.

DatasetEntry

Metadata describing a single downloadable MRI dataset. Returned by list_datasets and used to drive downloading and loading.

Field names, vocabularies and units are anchored in the DICOM standard — see dicom_tag and docs/src/taxonomy.md for the full mapping. A handful of fields have no DICOM equivalent (receiver_channels, split, cohort, undersampling_pattern, quantitative, trajectory, acceleration); these are documented in TAXONOMY_EXTENSIONS with their justification.

Fields

Identity

• source::AbstractSource: which repository hosts the file.
• id::String: source-specific identifier (mridata UUID, OCMR file stem, ...).
• name::String: human-readable label — Series Description (0008,103E).

Subject

• subject_id::Union{String,Nothing}: Clinical Trial Subject ID (0012,0040).
• cohort::Union{Symbol,Nothing}: :volunteer/:patient/:phantom. EXTENSION.
• split::Union{Symbol,Nothing}: :train/:val/:test/:demo. EXTENSION.
• repetition::Union{Int,Nothing}: Acquisition Number (0020,0012).

System

• vendor::Union{Symbol,Nothing}: e.g. :siemens, :ge — Manufacturer (0008,0070).
• scanner_model::Union{String,Nothing}: Manufacturer Model Name (0008,1090).
• institution::Union{String,Nothing}: Institution Name (0008,0080).
• field_strength::Union{Float64,Nothing}: tesla — Magnetic Field Strength (0018,0087).
• receiver_channels::Union{Int,Nothing}: count of used receive channels. EXTENSION.
• coil_data::Symbol: :original/:derived — Image Type value 1 (0008,0008).

What was imaged

• anatomy::Symbol: e.g. :knee, :brain, :heart — Body Part Examined (0018,0015).
• contrast::Symbol: T1/T2/T2*/proton-density/... — Acquisition Contrast (0008,9209).
• orientation::Union{Symbol,Nothing}: e.g. :short_axis — View Code Sequence (0054,0220).
• sequence::Union{String,Nothing}: spelled-out pulse sequence name, never abbreviated — Pulse Sequence Name (0018,9005).
• echo_type::Union{Symbol,Nothing}: :spin/:gradient/:both — Echo Pulse Sequence (0018,9008).
• quantitative::Bool: parametric-mapping acquisition (T1map/T2map/...). EXTENSION.

Acquisition geometry

• acquisition_dim::Int: 1/2/3 — MR Acquisition Type (0018,0023).
• num_slices::Union{Int,Nothing}: Number of Frames (0028,0008).
• num_frames::Union{Int,Nothing}: cardiac/temporal frames — Cardiac Number of Images (0018,1090).
• num_averages::Union{Int,Nothing}: Number of Averages (0018,0083).

Sampling

• trajectory::Symbol: ISMRMRD trajectoryType — :cartesian, :epi, :radial, :goldenangle, :spiral, :other, :unknown. EXTENSION (more expressive than DICOM).
• fully_sampled::Union{Bool,Nothing}: Percent Sampling (0018,0093) == 100.
• acceleration::Union{Float64,Nothing}: net R at the source's native frame binning. EXTENSION.
• undersampling_pattern::Union{Symbol,Nothing}: e.g. :vista, :kt_gaussian. EXTENSION.
• partial_fourier::Union{Bool,Nothing}: Partial Fourier (0018,9081).
• has_acs::Bool: Parallel Acquisition (0018,9077).

Cardiac / contrast-agent flags

• cardiac_sync::Symbol: :none/:realtime/:prospective/:retrospective/:paced — Cardiac Synchronization Technique (0018,9037).
• phase_contrast::Bool: Phase Contrast (0018,9014).
• blood_signal_nulling::Bool: Blood Signal Nulling (0018,9022).
• fat_suppression::Union{Symbol,Nothing}: Spectrally Selected Suppression (0018,9025).
• contrast_agent::Union{Bool,Nothing}: Contrast/Bolus Agent present (0018,0010).

Transport (non-DICOM)

• file_format::Symbol: :ismrmrd/:fastmri_h5/:matlab_v73.
• approx_size_bytes::Union{Int,Nothing}: rough download size.
• sha256::Union{String,Nothing}: pinned checksum, if known.
• url::String: resolved download URL.
• extra::Dict{String,Any}: source-specific metadata, keyed by DICOM keyword where one exists (see dicom_tag and extra_schema).
• locator::Dict{String,Any}: transport coordinates (byte offsets, archive names) needed to fetch the file. Not DICOM-anchored; never text-searched or displayed.

DatasetHandle(entry::DatasetEntry)

A DatasetEntry bound for download/loading. Currently a thin wrapper that lets the API accept either an entry or a handle; created by dataset.

list_datasets(source::AbstractSource; filters...) -> Vector{DatasetEntry}

Return the catalog entries for source, optionally narrowed by keyword filters (see _matches). The catalog is read from a committed metadata file, so this works offline.

A filter value of missing (or an omitted key) does not filter; nothing matches entries whose field is unset, so fully_sampled = nothing finds the ones with unknown sampling.

Examples

list_datasets(MRIDATA; anatomy = :knee, fully_sampled = true)
list_datasets(OCMR_SOURCE; field_strength = (1.5, 3.0))
list_datasets(MRIDATA; coils = c -> c !== nothing && c >= 8)
list_datasets(FASTMRI; coils = nothing)          # coil count not recorded

query(; sources = list_sources(), text = missing, offline = false, strict = false, filters...)
    -> Vector{DatasetEntry}

Search across one or several dataset sources and return the matching entries.

This is the cross-source counterpart of list_datasets: it queries every source in sources and concatenates the results, applying the same keyword filters. Unknown keywords (those that are not DatasetEntry fields) are matched against the per-source extra metadata (see extra_schema), so you can filter on source-specific attributes such as repetition_time_ms = t -> t < 10 or scanner_model = "Siemens MAGNETOM Sola".

Keywords

• sources: a single source or a collection of sources to search (default: all of list_sources).
• text: a case-insensitive substring (or a predicate, or a Regex) matched against the entry's name, id, and the string values in extra (never locator). missing (the default) disables it.
• offline: pass true to use only the committed fallback index (no network).
• strict: pass true to error on a filter keyword that is neither a DatasetEntry field nor in any queried source's extra_schema (a likely typo). The default just @warns and treats it as an always-empty extra filter.
• filters...: per-field filters as in list_datasets / _matches. A filter value may be a scalar (==), a collection (in), a predicate, or missing for no filter. Keys that are not DatasetEntry fields are looked up in extra, where a key the entry does not carry reads as nothing.

nothing is a value rather than a wildcard, so fully_sampled = nothing selects entries with unknown sampling and cohort = nothing selects entries carrying no cohort.

Examples

query(; anatomy = :knee, fully_sampled = true)                 # every source
query(; sources = OCMR_SOURCE, field_strength = (1.5, 3.0))
query(; text = "prisma")                                       # free-text over name/id/extra
query(; cohort = :patient)                                     # patients, not volunteers
query(; field_strength = f -> f !== nothing && f >= 3.0)
query(; receiver_channels = nothing)                            # channel count not recorded

query(text::AbstractString; sources = list_sources(), offline = false, strict = false)
    -> Vector{DatasetEntry}

The string-expression counterpart of the keyword form of query: parse text as a boolean expression and return the matching entries.

Grammar

or_expr  := and_expr (OR and_expr)*
and_expr := atom (AND atom)*
atom     := '(' or_expr ')' | field OP value
OP       := '=' | '!=' | '<' | '<=' | '>' | '>='

AND/OR are case-insensitive and AND binds tighter than OR; parenthesize to override. A value is a bare word, a 'single'/"double"-quoted string, a number, or the bare word nothing (also null/missing/none) — R = nothing matches entries with no acceleration, R != nothing matches the ones that have it. A number may carry a size suffix — K/M/G (1000-based) or Ki/Mi/Gi (1024-based), with an optional trailing B — so size < 100M and size >= 2GiB work (a lone trailing T is ignored, so b0=3T reads as 3). A string containing * is matched as a case-insensitive glob (* → any run of characters, anchored); without * it's an exact case-insensitive compare. </<=/>/>= compare numerically and never match a non-numeric or missing field.

field accepts any DatasetEntry field name, a friendly alias matching the browser's column headers (dataset/source, r/accel → acceleration, b0 → field_strength, channels → receiver_channels, frames → num_frames, size → approx_size_bytes, sampling → the same fully-sampled/pattern value the browser displays), or a per-source extra key (see extra_schema) — all case-insensitive. strict = true errors on an unknown field instead of @warning and matching nothing.

Examples

query("dataset=fastmri AND R<3")
query("id='fs_*'")
query("(anatomy=knee AND R<3) OR fully_sampled=true")
query("dataset=ocmr AND size < 100M")
query("R != nothing")                     # only entries with a known acceleration

dataset(source::AbstractSource, id::AbstractString) -> DatasetHandle

Look up a dataset by id. If id is in the curated catalog the full metadata is used; otherwise (where the source supports it, e.g. an arbitrary mridata UUID) a minimal entry is synthesised from id.

dicom_tag(field::Symbol) -> Union{Tuple{UInt16,UInt16,String},Nothing}

The (group, element, keyword) DICOM attribute anchoring field, or nothing when field is an TAXONOMY_EXTENSIONS extension with no DICOM equivalent.

dicom_keyword(field::Symbol) -> Union{String,Nothing}

The DICOM keyword for field (e.g. :field_strength → "MagneticFieldStrength"), or nothing when field has no DICOM anchor.

DICOM_ATTRIBUTES

Dict{Symbol,Tuple{UInt16,UInt16,String}} mapping a DatasetEntry core field, or a DICOM-keyword-named extra key (as a Symbol), to its (group, element, keyword) DICOM attribute. Fields with no DICOM anchor are omitted here — see TAXONOMY_EXTENSIONS.

TAXONOMY_EXTENSIONS

Dict{Symbol,String} mapping each field that has no DICOM attribute to a one-line justification. See docs/src/taxonomy.md for the full rationale.

extra_schema(source) -> Dict{String,String}

The extra keys source may populate, each mapped to a one-line description. Declared beside each source's parser; feeds query's keyword validation, the browser's details pane, and the generated docs table. Defaults to an empty Dict for a source that puts everything it knows into core fields.

CONTRASTS

Controlled vocabulary for DatasetEntry.contrast — DICOM Acquisition Contrast (0008,9209) defined terms (PS3.3 §C.8.13.3), lowercased snakecase. Proton density is a contrast; cine/mapping/tagging/flow/black-blood are not — they are sequence / `cardiacsync/phasecontrast/bloodsignal_nulling` instead.

TRAJECTORIES

Controlled vocabulary for DatasetEntry.trajectory — the ISMRMRD trajectoryType enumeration, verbatim (ismrmrd.xsd). An EXTENSION (no single DICOM attribute is this expressive): strictly more expressive than DICOM's Geometry of k-Space Traversal (0018,9032), which lacks EPI and golden-angle.

ANATOMIES

Controlled vocabulary for DatasetEntry.anatomy — DICOM Body Part Examined (0018,0015) defined terms, lowercased (PS3.16 Annex L). :other covers mridata.org's open-ended scraped anatomy text (hip, shoulder, spine, phantom, ...) that this package does not curate a term for — distinct from :unknown (not recorded at all).

CARDIAC_SYNC

Controlled vocabulary for DatasetEntry.cardiac_sync — DICOM Cardiac Synchronization Technique (0018,9037) defined terms (PS3.3 §C.7.6.18).

FAT_SUPPRESSION

Controlled vocabulary for DatasetEntry.fat_suppression — DICOM Spectrally Selected Suppression (0018,9025) defined terms.

ECHO_TYPES

Controlled vocabulary for DatasetEntry.echo_type — DICOM Echo Pulse Sequence (0018,9008) defined terms.

COIL_DATA

Controlled vocabulary for DatasetEntry.coil_data — DICOM Image Type (0008,0008) value 1, applied to the channel data. An EXTENSION (§4.1): no DICOM attribute counts receiver channels, but ORIGINAL/DERIVED covers emulated/virtual coils.

SPLITS

Controlled vocabulary for DatasetEntry.split — the ML-corpus partition. EXTENSION: not an imaging concept, so DICOM has no attribute for it.

COHORTS

Controlled vocabulary for DatasetEntry.cohort — EXTENSION: DICOM has no research-subject-class attribute.

UNDERSAMPLING_PATTERNS

Controlled vocabulary for DatasetEntry.undersampling_pattern. EXTENSION: DICOM's Parallel Acquisition Technique (0018,9078) names the reconstruction (SENSE/GRAPPA), not the sampling mask — VISTA, kt-Gaussian, kt-radial, Poisson-disc have no DICOM term.

ORIENTATIONS

Controlled vocabulary for DatasetEntry.orientation. Anchored on DICOM View Code Sequence (0054,0220) as a container, but DICOM publishes no Context Group for cardiac MR views (the cardiac view CIDs are echocardiography), so these are local symbols (§4.6) rather than SNOMED codes. :lvot = left ventricular outflow tract.

refresh_index(source; progress=true, fetch_sizes=false)
refresh_index(; progress=true, fetch_sizes=false)

Force-refresh the cached dataset index from upstream — the manual trigger. With no argument, refreshes every source in parallel. Returns the index path(s); a source whose index is static (_is_static_index) has nothing to refresh and simply reports its bundled map.

When fetch_sizes=true, an HTTP HEAD request is issued for each entry whose size is not already known, and the result is stored as approx_size_bytes in the index. This costs one extra round-trip per entry but enables the max_bytes guard in download_dataset for sources (like mridata.org) that do not publish sizes in their catalog. The option has no effect for sources that already carry size information.

index_path(source) -> String

Path to the cached index file for source (may not exist yet).

index_age_days(source) -> Union{Float64,Nothing}

Age (in days) of the cached index for source, or nothing if it has never been fetched (in which case the bundled fallback is in use).

MRITestData.INDEX_TTL_DAYS

Ref{Int} holding how many days a cached dataset index stays fresh before it is refetched from upstream. Defaults to 30. Set MRITestData.INDEX_TTL_DAYS[] = n to change the refresh period. Use MRITestData.set_refresh_period! to persist the value across sessions.

set_download_path!(dir::AbstractString)
set_download_path!(:cache)

Choose where downloaded datasets (and their cached ISMRMRD conversions) are stored, and persist the choice in LocalPreferences.toml.

Until this is called all downloads are refused — download_dataset, copy_dataset and an entry-based load_raw throw with instructions. (Passing path= to download_dataset is the one-off exception.)

• set_download_path!(dir) uses dir (created if missing) as the cache root.
• set_download_path!(:cache) uses the package's per-user Scratch space — the original default behaviour.

Retrieve the current value with get_download_path; clear it with unset_download_path!.

get_download_path() -> Union{String, Nothing}

Return the configured download directory, or nothing if none has been set (in which case downloads are refused — see set_download_path!).

unset_download_path!()

Forget the persisted download path. Downloads are refused again until set_download_path! is called.

download_dataset(x; path=nothing, force=false, verify=true, progress=true, max_bytes=nothing) -> String

Download the dataset for x (a DatasetEntry or DatasetHandle) into the cache and return its path. If already cached (see is_cached) the cached path is returned without re-downloading unless force=true.

A download destination must be configured with set_download_path! first; until then this throws. Passing path is the exception — see below.

• path: download into this directory instead of the configured cache and return the file path there. Works even when no default download path has been set. The file is reused on a later call if it is already present (unless force=true); no .meta.toml freshness tracking is done for an explicit path.
• verify: when the entry pins a sha256, verify the download against it.
• progress: show a ProgressMeter bar (set false to opt out).
• max_bytes: if the entry's approx_size_bytes exceeds this, error before downloading. Use this in tests/CI to avoid pulling large files by accident.

The download goes to <path>.part and is atomically renamed on success; a sidecar .meta.toml records the url, size and computed checksum.

For servers that support byte-range requests (both OCMR and mridata.org back onto Amazon S3 and support Accept-Ranges: bytes), the transfer is automatically parallelised across MRITestData.PARALLEL_CHUNKS[] chunks, giving a ~1.5–2.5× speed improvement on high-latency connections.

copy_dataset(x, dest; force=false, verify=true, progress=true, max_bytes=nothing) -> String

Ensure the dataset for x is available at dest, downloading only if necessary.

1. If the Scratch cache already holds the file and it is unmodified (checked via the stored sha256 or mtime), the file is copied to dest — no HTTP request is made.
2. If the cache is missing or stale, the file is downloaded first (into the Scratch cache) and then copied.

Returns dest. Keyword arguments are the same as download_dataset.

cache_path(x) -> String

The path where the dataset for x (a DatasetEntry or DatasetHandle) is or would be cached. Does not check existence.

is_cached(x) -> Bool

Whether the dataset for x is already present in the cache and unmodified.

Validation strategy (in order):

1. File must exist.
2. If the entry pins a sha256, the recorded checksum in the sidecar must match.
3. Otherwise the recorded mtime must match the file's current modification time (fast check; skipped when there is no sidecar yet).

clear_cache(; source = nothing)

Delete cached files. With source = nothing (default) clears every source; otherwise clears only that source's subdirectory.

fetch_sizes(entries; timeout=15) -> Vector{DatasetEntry}

Issue one HTTP HEAD request per entry whose approx_size_bytes is not yet known and return a new Vector{DatasetEntry} with the approx_size_bytes field filled in where the server reported a Content-Length. Entries that already have a size, or whose server does not advertise one, are returned unchanged.

The HEAD requests are fired in parallel (one @async task per entry), so the total wall time is roughly the latency of the slowest single request rather than the sum of all requests.

entries = list_datasets(OCMR_SOURCE)
entries = fetch_sizes(entries)         # fills in approx_size_bytes

sizes_path(source) -> String

Path to the persisted dataset sizes sidecar for source. Stores a mapping from dataset id to approx_size_bytes so sizes fetched via HTTP HEAD are not lost across sessions. Lives alongside the cached index in the index directory.

read_sizes(source) -> Dict{String,Int}

Return the persisted id → size mapping for source, or an empty dict if none exists.

write_sizes(source, sizes::Dict{String,Int})

Persist sizes (id → approxsizebytes) for source, merging with any previously stored values. Existing entries are never removed — sizes are expected to be stable.

load_raw(path; slice=nothing, repetition=nothing, contrast=nothing) -> RawAcquisitionData
load_raw(entry_or_handle; kwargs...) -> RawAcquisitionData

Read an ISMRMRD .h5 file at path into a MRIFiles.RawAcquisitionData (raw profiles plus the parsed XML header in .params). Optional slice, repetition and contrast filter which profiles are loaded.

Given a DatasetEntry or DatasetHandle, the dataset is downloaded (and cached) first; CMRxRecon2024 entries are converted from their MATLAB k-space (plus the paired undersampling mask) into a cached ISMRMRD file transparently.

Two exporter defects are repaired on the way through: cardiac OCMR files' ECG <waveformInformation> blocks are stripped from the cached HDF5 (MRIFiles misparses them), and profiles left with sample_time_us = 0 — every profile of a USC Speech spiral file — get the dwell time implied by the sequence's trajectoryDescription, without which building a non-Cartesian trajectory throws ArgumentError: range step cannot be zero.

To reconstruct, build an AcquisitionData from the result and hand it to a reconstruction package such as MRIReco.jl — see the "Reconstruction with MRIReco" section of the documentation.

load_mat(x) -> Dict{String,Any}

Load a MATLAB .mat file into a Dict mapping variable name to value. x may be:

• a path to a .mat file;
• a DatasetEntry or DatasetHandle — it is downloaded (cached) first via download_dataset, then loaded.

Used primarily for CMRxRecon2024, whose k-space data ships as v7.3 .mat files.

e = list_datasets(CMRXRECON2024; offline = true)[1]
data = load_mat(e)            # downloads + reads
keys(data)                    # e.g. "kspace_full", "kspace_sub", ...

run_browser(; sources=list_sources(), offline=false)

Open a full-screen interactive browser for MRI datasets.

Launches a Tachikoma.jl PagedDataTable that lets you search, filter, sort, and select a dataset for download — all from the terminal, including from within the Julia REPL.

Keys

• ↑ ↓ move selection; PgUp/PgDn change page
• s (or /) open the search / expression-query overlay (see below); Enter applies, Esc cancels
• f open the per-column filter modal (single-column, typed filters). On its column list: p cycles the highlighted column's missing-value filter (none → present → missing → none), x clears every active filter (per-column, missing-value, and the expression query)
• c open the column-visibility picker — Space toggles the highlighted column, Enter applies, Esc cancels; "#" (the row index) is always shown. The applied selection is persisted in LocalPreferences.toml and restored on the next launch
• 1-9 sort by that column (toggles ascending/descending)
• d open the details pane for the highlighted dataset — a keyword │ value │ description table of every extra key it carries (the keyword is also its query/list_datasets filter name; the description column wraps). Esc/d/q closes it — no download quit
• Enter select the highlighted dataset and start the download flow
• q / Esc quit without downloading

When sources narrows the session to a single source, a couple of that source's most useful extra fields (e.g. OCMR's scanner_model) are added as real columns — sortable/filterable like any other — on top of the base column set; they're also toggleable from the column picker and queryable by their extra_schema key.

Search / expression queries (s) use the same boolean language as the string form of query — AND/OR (AND binds tighter), parentheses, =/!=/</<=/>/>=, quoted or bare values, * wildcards for string matches, K/M/G size suffixes on numbers, and nothing for "no value":

(dataset=fastmri AND R<3) OR id='fs_*'
anatomy=knee AND fully_sampled=true
size < 100M
R != nothing

Field names accept any DatasetEntry field, the friendly aliases matching the table's column headers (dataset/source, r, b0, channels, frames, size, sampling), or a per-source extra key. Changing the visible columns resets the per-column filter/sort state (column indices move underneath it); an expression query keeps it.

After selecting a dataset you are asked to confirm (y/n) and to choose a destination path. The default is <current directory>/<id>.h5; press Enter to accept it. CMRxRecon downloads need a Synapse access token; if none is configured you are prompted for one (saved to LocalPreferences.toml for reuse).

Dataset sizes (the Size column) are fetched in the background via HTTP HEAD requests as you browse. Sizes for the current page and the adjacent pages are prefetched automatically; previously fetched sizes are reused.

Returns the path of the downloaded file, or nothing if you quit without downloading. A failed download is reported and then rethrown, so the cause reaches the REPL.

using MRITestData
run_browser()                             # browse all sources
run_browser(; sources = OCMR_SOURCE)     # one source only
run_browser(; offline = true)            # skip the network

dismiss_terms_notice!()

Permanently suppress the data-source terms-of-use warning that is printed when using MRITestData is called. Only call this after you have reviewed the terms — the notice itself lists them, and MRITestData.terms_notice() reprints it at any time (terms_url(source) gives a single source's URL).

The setting is stored in LocalPreferences.toml and persists across Julia sessions. Re-enable the notice with enable_terms_notice!.

enable_terms_notice!()

Re-enable the data-source terms-of-use warning printed on using MRITestData. Reverts a previous dismiss_terms_notice! call.

set_chunk_size!(n::Int)

Persistently set the number of parallel byte-range chunks used during download. Also updates MRITestData.PARALLEL_CHUNKS for the current session. Set to 1 to disable parallel chunking.

get_chunk_size() -> Int

Return the number of parallel download chunks (see MRITestData.PARALLEL_CHUNKS). Reads the persistent preference; defaults to 4 if not set.

set_min_file_size!(n::Int)

Persistently set the minimum file size (bytes) threshold for parallel chunking. Also updates MRITestData.PARALLEL_MIN_BYTES for the current session.

get_min_file_size() -> Int

Return the minimum file size in bytes below which parallel chunking is skipped (see MRITestData.PARALLEL_MIN_BYTES). Defaults to 8_388_608 (8 MiB).

set_refresh_period!(days::Int)

Persistently set how many days a cached dataset index is kept before it is re-fetched from upstream. Also updates MRITestData.INDEX_TTL_DAYS for the current session.

get_refresh_period() -> Int

Return the dataset-index TTL in days (see MRITestData.INDEX_TTL_DAYS). Defaults to 30.

set_synapse_token!(token::AbstractString)

Persistently store a Synapse Personal Access Token used to download the Synapse-hosted sources, CMRXRECON2024 and CMRXRECON300. The token is saved in LocalPreferences.toml and survives across sessions. It is read by download_dataset for both CMRxRecon sources (the SYNAPSE_AUTH_TOKEN environment variable takes precedence if set).

CMRxRecon-300 is CC-BY and only needs a free Synapse account. CMRxRecon2024 additionally requires that the account has completed the CMRxRecon2024 challenge registration; otherwise the token lacks permission to download its data fragments. See the package README for registration instructions.

get_synapse_token() -> String

Return the Synapse Personal Access Token used for CMRXRECON2024 and CMRXRECON300 downloads. The SYNAPSE_AUTH_TOKEN environment variable takes precedence; otherwise the value persisted by set_synapse_token! is returned, or "" if none is set.

set_fastmri_urls!(text::AbstractString)

Parse the confirmation email from fastmri.med.nyu.edu (or the curl-command block within it) and persistently store all signed download URLs in LocalPreferences.toml.

text must contain one or more lines of the form:

curl -C - "https://fastmri-dataset.s3.amazonaws.com/..." --output filename.tar.xz

All matching URLs and their output filenames are extracted and stored as a filename => url mapping. The Expires Unix timestamp (the same across all URLs in one email) is extracted from any URL and stored separately; fastmri_url_expires converts it to a DateTime.

Call this once after receiving the access email — credentials last 90 days. Re-run after requesting a new set of links at https://fastmri.med.nyu.edu.

get_fastmri_url(filename) -> String

Return the stored signed URL for the fastMRI archive filename (e.g. "knee_singlecoil_train.tar.xz"). Errors with instructions if the URL is missing or the credentials have expired. Use set_fastmri_urls! to store new URLs.

fastmri_url_expires() -> Union{DateTime, Nothing}

Return the expiry DateTime (UTC) of the stored fastMRI signed URLs, or nothing if no URLs have been stored yet. Use set_fastmri_urls! to register new URLs.

MRITestData.PARALLEL_CHUNKS[]

Number of parallel byte-range chunks used when the server supports Accept-Ranges: bytes. Defaults to 4 (empirically optimal for OCMR S3). Set to 1 to disable parallel chunking.

MRITestData.PARALLEL_MIN_BYTES[]

Minimum file size in bytes below which parallel chunking is skipped and a plain single-connection download is used. Defaults to 8 MiB.