brukerapi 0.2.6__tar.gz → 0.4.0__tar.gz

brukerapi-0.4.0/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: brukerapi
+Version: 0.4.0
+Summary: Bruker API
+Author-email: Tomas Psorn <tomaspsorn@isibrno.cz>, Jiri Vitous <vitous@isibrno.cz>
+Maintainer-email: Jiri Vitous <vitous@isibrno.cz>
+License: MIT
+Project-URL: Homepage, https://github.com/isi-nmr/brukerapi-python
+Project-URL: Download, https://github.com/isi-nmr/brukerapi-python/releases/latest
+Requires-Python: >=3.8
+Description-Content-Type: text/x-rst
+License-File: LICENSE
+Requires-Dist: numpy<2; python_version < "3.9"
+Requires-Dist: numpy>=1.26.0; python_version >= "3.9"
+Requires-Dist: pyyaml
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: zenodo_get; extra == "dev"
+Requires-Dist: ruff==0.16.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+brukerapi-python
+======================
+
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3831320.svg
+   :target: https://doi.org/10.5281/zenodo.3831320
+
+.. image:: https://github.com/isi-nmr/brukerapi-python/workflows/CI/badge.svg
+   :target: https://doi.org/10.5281/zenodo.3831320
+
+.. image:: https://readthedocs.org/projects/bruker-api/badge/?version=latest
+    :target: https://bruker-api.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+
+A Python package providing I/O interface for Bruker data sets.
+
+tl;dr
+========
+
+Install using pip:
+
+.. code-block:: shell
+
+    pip install brukerapi
+
+Load any **data set**:
+
+.. code-block:: python
+
+    from brukerapi.dataset import Dataset
+    dataset = Dataset('{path}/2dseq')    # also supports fid, fid_proc.64, traj, and rawdata.jobN
+    dataset.data                         # access data array
+    dataset.get_value('VisuCoreSize')    # get a parameter value
+
+Raw acquisitions and k-space
+==============================
+
+Raw Bruker acquisitions have format-dependent historical ``.data`` semantics.
+For explicit code, use the representation that matches the task:
+
+.. code-block:: python
+
+    fid = Dataset('{path}/fid')
+    fid.raw                 # decoded (sample, shot, receiver) acquisitions
+    fid.kspace              # ordered FID k-space
+
+    job = Dataset('{path}/rawdata.job0')
+    job.raw                 # decoded (sample, shot, receiver) acquisitions
+    job.kspace              # ordered Cartesian PV360 k-space, when metadata proves the layout
+    job.to_kspace(bart=True)  # optional 16-axis BART layout
+
+``Dataset.data`` remains backward compatible: FIDs expose their historical
+ordered k-space view, whereas PV360 ``rawdata.jobN`` exposes its historical
+decoded stream and emits a ``FutureWarning``. ``.kspace`` is not a
+reconstruction API; EPI and non-Cartesian jobs require acquisition-specific
+handling.
+
+Frame-group metadata
+====================
+
+For 2dseq data, ``frame_group_values`` aligns values named by
+``VisuGroupDepVals`` to the corresponding array axes. Returned arrays use
+singleton dimensions where needed and therefore broadcast directly against
+``dataset.data``:
+
+.. code-block:: python
+
+    echoes = dataset.frame_group_values['VisuAcqEchoTime']
+    b_matrices = dataset.frame_group_values['VisuAcqDiffusionBMatrix']
+
+``metadata`` provides normalized, grouped access to parsed subject, study,
+series, equipment, and acquisition fields:
+
+.. code-block:: python
+
+    dataset.metadata['visu_study']['uid']
+    dataset.metadata['visu_acq']['sequence_name']
+    dataset.metadata['subject']['id']
+
+Load an entire **study**:
+
+.. code-block:: python
+
+    from brukerapi.folders import Study
+    study = Study('{path_to_study_folder}')
+    dataset = study.get_dataset(exp_id='1', proc_id='1')
+
+    dataset.data                         # Study loads datasets by default
+
+Load a parametric file:
+
+.. code-block:: python
+
+   from brukerapi.jcampdx import JCAMPDX
+
+   parameters = JCAMPDX('path_to_scan/method')
+   
+   TR = parameters.params["PVM_RepetitionTime"].value
+   TR = parameters.get_value("PVM_RepetitionTime")
+
+
+
+
+
+Features
+========
+
+* **I/O** interface for **fid** data sets
+* **I/O** interface for **2dseq** data sets
+* **I/O** interface for **rawdata** data sets
+* **Random access** for **fid** and **2dseq** data sets
+* **Split** operation implemented over **2dseq** data sets
+* **Filter** operation implemented over Bruker **folders** (allowing you to work with a subset of your study only)
+* ParaVision 5.1, 6.0.1, 7.0.0, and 360 metadata and binary-layout support
+* Metadata-based fallback inference for custom Cartesian, EPI, radial/UTE, spiral, ZTE, CSI, and spectroscopy sequences
+
+Examples
+========
+
+* How to `read <examples/read_fid.ipynb>`_ a Bruker fid, 2dseq, or rawdata file
+* How to `split slice packages <examples/split_sp_demo.ipynb>`_ of a 2dseq data set
+* How to `split FG_ECHO <examples/split_fg_echo_demo.ipynb>`_ of a 2dseq data set
+* How to `split FG_ISA <examples/examples/split_fg_isa_demo.ipynb>`_ of a 2dseq data set
+
+Documentation
+==============
+
+Online `documentation <https://bruker-api.readthedocs.io/en/latest/>`_ of the API is available at Read The Docs.
+
+
+Install
+=======
+Using pip:
+
+.. code-block:: shell
+
+    pip install brukerapi
+
+From source:
+
+.. code-block:: shell
+
+    git clone https://github.com/isi-nmr/brukerapi-python.git
+    cd brukerapi-python
+    python -m pip install -e .[dev]
+
+Testing
+========
+To ensure reliability, every commit to this repository is tested against the following, publicly available
+data sets:
+
+* `BrukerAPI test data set (Bruker ParaVision v5.1) <https://doi.org/10.5281/zenodo.3899268>`_
+* `BrukerAPI test data set (Bruker ParaVision v6.0.1) <https://doi.org/10.5281/zenodo.3894651>`_
+* BrukerAPI test data set for ParaVision v7.0.0 (Zenodo DOI collection ``10.5281/zenodo.4522220``)
+* `PV360 standard data <https://github.com/cecilyen/PV360_StdData>`_
+
+The corpus download is opt-in for local runs:
+
+.. code-block:: shell
+
+    python -m pytest test --download_test_data
+
+Without that flag, pytest uses any corpus already present under ``test/test_data`` and
+skips unavailable collections.
+
+File format reference
+=====================
+
+`Bruker ParaVision Raw Data Format
+<https://github.com/gdevenyi/brkraw-legacy/blob/main/FILE_FORMAT.md>`_ is the source of truth
+for file-format parsing, binary layouts, dataset typing, and metadata-driven acquisition
+scheme inference in this project.
+
+Compatibility
+=============
+
+Tested releases are ParaVision 5.1, 6.0.1, 7.0.0, and PV360 3.x. Supported
+primary binaries are ``fid``, ``fid_proc.64``, ``2dseq``, ``traj``,
+``rawdata.jobN``, and ``rawdata.Navigator``. Known ``fid.spiral``,
+``fid.navFid``, and ``fid.orig`` files are exposed as auxiliary subdatasets of
+their parent ``fid``; they are not accepted as standalone primary datasets.
+TopSpin/NMR ``ser`` is intentionally unsupported.
+
+Known pulse-program names use dedicated layouts. For custom sequences the
+reader also infers common acquisition families from metadata; callers can pass
+``scheme_id=`` when inference is ambiguous. Rawdata is returned as complex
+ordered samples, not as reconstructed k-space. See the compatibility page in
+the documentation for behavior and current reconstruction limitations.

brukerapi-0.4.0/README.rst

@@ -0,0 +1,188 @@
+brukerapi-python
+======================
+
+.. image:: https://zenodo.org/badge/DOI/10.5281/zenodo.3831320.svg
+   :target: https://doi.org/10.5281/zenodo.3831320
+
+.. image:: https://github.com/isi-nmr/brukerapi-python/workflows/CI/badge.svg
+   :target: https://doi.org/10.5281/zenodo.3831320
+
+.. image:: https://readthedocs.org/projects/bruker-api/badge/?version=latest
+    :target: https://bruker-api.readthedocs.io/en/latest/?badge=latest
+    :alt: Documentation Status
+
+
+A Python package providing I/O interface for Bruker data sets.
+
+tl;dr
+========
+
+Install using pip:
+
+.. code-block:: shell
+
+    pip install brukerapi
+
+Load any **data set**:
+
+.. code-block:: python
+
+    from brukerapi.dataset import Dataset
+    dataset = Dataset('{path}/2dseq')    # also supports fid, fid_proc.64, traj, and rawdata.jobN
+    dataset.data                         # access data array
+    dataset.get_value('VisuCoreSize')    # get a parameter value
+
+Raw acquisitions and k-space
+==============================
+
+Raw Bruker acquisitions have format-dependent historical ``.data`` semantics.
+For explicit code, use the representation that matches the task:
+
+.. code-block:: python
+
+    fid = Dataset('{path}/fid')
+    fid.raw                 # decoded (sample, shot, receiver) acquisitions
+    fid.kspace              # ordered FID k-space
+
+    job = Dataset('{path}/rawdata.job0')
+    job.raw                 # decoded (sample, shot, receiver) acquisitions
+    job.kspace              # ordered Cartesian PV360 k-space, when metadata proves the layout
+    job.to_kspace(bart=True)  # optional 16-axis BART layout
+
+``Dataset.data`` remains backward compatible: FIDs expose their historical
+ordered k-space view, whereas PV360 ``rawdata.jobN`` exposes its historical
+decoded stream and emits a ``FutureWarning``. ``.kspace`` is not a
+reconstruction API; EPI and non-Cartesian jobs require acquisition-specific
+handling.
+
+Frame-group metadata
+====================
+
+For 2dseq data, ``frame_group_values`` aligns values named by
+``VisuGroupDepVals`` to the corresponding array axes. Returned arrays use
+singleton dimensions where needed and therefore broadcast directly against
+``dataset.data``:
+
+.. code-block:: python
+
+    echoes = dataset.frame_group_values['VisuAcqEchoTime']
+    b_matrices = dataset.frame_group_values['VisuAcqDiffusionBMatrix']
+
+``metadata`` provides normalized, grouped access to parsed subject, study,
+series, equipment, and acquisition fields:
+
+.. code-block:: python
+
+    dataset.metadata['visu_study']['uid']
+    dataset.metadata['visu_acq']['sequence_name']
+    dataset.metadata['subject']['id']
+
+Load an entire **study**:
+
+.. code-block:: python
+
+    from brukerapi.folders import Study
+    study = Study('{path_to_study_folder}')
+    dataset = study.get_dataset(exp_id='1', proc_id='1')
+
+    dataset.data                         # Study loads datasets by default
+
+Load a parametric file:
+
+.. code-block:: python
+
+   from brukerapi.jcampdx import JCAMPDX
+
+   parameters = JCAMPDX('path_to_scan/method')
+   
+   TR = parameters.params["PVM_RepetitionTime"].value
+   TR = parameters.get_value("PVM_RepetitionTime")
+
+
+
+
+
+Features
+========
+
+* **I/O** interface for **fid** data sets
+* **I/O** interface for **2dseq** data sets
+* **I/O** interface for **rawdata** data sets
+* **Random access** for **fid** and **2dseq** data sets
+* **Split** operation implemented over **2dseq** data sets
+* **Filter** operation implemented over Bruker **folders** (allowing you to work with a subset of your study only)
+* ParaVision 5.1, 6.0.1, 7.0.0, and 360 metadata and binary-layout support
+* Metadata-based fallback inference for custom Cartesian, EPI, radial/UTE, spiral, ZTE, CSI, and spectroscopy sequences
+
+Examples
+========
+
+* How to `read <examples/read_fid.ipynb>`_ a Bruker fid, 2dseq, or rawdata file
+* How to `split slice packages <examples/split_sp_demo.ipynb>`_ of a 2dseq data set
+* How to `split FG_ECHO <examples/split_fg_echo_demo.ipynb>`_ of a 2dseq data set
+* How to `split FG_ISA <examples/examples/split_fg_isa_demo.ipynb>`_ of a 2dseq data set
+
+Documentation
+==============
+
+Online `documentation <https://bruker-api.readthedocs.io/en/latest/>`_ of the API is available at Read The Docs.
+
+
+Install
+=======
+Using pip:
+
+.. code-block:: shell
+
+    pip install brukerapi
+
+From source:
+
+.. code-block:: shell
+
+    git clone https://github.com/isi-nmr/brukerapi-python.git
+    cd brukerapi-python
+    python -m pip install -e .[dev]
+
+Testing
+========
+To ensure reliability, every commit to this repository is tested against the following, publicly available
+data sets:
+
+* `BrukerAPI test data set (Bruker ParaVision v5.1) <https://doi.org/10.5281/zenodo.3899268>`_
+* `BrukerAPI test data set (Bruker ParaVision v6.0.1) <https://doi.org/10.5281/zenodo.3894651>`_
+* BrukerAPI test data set for ParaVision v7.0.0 (Zenodo DOI collection ``10.5281/zenodo.4522220``)
+* `PV360 standard data <https://github.com/cecilyen/PV360_StdData>`_
+
+The corpus download is opt-in for local runs:
+
+.. code-block:: shell
+
+    python -m pytest test --download_test_data
+
+Without that flag, pytest uses any corpus already present under ``test/test_data`` and
+skips unavailable collections.
+
+File format reference
+=====================
+
+`Bruker ParaVision Raw Data Format
+<https://github.com/gdevenyi/brkraw-legacy/blob/main/FILE_FORMAT.md>`_ is the source of truth
+for file-format parsing, binary layouts, dataset typing, and metadata-driven acquisition
+scheme inference in this project.
+
+Compatibility
+=============
+
+Tested releases are ParaVision 5.1, 6.0.1, 7.0.0, and PV360 3.x. Supported
+primary binaries are ``fid``, ``fid_proc.64``, ``2dseq``, ``traj``,
+``rawdata.jobN``, and ``rawdata.Navigator``. Known ``fid.spiral``,
+``fid.navFid``, and ``fid.orig`` files are exposed as auxiliary subdatasets of
+their parent ``fid``; they are not accepted as standalone primary datasets.
+TopSpin/NMR ``ser`` is intentionally unsupported.
+
+Known pulse-program names use dedicated layouts. For custom sequences the
+reader also infers common acquisition families from metadata; callers can pass
+``scheme_id=`` when inference is ambiguous. Rawdata is returned as complex
+ordered samples, not as reconstructed k-space. See the compatibility page in
+the documentation for behavior and current reconstruction limitations.

{brukerapi-0.2.6 → brukerapi-0.4.0}/brukerapi/cli.py

@@ -141,7 +141,7 @@ def report(args):
     elif output is None:
         Dataset(input, add_parameters=["subject"]).report(props=args.props, verbose=args.verbose)
     # dataset to folder, or dataset to file
-    elif output.is_dir():
+    else:
         Dataset(input, add_parameters=["subject"]).report(path=output, props=args.props, verbose=args.verbose)
 
 

{brukerapi-0.2.6 → brukerapi-0.4.0}/brukerapi/config/properties_2dseq_core.json

@@ -61,6 +61,14 @@
           ["#VisuCoreWordType",["_8BIT_UNSGN_INT"]],
           ["#VisuCoreByteOrder",["bigEndian"]]
         ]
+    },
+    {
+        "cmd": "np.dtype({'_32BIT_SGN_INT':'int32','_16BIT_SGN_INT':'int16','_32BIT_FLOAT':'float32','_8BIT_UNSGN_INT':'uint8'}[#RECO_wordtype]).newbyteorder('<' if #RECO_byte_order=='littleEndian' else '>')",
+        "conditions": ["#RECO_wordtype in ['_32BIT_SGN_INT','_16BIT_SGN_INT','_32BIT_FLOAT','_8BIT_UNSGN_INT']", "#RECO_byte_order in ['littleEndian','bigEndian']"]
+    },
+    {
+        "cmd": "np.dtype({'ip_int':'int32','ip_short':'int16','ip_float':'float32'}[#DATTYPE]).newbyteorder('<')",
+        "conditions": ["#DATTYPE in ['ip_int','ip_short','ip_float']"]
     }
   ],
   "shape_frames": [
@@ -108,12 +116,24 @@
       {
         "cmd": "#VisuCoreSize.tuple",
         "conditions": []
+      },
+      {
+        "cmd": "#RECO_size.tuple",
+        "conditions": []
+      },
+      {
+        "cmd": "tuple(size for size in (int(#IM_SIX), int(#IM_SIY), int(#IM_SIZ)) if size > 1)",
+        "conditions": []
       }
   ],
   "encoded_dim": [
       {
         "cmd": "len(#VisuCoreSize.tuple)",
         "conditions": []
+      },
+      {
+        "cmd": "len(@shape_block)",
+        "conditions": []
       }
   ],
   "shape_storage":[
@@ -143,12 +163,20 @@
     {
       "cmd": "#VisuCoreDataSlope.array",
       "conditions": []
+    },
+    {
+      "cmd": "#RECO_map_slope.array",
+      "conditions": []
     }
   ],
   "offset": [
     {
       "cmd": "#VisuCoreDataOffs.array",
       "conditions": []
+    },
+    {
+      "cmd": "#RECO_map_offset.array",
+      "conditions": []
     }
   ],
   "dim_type": [
@@ -165,8 +193,8 @@
       "conditions": ["@is_single_slice==False"]
     },
     {
-      "cmd": "#VisuCoreDimDesc.list",
+      "cmd": "#VisuCoreDimDesc.list + ['frame']",
       "conditions": ["@is_single_slice==False"]
     }
   ]
-}
+}

{brukerapi-0.2.6 → brukerapi-0.4.0}/brukerapi/config/properties_2dseq_custom.json

@@ -130,6 +130,18 @@
         "#VisuCorePosition.size[0]==1",
         "#VisuCoreDim==2"]
     },
+    {
+      "cmd": "np.array([#VisuCoreExtent[0] / #VisuCoreSize[0], #VisuCoreExtent[1] / #VisuCoreSize[1], np.linalg.norm(#VisuCorePosition[1,:] - #VisuCorePosition[0,:])])",
+      "conditions": [
+        "#VisuCorePosition.size[0]>1",
+        "#VisuCoreDim==2"]
+    },
+    {
+      "cmd": "np.array([#VisuCoreExtent[0] / #VisuCoreSize[0], #VisuCoreExtent[1] / #VisuCoreSize[1], #VisuCoreFrameThickness])",
+      "conditions": [
+        "#VisuCorePosition.size[0]==1",
+        "#VisuCoreDim==2"]
+    },
     {
       "cmd": "np.array([#VisuCoreExtent[0] / #VisuCoreSize[0], #VisuCoreExtent[1] / #VisuCoreSize[1], #VisuCoreExtent[2] / #VisuCoreSize[2]])",
       "conditions": [
@@ -253,13 +265,13 @@
       {
         "cmd": "datetime.datetime.strptime(#VisuStudyDate[1:-1], '%X %d %b %Y')",
         "conditions": [
-          "#VisuVersion==1"
+          "'T' not in #VisuStudyDate"
         ]
       },
       {
         "cmd": "datetime.datetime.strptime(#VisuStudyDate[1:-1], '%Y-%m-%dT%X,%f%z')",
         "conditions": [
-          "#VisuVersion==3"
+          "'T' in #VisuStudyDate"
         ]
       }
   ],
@@ -274,4 +286,4 @@
       "comment": "default value"
     }
   ]
-}
+}