xnatbidscli 2.0.0__py3-none-any.whl

xnatbidscli/__init__.py

@@ -0,0 +1,6 @@
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("xnatbidscli")
+except PackageNotFoundError:
+    __version__ = "0.0.0.dev0"

xnatbidscli/archive.py

@@ -0,0 +1,67 @@
+import shutil
+import tarfile
+from pathlib import Path
+
+STATUS_COMPLETE = "COMPLETE"
+STATUS_SKIPPED = "SKIPPED"
+STATUS_FAILURE = "FAILURE"
+STATUS_NONEXISTENT = "NONEXISTENT"
+
+OK_STATUSES = {STATUS_COMPLETE, STATUS_SKIPPED}
+
+
+def archive_path(
+    data_root: Path, project: str, subject: str, experiment: str
+) -> Path:
+    return (
+        data_root
+        / "archive"
+        / f"PROJECT-{project}_SUBJECT-{subject}_EXPERIMENT-{experiment}.tar.gz"
+    )
+
+
+def archive_experiment(
+    data_root: Path, project: str, subject: str, experiment: str
+) -> tuple[str, str | None]:
+    """Tar+gzip data_root/PROJECT/SUBJECT/EXPERIMENT into data_root/archive/.
+
+    Returns (status, detail). Existing archives are left untouched and reported
+    as SKIPPED; the tarball is written to a .tmp sibling and renamed into place
+    only on success so an interrupted run never leaves a partial file behind.
+    """
+    src = data_root / project / subject / experiment
+    if not src.is_dir():
+        return STATUS_NONEXISTENT, f"source directory not found: {src}"
+
+    dest = archive_path(data_root, project, subject, experiment)
+    if dest.exists():
+        return STATUS_SKIPPED, f"archive already exists: {dest}"
+
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + ".tmp")
+    try:
+        with tarfile.open(tmp, "w:gz") as tar:
+            tar.add(src, arcname=experiment)
+        tmp.replace(dest)
+    except Exception as e:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except Exception:
+                pass
+        return STATUS_FAILURE, f"error creating archive: {e}"
+    return STATUS_COMPLETE, None
+
+
+def delete_experiment_dir(
+    data_root: Path, project: str, subject: str, experiment: str
+) -> None:
+    """Delete the EXPERIMENT dir and prune empty SUBJECT/PROJECT parents."""
+    exp_dir = data_root / project / subject / experiment
+    if exp_dir.exists():
+        shutil.rmtree(exp_dir, ignore_errors=True)
+    for parent in (data_root / project / subject, data_root / project):
+        try:
+            parent.rmdir()
+        except OSError:
+            return

xnatbidscli/assets/mriconvert_qc.json

@@ -0,0 +1,82 @@
+{
+    "Dcm2BidsConfigPath": {
+        "Description": "Absolute path to the dcm2bids config JSON used to convert this project. Set via mriconvert's -c/--config; preserved from a prior run if omitted (e.g. under -m/--maps). LastModified is the timestamp (Python logging's default asctime format) of the last time -c/--config was passed and Value was updated.",
+        "Value": "",
+        "LastModified": ""
+    },
+    "PhysioParent": {
+        "Description": "Absolute path to the parent directory of all raw physio recordings for this project, stored in a flat directory structure. Set via mriconvert's -y/--physio; preserved from a prior run if omitted.",
+        "Value": ""
+    },
+    "filename": {
+        "Description": "Path to the NIfTI file relative to the root inside the PROJECT (BIDS dataset) directory, with no leading periods or slashes."
+    },
+    "acq_time": {
+        "Description": "Acquisition time of the scan, taken from the AcquisitionTime field of the file's accompanying JSON sidecar. Empty when the field or sidecar is absent."
+    },
+    "series_number": {
+        "Description": "DICOM study series number, taken from the SeriesNumber field of the file's accompanying JSON sidecar. Empty when the field or sidecar is absent."
+    },
+    "dimensions": {
+        "Description": "Image array shape as read by nibabel, given as x-joined dimension sizes and always including the 4th (time) dimension even when it is 1 (e.g. 256x256x170x1)."
+    },
+    "size_bytes": {
+        "Description": "Size of the NIfTI file on disk, in bytes."
+    },
+    "participant_id": {
+        "Description": "BIDS participant identifier (sub-<label>) parsed from the filename."
+    },
+    "session_id": {
+        "Description": "BIDS session identifier (ses-<label>) parsed from the filename."
+    },
+    "datatype": {
+        "Description": "BIDS datatype, taken from the name of the file's parent directory (e.g. anat, func, dwi, fmap)."
+    },
+    "suffix": {
+        "Description": "BIDS suffix, the portion of the basename after the last underscore and before the extension. Never empty."
+    },
+    "bids_name": {
+        "Description": "The portion of the file basename between the sub-<label>_ses-<label>_ prefix and the .nii.gz extension."
+    },
+    "rename": {
+        "Description": "Free-text field for an end-user to record a corrected bids_name when the file needs renaming. Empty by default."
+    },
+    "physio": {
+        "Description": "Free-text field for an end-user to record the basename (with extension) of a raw physio recording found under PhysioParent that was acquired alongside this scan. Consumed by xnatbidscli physioconvert to convert and place that recording directly, using this row's participant_id/session_id/datatype for placement and its bids_name/rename for naming. Empty by default; never auto-populated by mriconvert."
+    },
+    "recommend_for_use": {
+        "Description": "Whether the file is recommended for use. Empty until reviewed by an end-user.",
+        "Levels": {
+            "TRUE": "The file is recommended for use.",
+            "FALSE": "The file is not recommended for use."
+        }
+    },
+    "complete": {
+        "Description": "Whether the file was acquired at its complete, as-intended length. Empty until reviewed by an end-user.",
+        "Levels": {
+            "TRUE": "The acquisition is complete.",
+            "FALSE": "The acquisition is incomplete."
+        }
+    },
+    "usable": {
+        "Description": "Whether the file is usable at all. Empty until reviewed by an end-user.",
+        "Levels": {
+            "TRUE": "The file is usable.",
+            "FALSE": "The file is not usable."
+        }
+    },
+    "qc_rating": {
+        "Description": "Acquisition quality-control rating. Empty until reviewed by an end-user.",
+        "Levels": {
+            "PASS": "The acquisition passed quality control.",
+            "FAIL": "The acquisition failed quality control.",
+            "UNCERTAIN": "The quality-control outcome is uncertain."
+        }
+    },
+    "rating_reason": {
+        "Description": "Free-text reason for the qc_rating, open to any string of any length. Empty by default."
+    },
+    "qc_notes": {
+        "Description": "Free-text notes about the quality control not captured by other fields, open to any string of any length. Empty by default."
+    }
+}

xnatbidscli/assets/physioconvert_qc.json

@@ -0,0 +1,33 @@
+{
+    "PhysioParent": {
+        "Description": "Absolute path to the parent directory of all raw physio recordings for this project, as resolved from mriconvert_qc.json at the time of this run.",
+        "Value": ""
+    },
+    "physio": {
+        "Description": "The raw physio basename (mriconvert_qc.tsv's physio column value) used to produce this row's output, as of the last conversion. Primary key of this table."
+    },
+    "status": {
+        "Description": "Per-association processing outcome, regenerated every run.",
+        "Levels": {
+            "CONVERTED": "phys2bids read the raw file and its BIDS _physio.tsv.gz/.json were written next to the paired NIfTI.",
+            "NOT_PHYSIO": "Matched a supported extension but could not be loaded as physiological data.",
+            "READER_MISSING": "The optional reader package phys2bids needs for this format is not installed.",
+            "CONVERT_ERROR": "phys2bids raised while converting, produced no .tsv.gz output, or its destination was already occupied by a different association.",
+            "SOURCE_MISSING": "PhysioParent was unset/not a directory, the named basename was not found under it, or the mriconvert_qc.tsv row is missing participant_id/datatype.",
+            "COLLISION": "This physio basename is referenced by more than one mriconvert_qc.tsv row; none of them were converted until resolved.",
+            "SKIPPED": "The association's _physio.tsv.gz already existed at its expected destination and was a valid (non-corrupt) GZIP file, so conversion was not attempted."
+        }
+    },
+    "n_channels": {
+        "Description": "Number of channels phys2bids reported for the recording (its ch_amount, which includes the leading time channel). Blank for associations that were not loaded as physio."
+    },
+    "sampling_frequencies": {
+        "Description": "Unique channel sampling frequencies in hertz, ascending, comma-separated (e.g. 1000,500). A single value for the common single-frequency case. Aligned position-by-position with sample_count and duration_seconds."
+    },
+    "sample_count": {
+        "Description": "Number of samples per sampling frequency, comma-separated and aligned with sampling_frequencies (the longest channel recorded at each frequency). Blank for associations that were not loaded as physio."
+    },
+    "duration_seconds": {
+        "Description": "Acquisition duration in seconds at 0.001 s precision, computed as sample_count / sampling_frequency, comma-separated and aligned with sampling_frequencies. Blank for associations that were not loaded as physio."
+    }
+}