Metadata-Version: 2.1
Name: fw-file
Version: 3.2.2
Summary: Unified data-file interface
Home-page: https://gitlab.com/flywheel-io/tools/lib/fw-file
License: MIT
Keywords: Flywheel,parse,medical,file,metadata,extract,DICOM,RAW,MR,CT,PET,NIfTI,JPG,JPEG,PNG,Bruker,ParaVision,GE,PFile,Philips,PARREC,Siemens,PTD,EEG
Author: Flywheel
Author-email: support@flywheel.io
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: all
Provides-Extra: eeg
Provides-Extra: jpg
Provides-Extra: json
Provides-Extra: nifti
Provides-Extra: png
Requires-Dist: dicom-validator (>=0.3.5,<0.4.0)
Requires-Dist: dotty-dict (>=1.3.1,<2.0.0) ; extra == "all" or extra == "json"
Requires-Dist: edflib-python (>=1.0.8,<2.0.0) ; extra == "all" or extra == "eeg"
Requires-Dist: eeglabio (>=0,<1) ; extra == "all" or extra == "eeg"
Requires-Dist: fw-meta (>=4.0.0)
Requires-Dist: fw-utils (>=4.3.4)
Requires-Dist: mne[hdf5] (>=1.5.1,<2.0.0) ; extra == "all" or extra == "eeg"
Requires-Dist: natsort (>=8.0.0,<9.0.0)
Requires-Dist: nibabel (>=4.0.2) ; extra == "all" or extra == "nifti"
Requires-Dist: piexif (>=1.1.3,<2.0.0) ; extra == "all" or extra == "jpg" or extra == "png"
Requires-Dist: pillow (>=9) ; extra == "all" or extra == "jpg" or extra == "png"
Requires-Dist: pybv (>=0,<1) ; extra == "all" or extra == "eeg"
Requires-Dist: pydantic (>=2.4.2,<3.0.0)
Requires-Dist: pydantic-settings (>=2.0.3,<3.0.0)
Requires-Dist: pydicom (>=2.3.0,<3.0.0)
Requires-Dist: pypng (>=0,<1) ; extra == "all" or extra == "png"
Requires-Dist: python-dateutil (>=2.8.1,<3.0.0)
Requires-Dist: pyyaml (>=5.4.1)
Project-URL: Documentation, https://gitlab.com/flywheel-io/tools/lib/fw-file
Project-URL: Repository, https://gitlab.com/flywheel-io/tools/lib/fw-file
Description-Content-Type: text/markdown

# fw-file

Unified interface for reading medical file types, exposing parsed fields as dict
keys as well as attributes and for saving any modifications to disk or a buffer.

DICOM support - built on top of `pydicom` - is the primary goal of the library.
`fw-file` also provides helpers for parsing DICOMs containing non-standard tags
and utilities for organizing datasets and extracting metadata.

Additional file types supported:

- NIfTI1 and NIfTI2 (.nii.gz)
- Bruker ParaVision (subject/acqp/method)
- GE MR RAW / PFile (P_NNNNN_.7)
- Philips MR PAR/REC header (.par)
- Siemens MR RAW (.dat)
- Siemens MR Spectroscopy (.rda)
- Siemens PET RAW (.ptd)
- PNG (.png)
- JPEG/JPG (.jpeg/.jpg)

## Installation

To install the package with all the optional dependencies:

```bash
pip install "fw-file[all]"
```

Alternatively, add as a `poetry` dependency to your project:

```bash
poetry add fw-file --extras all
```

## Usage

### Opening

```python
from fw_file.dicom import DICOM
dcm = DICOM("dataset.dcm")  # also works with any readable file-like object
```

### Fields

**Attribute access** on DICOMs works similarly to that in `pydicom`:

```python
dcm.PatientAge == "060Y"
dcm.patientage == "060Y"   # attrs are case-insensitive
dcm.patient_age == "060Y"  # and snake_case compatible
```

**Key access** also returns values instead of `pydicom.DataElement`:

```python
dcm["PatientAge"] == "060Y"
dcm["patientage"] == "060Y"   # keys are case-insensitive too
dcm["patient_age"] == "060Y"  # and snake_case compatible
dcm["00101010"] == "060Y"
dcm["0010", "1010"] == "060Y"
dcm[0x00101010] == "060Y"
dcm[0x0010, 0x1010] == "060Y"
```

**Private tags** can be accessed as keys when including the creator:

```python
dcm["AGFA", "Zoom factor"] == 2
dcm["AGFA", "0019xx82"] == 2
```

**Assignment and deletion** works with attributes and keys alike:

```python
dcm.PatientAge = "065Y"
del dcm["PatientAge"]
```

### Metadata

Flywheel metadata can be extracted using the `get_meta()` method:

```python
from fw_file.dicom import DICOM
dcm = DICOM("dataset.dcm")
dcm.get_meta() == {
    "subject.label": "PatientID",
    "session.label": "StudyDescription",
    "session.uid": "1.2.3",  # StudyInstanceUID
    "acquisition.label": "SeriesDescription",
    "acquisition.uid": "4.5.6",  # SeriesInstanceUID
    # and much, much more...
}
```

### Saving

```python
dcm.save()              # save to the original location
dcm.save("edited.dcm")  # save to a given filepath
dcm.save(io.BytesIO())  # save to any writable object
```

### Collections and series

Handling multiple DICOM files together is a common use case, where the tags of
more than one file need to be inspected in tandem for QA/validation or even
modified for de-identification. `DICOMCollection` facilitates that and exposes
convenience methods to be loaded from a list of files, a directory or a zip
archive.

```python
from fw_file.dicom import DICOMCollection
coll_dcm = DICOMCollection("001.dcm", "002.dcm")  # from a list of files
coll_dir = DICOMCollection.from_dir(".")          # from a directory
coll_zip = DICOMCollection.from_zip("dicom.zip")  # from a zip archive
coll = DICOMCollection()  # or start from scratch
coll.append("001.dcm")    # and add files later
```

To interact with the underlying DICOMs:

```python
# access individual instances through list indexes
coll[0].SOPInstanceUID == "1.2.3"
# get tag value of all instances as a list, allowing different values
coll.bulk_get("SOPInstanceUID") == ["1.2.3", "1.2.4"]
# get a unique tag value, raising when encountering multiple values
coll.get("SeriesInstanceUID") == "1.2"
coll.get("SOPInstanceUID")  # raises ValueError
# set a tag value uniformly on all instances
coll.set("PatientAge", "060Y")
# delete a tag across all instances
coll.delete("PatientID")
```

Finally, a `DICOMCollection` can be saved in place, exported to a directory or
packed as a zip archive:

```python
coll.save()
coll.to_dir("/tmp/dicom")
coll.to_zip("/tmp/dicom.zip")
```

`DICOMSeries` is a subclass of `DICOMCollection`, intended to be used on files
that belong to the same DICOM series. The instances normally have the same
`SeriesInstanceUID` attribute and are uploaded together (zipped) into a Flywheel
acquisition. In addition to the collection methods, `DICOMSeries` can be used to
pack the instances into an appropriately named ZIP archive and extract Flywheel
metadata from multiple files while also validating the values, checking for any
discrepancies among the instances along the way.

```python
from fw_file.dicom import DICOMSeries
series = DICOMSeries("001.dcm", "002.dcm")
filepath, metadata = series.to_upload()
```

### DICOM Standard Editions

As the DICOM Standard is typically revised multiple times throughout the year,
`fw-file` provides the option to choose which edition is being utilized via
environment variables. The default is `"2023c"`, which utilizes the locally-saved
2023c edition. Additional options are `"current"` and any valid 5-character edition
(i.e. `"2022d"`). Specifying `"current"` will fetch the most recent edition at runtime.

```bash
FW_DCM_STANDARD_REV=current
FW_DCM_STANDARD_REV=2022d
```

### Private dictionary

In addition to the private tags included in
[`pydicom`](https://github.com/pydicom/pydicom/blob/v2.1.2/pydicom/_private_dict.py),
`fw-file` ships with an [extended dictionary](fw_file/dicom/dcmdict.py) to
make accessing even more private tags that much simpler.

The private dictionary can be further extended by creating a DCMTK-style
[data dict](https://github.com/DCMTK/dcmtk/blob/master/dcmdata/data/private.dic)
file and setting the
[`DCMDICTPATH`](https://support.dcmtk.org/docs/file_envvars.html)
environment variable to it's path.

### `DataElement` decoding

DICOMs are often saved with non-standard and/or corrupt data elements. To enable
loading these datasets, `fw-file` provides fixes for some common problems:

- Fix `VM=1` strings that contain `\` by replacing with `_` (default: enabled)
- Fix `VR` for known data elements encoded as explicit `UN` (default: enabled)
- Extend/improve handling of data elements with a `VR` mismatch (default: disabled)

These fixes can also be enabled/disabled via environment variables:

```bash
FW_DCM_REPLACE_UN_WITH_KNOWN_VR=false
FW_DCM_FIX_VM1_STRINGS=false
FW_DCM_FIX_VR_MISMATCH=true
```

To extract as much information from a DICOM as possible, `fw-file` can be run in
read-only mode. When enabled, invalid values are retained and the VR is set to OB.
As it is not safe to write the DICOM back in this state, saving is disabled. This
mode can be enabled via an environment variable. (default: disabled)

```bash
FW_DCM_READ_ONLY=true
```

Additionally, validation mode can be set via environment variables. Default is
1 (WARN), additional options are 2 (RAISE) and 0 (IGNORE).

```bash
FW_DCM_READING_VALIDATION_MODE=1
FW_DCM_WRITING_VALIDATION_MODE=1
```

## Development

Install the project using `poetry` and enable `pre-commit`:

```bash
poetry install --extras "all"
pre-commit install
```

## License

[![MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)

