PACFISH

In this repository we develop the photoacoustic converter for information sharing (PACFISH). It is a tool that enables the conversion of vendor-specific proprietary data formats into the IPASC data format, which is an HDF5 container that has a defined structure for the meta data that are given with the binary data. A list of meta data information was suggested by the International Photoacoustic Standardisation Consortium (IPASC) in early 2020. You can find this list using the following link:

https://www.ipasc.science/documents/20210916_IPASC_Format_V2.pdf

PACFISH serves three purposes: (1) it helps vendors to integrate the IPASC data format export into their standard software; (2) it assists scientists to read and write data in the consensus HDF5 format; and (3) it helps the PA community to create custom adapters that convert proprietary file formats into the consensus HDF5 format.

Please help IPASC by reporting any missing parameters, bugs, or issues. We are also looking forward to any contributions in form of adapters that can convert a priprietary format into the IPASC format. If you are a member of the research community, a photoacoustic vendor, or interested to contribute or in the project in general because of any other reasons, please contact the leadership team of the Data Acquisition and Management Theme of IPASC.

These are currently: Janek Gröhl, Lina Hacker, and Ben Cox.

Software Architecture

PACFISH is divided into the API, core, quality control, and iohandler modules. The API package (pacfish.api yellow module) can be used to facilitate the integration of conversion adapters to convert from arbitrary file formats into the IPASC data format. To create a conversion adapter, a Python representation of (1) the binary data, (2) the acquisition metadata dictionary, and (3) the device metadata dictionary need to be implemented.

The core classes (pacfish.core green module) represent the metadata and data structure in Python. Each metadatum is described with specific device tags defining the name, data type, necessity and SI unit (if applicable), and setting a value constraint. Basic metadata constraints have been implemented to avoid accidental typos within the values field (e.g. only positive numbers larger than zero are applicable for acquisition wavelengths). If the value is not within the constraints a TypeError is raised. Metadatum-specific functions enable easy addition of the values for the specific metadata field.

The quality control functionalities (pacfish.qualitycontrol blue module) ensure the correctness of the conversion into the IPASC format: a completeness checker tests that all metadata are being called and a consistency checker ensures that all metadata are within their constraints. An automatically-generated output report gives a human-readable summary of the quality control checks and ensures that the likelihood of conversion mistakes are minimized. For control of the Device Metadata, the detector and illuminator positions can be represented in a 3D coordinate system as visual control.

Finally, the I/O functionality (pacfish.iohandler red module) enables reading and writing of IPASC-formatted data files.

Examples and use cases

Please look in the examples folder for detailed and functional examples how to use the PACFISH API. We have examples for both Python and MATLAB.

Use case: using the tool to read and write HDF5 files

import pacfish as pf

# Loading data from the hard drive
pa_data = pf.load_data("path/to/hdf5file.hdf5")
numpy_array = pa_data.binary_time_series_data

# Writing of data to hard drive
pf.write_data("path/to/new/file.hdf5", pa_data)

Use case: Implement a conversion adapter

impot pacfish as pf

class DeviceSpecificAdapter(pf.BaseAdapter):

    def generate_binary_data(self) -> np.ndarray:
        # IMPLEMENTATION HERE
        pass

    def generate_device_meta_data(self) -> dict:
        # IMPLEMENTATION HERE
        pass

    def set_metadata_value(self, metadata_tag: MetaDatum) -> object:
        # IMPLEMENTATION HERE
        pass