wotann 0.5.80 → 0.5.83

package/skills/scientific/bids/references/metadata_fields.md

@@ -0,0 +1,365 @@
+# BIDS Metadata Fields Reference
+
+This reference lists the required and recommended JSON sidecar fields for each BIDS modality.
+
+**Legend:**
+- **R** = Required
+- **REC** = Recommended
+- **OPT** = Optional
+
+## Common MRI Fields (All MRI Modalities)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `MagneticFieldStrength` | REC | number | Field strength in Tesla |
+| `Manufacturer` | REC | string | Scanner manufacturer |
+| `ManufacturersModelName` | REC | string | Scanner model |
+| `DeviceSerialNumber` | REC | string | Scanner serial number |
+| `StationName` | REC | string | Scanner station name |
+| `SoftwareVersions` | REC | string | Scanner software version |
+| `InstitutionName` | REC | string | Name of institution |
+| `InstitutionAddress` | REC | string | Address of institution |
+| `InstitutionalDepartmentName` | REC | string | Department name |
+
+## Anatomical MRI (anat/)
+
+### T1w, T2w, FLAIR, T2star, PDw
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `RepetitionTime` | REC | number | TR in seconds |
+| `EchoTime` | REC | number | TE in seconds |
+| `InversionTime` | REC | number | TI in seconds (if applicable) |
+| `FlipAngle` | REC | number | Flip angle in degrees |
+| `SequenceName` | REC | string | Pulse sequence name |
+| `SequenceVariant` | REC | string | Variant of the sequence |
+| `ScanningSequence` | REC | string | General description |
+| `PulseSequenceType` | REC | string | Type of pulse sequence |
+| `NonlinearGradientCorrection` | REC | boolean | Whether applied |
+| `ParallelReductionFactorInPlane` | REC | number | iPAT/GRAPPA factor |
+| `ContrastBolusIngredient` | REC | string | Active contrast ingredient |
+
+### Quantitative MRI (T1map, T2map, etc.)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `RepetitionTimeExcitation` | R | number | Excitation TR in seconds |
+| `RepetitionTimePrepration` | R | number | Preparation TR in seconds |
+| `FlipAngle` | R | number/array | Flip angle(s) in degrees |
+| `MTState` | R | boolean | Magnetization transfer on/off |
+| `SpoilingState` | REC | boolean | Whether RF spoiling applied |
+| `SpoilingType` | REC | string | `RF`, `GRADIENT`, or `COMBINED` |
+| `SpoilingRFPhaseIncrement` | REC | number | Phase increment in degrees |
+
+## Functional MRI (func/)
+
+### BOLD
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `RepetitionTime` | R | number | TR in seconds (volume acquisition time) |
+| `TaskName` | R | string | Name of the task (must match `task-<label>`) |
+| `SliceTiming` | REC | array | Time each slice was acquired, in seconds |
+| `EchoTime` | REC | number | TE in seconds |
+| `FlipAngle` | REC | number | Flip angle in degrees |
+| `PhaseEncodingDirection` | REC | string | `i`, `i-`, `j`, `j-`, `k`, `k-` |
+| `EffectiveEchoSpacing` | REC | number | Effective echo spacing in seconds |
+| `TotalReadoutTime` | REC | number | Total readout time in seconds |
+| `MultibandAccelerationFactor` | REC | number | Multiband/SMS factor |
+| `NumberOfVolumesDiscardedByScanner` | REC | integer | Dummy scans removed |
+| `NumberOfVolumesDiscardedByUser` | REC | integer | Volumes removed post-hoc |
+| `TaskDescription` | REC | string | Longer description of the task |
+| `CogAtlasID` | REC | string | Cognitive Atlas ID for the task |
+| `CogPOID` | REC | string | Cognitive Paradigm Ontology ID |
+| `Instructions` | REC | string | Instructions given to participants |
+
+### Multi-echo BOLD
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `EchoTime` | R | number | TE for this echo (each echo in separate file) |
+| `EchoTime1`, `EchoTime2` | - | - | NOT used; use `echo-<index>` entity |
+
+### BOLD Timing Details
+
+**SliceTiming** - Array of times (in seconds) at which each slice was acquired relative to the start of volume acquisition. Length must equal the number of slices.
+
+Example for ascending sequential (3 slices, TR=2s):
+```json
+{"SliceTiming": [0.0, 0.667, 1.333]}
+```
+
+Example for interleaved (odd-first, 6 slices, TR=2s):
+```json
+{"SliceTiming": [0.0, 0.667, 1.333, 0.333, 1.0, 1.667]}
+```
+
+**PhaseEncodingDirection** values:
+- `i` / `i-` : along first image axis (typically left-right)
+- `j` / `j-` : along second image axis (typically anterior-posterior)
+- `k` / `k-` : along third image axis (typically inferior-superior)
+- The `-` suffix indicates the negative direction along that axis
+
+## Diffusion-Weighted Imaging (dwi/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `PhaseEncodingDirection` | R | string | Phase encoding direction |
+| `TotalReadoutTime` | R | number | Total readout time in seconds |
+| `EchoTime` | REC | number | TE in seconds |
+| `RepetitionTime` | REC | number | TR in seconds |
+| `FlipAngle` | REC | number | Flip angle in degrees |
+| `EffectiveEchoSpacing` | REC | number | Effective echo spacing in seconds |
+| `MultibandAccelerationFactor` | REC | number | SMS/multiband factor |
+| `SliceTiming` | REC | array | Slice timing |
+
+### DWI Gradient Files
+
+`.bvec` file (3 rows x N columns, N = number of volumes):
+```
+0 0.707 -0.707 0 0.577
+0 0.707 0.707 0 0.577
+0 0 0 1 0.577
+```
+
+`.bval` file (1 row x N columns):
+```
+0 1000 1000 1000 2000
+```
+
+- b=0 volumes have zero-vectors in `.bvec`
+- Gradient directions are in the image coordinate system
+- Values are space-separated (not tab-separated)
+- Number of columns must match number of volumes in the NIfTI
+
+## Fieldmaps (fmap/)
+
+### Case 1: Phase-difference map (`_phasediff`)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `EchoTime1` | R | number | TE of the first echo (shorter) |
+| `EchoTime2` | R | number | TE of the second echo (longer) |
+| `IntendedFor` | R | string/array | BIDS URI(s) of files to correct |
+| `B0FieldIdentifier` | REC | string | Identifier for this B0 field |
+
+### Case 2: Two phase maps (`_phase1`, `_phase2`)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `EchoTime` | R | number | TE for this phase image |
+| `IntendedFor` | R | string/array | Files to correct |
+
+### Case 3: Direct fieldmap (`_fieldmap`)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `Units` | R | string | Must be `Hz` or `rad/s` |
+| `IntendedFor` | R | string/array | Files to correct |
+
+### Case 4: "Pepolar" fieldmaps (`_epi`)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `PhaseEncodingDirection` | R | string | PE direction for this image |
+| `TotalReadoutTime` | R | number | Total readout time |
+| `IntendedFor` | R | string/array | Files to correct |
+| `B0FieldIdentifier` | REC | string | Identifier for this B0 field |
+| `B0FieldSource` | REC | string | Which B0 field to use |
+
+### IntendedFor Syntax
+
+**BIDS URI format** (recommended, v1.7+):
+```json
+{
+    "IntendedFor": [
+        "bids::sub-01/func/sub-01_task-rest_bold.nii.gz",
+        "bids::sub-01/dwi/sub-01_dwi.nii.gz"
+    ]
+}
+```
+
+**Relative path format** (legacy):
+```json
+{
+    "IntendedFor": [
+        "func/sub-01_task-rest_bold.nii.gz",
+        "dwi/sub-01_dwi.nii.gz"
+    ]
+}
+```
+
+**B0FieldIdentifier/B0FieldSource** (preferred in v1.9+):
+```json
+// In the fieldmap sidecar
+{"B0FieldIdentifier": "pepolar_fmap0"}
+
+// In the BOLD sidecar
+{"B0FieldSource": "pepolar_fmap0"}
+```
+
+## Perfusion Imaging (perf/)
+
+### ASL
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `ArterialSpinLabelingType` | R | string | `CASL`, `PCASL`, or `PASL` |
+| `PostLabelingDelay` | R | number/array | PLD in seconds |
+| `BackgroundSuppression` | R | boolean | Whether applied |
+| `MagneticFieldStrength` | R | number | In Tesla |
+| `M0Type` | R | string | `Separate`, `Included`, `Estimate`, `Absent` |
+| `RepetitionTimePreparation` | R | number | Time between ASL pulses |
+| `LabelingDuration` | R | number | Duration of labeling pulse |
+| `BackgroundSuppressionNumberPulses` | REC | integer | Number of suppression pulses |
+| `BackgroundSuppressionPulseTime` | REC | array | Timing of suppression pulses |
+| `VascularCrushing` | REC | boolean | Whether applied |
+| `LabelingOrientation` | REC | string | Orientation of labeling plane |
+| `LabelingDistance` | REC | number | Distance from isocenter (mm) |
+| `BolusCutOffFlag` | R (PASL) | boolean | Whether QUIPSS applied |
+| `BolusCutOffTimingSequence` | R (PASL) | string | QUIPSS sequence type |
+| `BolusCutOffDelayTime` | R (PASL) | number | QUIPSS delay time |
+
+### aslcontext.tsv
+
+Required file listing the order of volumes (label/control/m0scan):
+```
+volume_type
+control
+label
+control
+label
+m0scan
+```
+
+## EEG (eeg/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `TaskName` | R | string | Name of the task |
+| `SamplingFrequency` | R | number | In Hz |
+| `EEGReference` | R | string | Reference electrode(s) |
+| `PowerLineFrequency` | R | number | 50 or 60 Hz (or `n/a`) |
+| `SoftwareFilters` | R | object | Online filters applied |
+| `EEGPlacementScheme` | REC | string | e.g., `10-20`, `10-10` |
+| `CapManufacturer` | REC | string | Cap manufacturer |
+| `CapManufacturersModelName` | REC | string | Cap model |
+| `EEGChannelCount` | REC | integer | Number of EEG channels |
+| `EOGChannelCount` | REC | integer | Number of EOG channels |
+| `ECGChannelCount` | REC | integer | Number of ECG channels |
+| `EMGChannelCount` | REC | integer | Number of EMG channels |
+| `MiscChannelCount` | REC | integer | Number of misc channels |
+| `TriggerChannelCount` | REC | integer | Number of trigger channels |
+| `RecordingDuration` | REC | number | In seconds |
+| `RecordingType` | REC | string | `continuous`, `epoched`, `discontinuous` |
+
+### channels.tsv (EEG)
+
+| Column | Status | Description |
+|--------|--------|-------------|
+| `name` | R | Channel name |
+| `type` | R | `EEG`, `EOG`, `ECG`, `EMG`, `MISC`, `TRIG`, etc. |
+| `units` | R | `V`, `mV`, `uV` |
+| `sampling_frequency` | OPT | Per-channel if different |
+| `low_cutoff` | REC | High-pass filter frequency (Hz) |
+| `high_cutoff` | REC | Low-pass filter frequency (Hz) |
+| `notch` | REC | Notch filter frequency (Hz) |
+| `reference` | REC | Reference electrode name |
+| `status` | REC | `good` or `bad` |
+| `status_description` | OPT | Reason for bad status |
+
+### electrodes.tsv (EEG)
+
+| Column | Status | Description |
+|--------|--------|-------------|
+| `name` | R | Electrode name |
+| `x` | R | X coordinate |
+| `y` | R | Y coordinate |
+| `z` | R | Z coordinate |
+| `type` | OPT | Electrode type |
+| `material` | OPT | Electrode material |
+| `impedance` | OPT | Impedance in kOhm |
+
+## MEG (meg/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `TaskName` | R | string | Name of the task |
+| `SamplingFrequency` | R | number | In Hz |
+| `PowerLineFrequency` | R | number | 50 or 60 Hz |
+| `DewarPosition` | R | string | Position of the dewar |
+| `SoftwareFilters` | R | object | Online filters |
+| `DigitizedLandmarks` | R | boolean | Fiducials digitized |
+| `DigitizedHeadPoints` | R | boolean | Head shape digitized |
+| `MEGChannelCount` | REC | integer | Number of MEG channels |
+| `MEGREFChannelCount` | REC | integer | Reference channels |
+| `ContinuousHeadLocalization` | REC | boolean | HPI on |
+| `HeadCoilFrequency` | REC | array | HPI coil frequencies |
+| `InstitutionName` | REC | string | Institution name |
+
+## PET (pet/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `TracerName` | R | string | Name of the radiotracer |
+| `TracerRadionuclide` | R | string | e.g., `C11`, `F18`, `O15` |
+| `InjectedRadioactivity` | R | number | In MBq |
+| `InjectedRadioactivityUnits` | R | string | Must be `MBq` |
+| `InjectedMass` | R | number | Mass of tracer injected |
+| `InjectedMassUnits` | R | string | e.g., `ug` |
+| `ModeOfAdministration` | R | string | `bolus`, `infusion`, `bolus-infusion` |
+| `TimeZero` | R | string | Time of injection (HH:MM:SS) |
+| `ScanStart` | R | number | Start time relative to TimeZero |
+| `InjectionStart` | R | number | Injection time relative to TimeZero |
+| `FrameTimesStart` | R | array | Frame start times in seconds |
+| `FrameDuration` | R | array | Frame durations in seconds |
+| `Units` | R | string | Unit of voxel values (e.g., `Bq/mL`) |
+| `TracerRadLex` | REC | string | RadLex ID for tracer |
+| `BodyWeight` | REC | number | In kg |
+| `BodyPart` | REC | string | Imaged body part |
+| `AttenuationCorrection` | REC | string | Method description |
+| `ReconMethodName` | REC | string | Reconstruction method |
+| `ReconMethodParameterLabels` | REC | array | Parameter names |
+| `ReconMethodParameterValues` | REC | array | Parameter values |
+| `ReconFilterType` | REC | string | Post-recon filter type |
+| `ReconFilterSize` | REC | number | Filter FWHM in mm |
+
+## Microscopy (micr/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `Manufacturer` | R | string | Microscope manufacturer |
+| `ManufacturersModelName` | R | string | Microscope model |
+| `PixelSize` | R | array | [X, Y] or [X, Y, Z] in micrometers |
+| `PixelSizeUnits` | R | string | `um` (micrometers) |
+| `Magnification` | REC | number | Objective magnification |
+| `SampleEnvironment` | R | string | `in vivo`, `ex vivo`, `in vitro` |
+| `SampleFixation` | REC | string | Fixation method |
+| `SampleStaining` | REC | string | Staining protocol |
+| `SliceThickness` | REC | number | In micrometers |
+| `TissueDeformationScaling` | REC | number | Scaling factor |
+
+## NIRS (nirs/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `TaskName` | R | string | Name of the task |
+| `SamplingFrequency` | R | number | In Hz |
+| `NIRSSourceOptodeCount` | R | integer | Number of sources |
+| `NIRSDetectorOptodeCount` | R | integer | Number of detectors |
+| `ACCELChannelCount` | REC | integer | Accelerometer channels |
+| `NIRSPlacementScheme` | REC | string | e.g., `10-20` |
+
+## Motion (motion/)
+
+| Field | Status | Type | Description |
+|-------|--------|------|-------------|
+| `TaskName` | R | string | Name of the task |
+| `SamplingFrequency` | R | number | In Hz |
+| `TrackingSystemName` | R | string | Name of tracking system |
+| `ACCELChannelCount` | REC | integer | Accelerometer channels |
+| `GYROChannelCount` | REC | integer | Gyroscope channels |
+| `MAGNChannelCount` | REC | integer | Magnetometer channels |
+| `RotationOrder` | REC | string | e.g., `XYZ` |
+| `RotationRule` | REC | string | `left-hand` or `right-hand` |
+| `SpatialAxes` | REC | string | e.g., `ALS` |

package/skills/scientific/bids/scripts/update_schema.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python3
+"""Update BIDS schema JSON and BEPs list from upstream sources.
+
+Downloads:
+  - bids_schema.json from bids-specification ReadTheDocs (stable release)
+  - beps.yml from bids-standard/bids-website (current BEP listing)
+
+Usage:
+    python scripts/update_schema.py
+
+    # Fetch schema for a specific spec version or PR preview:
+    python scripts/update_schema.py --schema-url https://bids-specification.readthedocs.io/en/v1.11.0/schema.json
+
+    # Fetch a BEP-specific schema from bids-standard/bids-schema:
+    python scripts/update_schema.py --schema-url https://raw.githubusercontent.com/bids-standard/bids-schema/main/BEPs/BEP032/schema.json
+
+No external dependencies beyond the Python standard library.
+"""
+
+import argparse
+import json
+import urllib.request
+from pathlib import Path
+
+REFERENCES_DIR = Path(__file__).resolve().parent.parent / "references"
+
+SCHEMA_URL = "https://bids-specification.readthedocs.io/en/stable/schema.json"
+BEPS_URL = "https://raw.githubusercontent.com/bids-standard/bids-website/main/data/beps/beps.yml"
+
+
+def fetch(url):
+    """Fetch URL content as bytes."""
+    print(f"Fetching {url} ...")
+    req = urllib.request.Request(url, headers={"User-Agent": "bids-skill-updater/1.0"})
+    with urllib.request.urlopen(req) as resp:
+        return resp.read()
+
+
+def update_schema(url):
+    """Download schema.json and report version info."""
+    data = fetch(url)
+    output = REFERENCES_DIR / "bids_schema.json"
+
+    # Validate it's proper JSON and extract version
+    d = json.loads(data)
+    # Re-serialize with consistent formatting
+    with open(output, "w") as f:
+        json.dump(d, f, indent=2)
+        f.write("\n")
+
+    sv = d.get("schema_version", "?")
+    bv = d.get("bids_version", "?")
+    print(f"  -> {output.name}: schema {sv} / BIDS {bv}")
+
+
+def update_beps():
+    """Download beps.yml."""
+    data = fetch(BEPS_URL)
+    output = REFERENCES_DIR / "beps.yml"
+    output.write_bytes(data)
+
+    # Count entries
+    count = data.count(b"\n-   number:")
+    print(f"  -> {output.name}: {count} BEPs")
+
+
+def main():
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument(
+        "--schema-url",
+        default=SCHEMA_URL,
+        help=f"URL for schema.json (default: {SCHEMA_URL})",
+    )
+    parser.add_argument(
+        "--skip-beps",
+        action="store_true",
+        help="Skip fetching beps.yml",
+    )
+    args = parser.parse_args()
+
+    update_schema(args.schema_url)
+    if not args.skip_beps:
+        update_beps()
+
+    print("Done.")
+
+
+if __name__ == "__main__":
+    main()