brimfile 1.0.0__tar.gz

brimfile-1.0.0/.github/workflows/docs.yml

@@ -0,0 +1,54 @@
+name: docs_pages
+
+# build the documentation whenever there are new commits on main
+on:
+  push:
+    branches:
+      - main
+    # Alternative: only build for tags.
+    # tags:
+    #   - '*'
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@v5
+        with:
+          python-version: '3.13'
+
+      # ADJUST THIS: install all dependencies (including pdoc)
+      - run: pip install numpy 
+      - run: pip install "zarr>=3"
+      - run: pip install -e .
+      - run: pip install pdoc
+      # ADJUST THIS: build your documentation into docs/.
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - run: pdoc src/brimfile  -o docs
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

brimfile-1.0.0/.gitignore

@@ -0,0 +1,4 @@
+.venv/
+.DS_Store
+src/brimfile/__pycache__/*
+dist/*

brimfile-1.0.0/LICENSE.toml

@@ -0,0 +1,165 @@
+                   GNU LESSER GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+
+  This version of the GNU Lesser General Public License incorporates
+the terms and conditions of version 3 of the GNU General Public
+License, supplemented by the additional permissions listed below.
+
+  0. Additional Definitions.
+
+  As used herein, "this License" refers to version 3 of the GNU Lesser
+General Public License, and the "GNU GPL" refers to version 3 of the GNU
+General Public License.
+
+  "The Library" refers to a covered work governed by this License,
+other than an Application or a Combined Work as defined below.
+
+  An "Application" is any work that makes use of an interface provided
+by the Library, but which is not otherwise based on the Library.
+Defining a subclass of a class defined by the Library is deemed a mode
+of using an interface provided by the Library.
+
+  A "Combined Work" is a work produced by combining or linking an
+Application with the Library.  The particular version of the Library
+with which the Combined Work was made is also called the "Linked
+Version".
+
+  The "Minimal Corresponding Source" for a Combined Work means the
+Corresponding Source for the Combined Work, excluding any source code
+for portions of the Combined Work that, considered in isolation, are
+based on the Application, and not on the Linked Version.
+
+  The "Corresponding Application Code" for a Combined Work means the
+object code and/or source code for the Application, including any data
+and utility programs needed for reproducing the Combined Work from the
+Application, but excluding the System Libraries of the Combined Work.
+
+  1. Exception to Section 3 of the GNU GPL.
+
+  You may convey a covered work under sections 3 and 4 of this License
+without being bound by section 3 of the GNU GPL.
+
+  2. Conveying Modified Versions.
+
+  If you modify a copy of the Library, and, in your modifications, a
+facility refers to a function or data to be supplied by an Application
+that uses the facility (other than as an argument passed when the
+facility is invoked), then you may convey a copy of the modified
+version:
+
+   a) under this License, provided that you make a good faith effort to
+   ensure that, in the event an Application does not supply the
+   function or data, the facility still operates, and performs
+   whatever part of its purpose remains meaningful, or
+
+   b) under the GNU GPL, with none of the additional permissions of
+   this License applicable to that copy.
+
+  3. Object Code Incorporating Material from Library Header Files.
+
+  The object code form of an Application may incorporate material from
+a header file that is part of the Library.  You may convey such object
+code under terms of your choice, provided that, if the incorporated
+material is not limited to numerical parameters, data structure
+layouts and accessors, or small macros, inline functions and templates
+(ten or fewer lines in length), you do both of the following:
+
+   a) Give prominent notice with each copy of the object code that the
+   Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the object code with a copy of the GNU GPL and this license
+   document.
+
+  4. Combined Works.
+
+  You may convey a Combined Work under terms of your choice that,
+taken together, effectively do not restrict modification of the
+portions of the Library contained in the Combined Work and reverse
+engineering for debugging such modifications, if you also do each of
+the following:
+
+   a) Give prominent notice with each copy of the Combined Work that
+   the Library is used in it and that the Library and its use are
+   covered by this License.
+
+   b) Accompany the Combined Work with a copy of the GNU GPL and this license
+   document.
+
+   c) For a Combined Work that displays copyright notices during
+   execution, include the copyright notice for the Library among
+   these notices, as well as a reference directing the user to the
+   copies of the GNU GPL and this license document.
+
+   d) Do one of the following:
+
+       0) Convey the Minimal Corresponding Source under the terms of this
+       License, and the Corresponding Application Code in a form
+       suitable for, and under terms that permit, the user to
+       recombine or relink the Application with a modified version of
+       the Linked Version to produce a modified Combined Work, in the
+       manner specified by section 6 of the GNU GPL for conveying
+       Corresponding Source.
+
+       1) Use a suitable shared library mechanism for linking with the
+       Library.  A suitable mechanism is one that (a) uses at run time
+       a copy of the Library already present on the user's computer
+       system, and (b) will operate properly with a modified version
+       of the Library that is interface-compatible with the Linked
+       Version.
+
+   e) Provide Installation Information, but only if you would otherwise
+   be required to provide such information under section 6 of the
+   GNU GPL, and only to the extent that such information is
+   necessary to install and execute a modified version of the
+   Combined Work produced by recombining or relinking the
+   Application with a modified version of the Linked Version. (If
+   you use option 4d0, the Installation Information must accompany
+   the Minimal Corresponding Source and Corresponding Application
+   Code. If you use option 4d1, you must provide the Installation
+   Information in the manner specified by section 6 of the GNU GPL
+   for conveying Corresponding Source.)
+
+  5. Combined Libraries.
+
+  You may place library facilities that are a work based on the
+Library side by side in a single library together with other library
+facilities that are not Applications and are not covered by this
+License, and convey such a combined library under terms of your
+choice, if you do both of the following:
+
+   a) Accompany the combined library with a copy of the same work based
+   on the Library, uncombined with any other library facilities,
+   conveyed under the terms of this License.
+
+   b) Give prominent notice with the combined library that part of it
+   is a work based on the Library, and explaining where to find the
+   accompanying uncombined form of the same work.
+
+  6. Revised Versions of the GNU Lesser General Public License.
+
+  The Free Software Foundation may publish revised and/or new versions
+of the GNU Lesser General Public License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns.
+
+  Each version is given a distinguishing version number. If the
+Library as you received it specifies that a certain numbered version
+of the GNU Lesser General Public License "or any later version"
+applies to it, you have the option of following the terms and
+conditions either of that published version or of any later version
+published by the Free Software Foundation. If the Library as you
+received it does not specify a version number of the GNU Lesser
+General Public License, you may choose any version of the GNU Lesser
+General Public License ever published by the Free Software Foundation.
+
+  If the Library as you received it specifies that a proxy can decide
+whether future versions of the GNU Lesser General Public License shall
+apply, that proxy's public statement of acceptance of any version is
+permanent authorization for you to choose that version for the
+Library.

brimfile-1.0.0/PKG-INFO

@@ -0,0 +1,43 @@
+Metadata-Version: 2.4
+Name: brimfile
+Version: 1.0.0
+Summary: A package to read and write to the brim file format, containing spectral data and metadata from Brillouin microscopy
+Project-URL: Documentation, https://prevedel-lab.github.io/brimfile/
+Project-URL: Repository, https://github.com/prevedel-lab/brimfile
+Project-URL: Issues, https://github.com/prevedel-lab/brimfile/issues
+Author-email: Carlo Bevilacqua <carlo.bevilacqua@embl.de>, Sebastian Hambura <sebastian.hambura@embl.de>
+License-Expression: LGPL-3.0-or-later
+License-File: LICENSE.toml
+Keywords: Brillouin microscopy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: File Formats
+Classifier: Topic :: Scientific/Engineering
+Requires-Dist: numpy
+Requires-Dist: zarr>=3.0
+Provides-Extra: export-tiff
+Requires-Dist: tifffile; extra == 'export-tiff'
+Provides-Extra: remote-store
+Requires-Dist: fsspec; extra == 'remote-store'
+Description-Content-Type: text/markdown
+
+# brimfile package
+
+## What is it?
+
+*brimfile* is a package to read and write to brim (**Br**illouin **im**aging) files, containing spectral data and metadata from Brillouin microscopy.
+
+The detailed specs of the brim file format can be found [here](https://github.com/prevedel-lab/Brillouin-standard-file/blob/main/docs/brim_file_specs.md).
+
+## Where to get it
+
+*brimfile* can be installed from PyPI using `pip`:
+```bash
+pip install brimfile
+```
+
+## How to use it
+
+The documentation of the package can be found [here](https://prevedel-lab.github.io/brimfile/).

brimfile-1.0.0/README.md

@@ -0,0 +1,18 @@
+# brimfile package
+
+## What is it?
+
+*brimfile* is a package to read and write to brim (**Br**illouin **im**aging) files, containing spectral data and metadata from Brillouin microscopy.
+
+The detailed specs of the brim file format can be found [here](https://github.com/prevedel-lab/Brillouin-standard-file/blob/main/docs/brim_file_specs.md).
+
+## Where to get it
+
+*brimfile* can be installed from PyPI using `pip`:
+```bash
+pip install brimfile
+```
+
+## How to use it
+
+The documentation of the package can be found [here](https://prevedel-lab.github.io/brimfile/).

brimfile-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling >= 1.26"]
+build-backend = "hatchling.build"
+[tool.hatch.version]
+path = "src/brimfile/__init__.py"
+
+[project]
+name = "brimfile"
+dynamic = ["version"]
+authors = [
+    {name = "Carlo Bevilacqua", email = "carlo.bevilacqua@embl.de"},
+    {name = "Sebastian Hambura", email = "sebastian.hambura@embl.de"},
+]
+description = "A package to read and write to the brim file format, containing spectral data and metadata from Brillouin microscopy"
+readme = "README.md"
+license = "LGPL-3.0-or-later"
+license-files = ["LICEN[CS]E*"]
+classifiers = [
+	"Development Status :: 4 - Beta",
+	"Intended Audience :: Science/Research",
+	"Intended Audience :: Developers",
+	"Topic :: File Formats",
+	"Topic :: Scientific/Engineering",
+  "Programming Language :: Python :: 3"
+	
+]
+keywords = ["Brillouin microscopy"]
+dependencies = [
+  "numpy",
+  "zarr >= 3.0"
+]
+
+[project.optional-dependencies]
+remote-store = ["fsspec"]
+export-tiff = ["tifffile"]
+
+[project.urls]
+Documentation = "https://prevedel-lab.github.io/brimfile/"
+Repository = "https://github.com/prevedel-lab/brimfile"
+Issues = "https://github.com/prevedel-lab/brimfile/issues"

brimfile-1.0.0/src/brimfile/__init__.py

@@ -0,0 +1,275 @@
+"""
+## What is brimfile?
+
+*brimfile* is a Python library to read from and write to brim files,
+which contain both the spectra and analysed data for Brillouin imaging.
+More information about the brim file format can be found [here](https://github.com/prevedel-lab/Brillouin-standard-file).
+
+Briefly, a brim file can contain multiple data groups,
+typically corresponding to imaging of the same sample at different timepoints/conditions.
+Each data group contains the spectral data as well as the metadata and
+the results of the analysis on the spectral data (which can be many in case multiple reconstruction pipelines are performed).
+
+The structure of the *brimfile* library reflects the structure of the brim file and the user can access the data,
+metadata and analysis results through their corresponding classes.
+
+- [File](#file): represents a brim file, which can be opened or created.
+- [Data](#data): represents a data group in the brim file, which contains the spectral data and metadata.
+- [Metadata](#metadata): represents the metadata associated to a data group (or to the whole file).
+- [AnalysysResults](#analysisresults): represents the results of the analysis of the spectral data.
+
+
+## Install brimfile
+
+Simply run:
+
+```bash
+pip install brimfile
+```
+
+If you also need the support for exporting the analyzed data to OME-Tiff files,
+you can install the optional dependencies with:
+
+```bash
+pip install brimfile[export-tiff]
+```
+
+
+## Use brimfile
+
+### File
+
+The main class is `brimfile.file.File`, which represents a brim file.
+It can be used to create a new brim file (`brimfile.file.File.create`) or to open an existing one (`brimfile.file.File.__init__`).
+
+```Python
+import brimfile as brim
+
+filename = 'path/to/your/file.brim.zip'
+
+# Open an existing brim file
+f = brim.File(filename)
+
+# or create a new one
+f = brim.File.create(filename, store_type='zip')
+```
+
+### Data
+
+You can then get a `brimfile.data.Data` object representing the data group in the brim file
+either by getting an existing one (`brimfile.file.File.get_data`) or creating a new one (`brimfile.file.File.create_data_group`).
+
+```Python
+# Get the first data group in the file
+data = f.get_data()
+
+# or create a new one
+data = f.create_data_group(PSD, freq_GHz, (dz, dy, dx), name='my_data_group')
+```
+
+You can get the spectrum corresponding to a pixel in the image by calling the `brimfile.data.Data.get_spectrum_in_image` method:
+```Python
+PSD, frequency, PSD_units, frequency_units = data.get_spectrum_in_image((pz,py,px))    
+```
+
+### Metadata
+
+You can then get a `brimfile.metadata.Metadata` object by simply calling the `brimfile.data.Data.get_metadata` method on a previously retrieved `Data` object.
+The returned Metadata object contains all the metadata associated with the file and the data group.
+```Python
+metadata = data.get_metadata()
+```
+The list of available metadata is defined [here](https://github.com/prevedel-lab/Brillouin-standard-file/blob/main/docs/brim_file_metadata.md).
+
+New metadata can be added to the current data group (or to the whole file) by calling the `brimfile.metadata.Metadata.add` method.
+```Python
+import datetime
+
+Attr = Metadata.Item
+datetime_now = datetime.now().isoformat()
+temp = Attr(22.0, 'C')
+    
+metadata.add(Metadata.Type.Experiment, {'Datetime':datetime_now, 'Temperature':temp},local=True)
+```
+A single metadata item can be retrieved by indexing the `Metadata` object, which takes a string in the format 'group.object', e.g. 'Experiment.Datetime'.
+```Python
+datetime = metadata['Experiment.Datetime']
+```
+A dictionary containing all metadata can be retrieved by calling the `brimfile.metadata.Metadata.all_to_dict` method.
+```Python
+metadata.all_to_dict()
+```
+
+### AnalysisResults
+
+The results of the analysis can be accessed through the `brimfile.data.Data.AnalysisResults` object, obtained by calling the `brimfile.data.Data.get_analysis_results` method on a previously retrieved `Data` object:
+``` Python
+analysis_results = data.get_analysis_results()
+```
+or create a new one by calling the `brimfile.data.Data.create_analysis_results_group_raw`:
+``` Python
+analysis_results = data.create_analysis_results_group_raw(shift, width,
+    name='my_analysis_results')
+```
+
+`AnalysisResults` also exposes a method to retrieve the images of the analysis results (`brimfile.data.Data.AnalysisResults.get_image`):
+
+``` Python
+ar_cls = Data.AnalysisResults
+img, px_size = analysis_results.get_image(ar_cls.Quantity.Shift, ar_cls.PeakType.average)
+```
+
+## List the contents of a brim file
+
+The *brimfile* library provides methods to list the contents of a brim file.
+
+To list all the data groups in a brim file, you can use the `brimfile.file.File.list_data_groups` method.
+
+Once you have a `Data` object, you can list the analysis results in it by calling the `brimfile.data.Data.list_AnalysisResults` method.
+
+Once you have an `AnalysisResults` object, you can determine:
+- if the Stokes and/or anti-Stokes peaks are present by calling the `brimfile.data.Data.AnalysisResults.list_existing_peak_types` method;
+- the available quantities (e.g. shift, linewidth, etc...) in the analysis results by calling the `brimfile.data.Data.AnalysisResults.list_existing_quantities` method.
+
+## Example code
+
+Here is a simple example which creates a brim file with a data group and some metadata and then reads it back.
+
+We first write a function to generate some dummy data:
+
+``` Python
+import numpy as np
+
+def generate_data():
+    def lorentzian(x, x0, w):
+        return 1/(1+((x-x0)/(w/2))**2)
+    Nx, Ny, Nz = (7, 5, 3) # Number of points in x,y,z
+    dx, dy, dz = (0.4, 0.5, 2) # Stepsizes (in um)
+    n_points = Nx*Ny*Nz  # total number of points
+
+    width_GHz = 0.4
+    width_GHz_arr = np.full(n_points, width_GHz)
+    shift_GHz_arr = np.empty(n_points)
+    freq_GHz = np.linspace(6, 9, 151)  # 151 frequency points
+    PSD = np.empty((Nz, Ny, Nx, len(freq_GHz)))
+    for i in range(Nz):
+        for j in range(Ny):
+            for k in range(Nx):
+                index = k + Nx*j + Ny*Nx*i
+                #let's increase the shift linearly to have a readout 
+                shift_GHz = freq_GHz[0] + (freq_GHz[-1]-freq_GHz[0]) * index/n_points
+                spectrum = lorentzian(freq_GHz, shift_GHz, width_GHz)
+                shift_GHz_arr[index] = shift_GHz 
+                PSD[i, j, k,:] = spectrum
+    
+    return PSD, freq_GHz, (dz,dy,dx), shift_GHz_arr, width_GHz_arr
+```
+
+Now we can use this function to create a brim file with a data group and some metadata:
+
+``` Python
+    from brimfile import File, Data, Metadata
+    from datetime import datetime
+
+    filename = 'path/to/your/file.brim.zip' 
+
+    f = File.create(filename, store_type='auto')
+
+    PSD, freq_GHz, (dz,dy,dx), shift_GHz, width_GHz = generate_data()
+    
+    d0 = f.create_data_group(PSD, freq_GHz, (dz,dy,dx), name='test1')
+    
+    # Create the metadata
+    Attr = Metadata.Item
+    datetime_now = datetime.now().isoformat()
+    temp = Attr(22.0, 'C')
+    md = d0.get_metadata()
+    
+    md.add(Metadata.Type.Experiment, {'Datetime':datetime_now, 'Temperature':temp})
+    md.add(Metadata.Type.Optics, {'Wavelength':Attr(660, 'nm')})
+    # Add some metadata to the local data group   
+    temp = Attr(37.0, 'C')
+    md.add(Metadata.Type.Experiment, {'Temperature':temp}, local=True)
+
+    # create the analysis results
+    ar = d0.create_analysis_results_group_raw(({'shift':shift_GHz, 'shift_units': 'GHz',
+                                             'width': width_GHz, 'width_units': 'Hz'},),
+                                             ({'shift':shift_GHz, 'shift_units': 'GHz',
+                                             'width': width_GHz, 'width_units': 'Hz'},),
+                                             name = 'test1_analysis')
+    f.close()
+```
+and we can read it back:
+``` Python
+    from brimfile import File, Data, Metadata
+
+    filename = 'path/to/your/file.brim.zip' 
+
+    f = File(filename)
+
+    # check if the file is read only
+    f.is_read_only()
+
+    #list all the data groups in the file
+    data_groups = f.list_data_groups(retrieve_custom_name=True)
+
+    # get the first data group in the file
+    d = f.get_data()
+    # get the name of the data group
+    d.get_name()
+
+    # get the number of parameters which the spectra depend on
+    n_pars = d.get_num_parameters()
+
+    # get the metadata 
+    md = d.get_metadata()
+    all_metadata = md.all_to_dict()
+    # the list of metadata is defined here https://github.com/prevedel-lab/Brillouin-standard-file/blob/main/docs/brim_file_metadata.md
+    time = md['Experiment.Datetime']
+    time.value
+    time.units
+    temp = md['Experiment.Temperature']
+    md_dict = md.to_dict(Metadata.Type.Experiment)
+
+
+    #get the list of analysis results in the data group
+    ar_list = d.list_AnalysisResults(retrieve_custom_name=True)
+    # get the first analysis results in the data group
+    ar = d.get_analysis_results()
+    # get the name of the analysis results
+    ar.get_name()
+    # list the existing peak types and quantities in the analysis results
+    pt = ar.list_existing_peak_types()
+    qt = ar.list_existing_quantities()
+    # get the image of the shift quantity for the average of the Stokes and anti-Stokes peaks
+    img, px_size = ar.get_image(Data.AnalysisResults.Quantity.Shift, Data.AnalysisResults.PeakType.average)
+    # get the units of the shift quantity
+    u = ar.get_units(Data.AnalysisResults.Quantity.Shift)
+
+    # get a quantity at a specific pixel (coord) in the image
+    coord = (1,3,4)
+    qt_at_px = ar.get_quantity_at_pixel(coord, Data.AnalysisResults.Quantity.Shift, Data.AnalysisResults.PeakType.average)
+    assert img[coord]==qt_at_px
+    
+    # get the spectrum in the image at a specific pixel (coord)
+    PSD, frequency, PSD_units, frequency_units = d.get_spectrum_in_image(coord)    
+
+    f.close()
+```
+
+## Export the data to a different format
+
+### OME-TIFF
+
+You can export a specific quantity in the analyzed data to OME-TIFF files using the `brimfile.data.Data.AnalysisResults.save_image_to_OMETiff` method on an instance `ar` of the `AnalysisResults` class.
+``` Python
+ar_cls = Data.AnalysisResults
+ar.save_image_to_OMETiff(ar_cls.Quantity.Shift, ar_cls.PeakType.average, filename='path/to/your/exported_tiff' )
+```
+"""
+
+__version__ = "1.0.0"
+
+from .file import File
+from .data import Data
+from .metadata import Metadata

brimfile-1.0.0/src/brimfile/constants.py

@@ -0,0 +1,28 @@
+__docformat__ = "google"
+
+reserved_attr_names = ('Units', 'Name')
+
+
+class brim_obj_names:
+    """
+    This class contains the names of the objects in the brim file.
+    """
+    Brillouin_base_path = 'Brillouin_data/'
+
+    class data:
+        """
+        This class contains the names of the data groups in the brim file.
+        """
+        base_group = 'Data'
+        PSD = 'PSD'
+        frequency = 'Frequency'
+        parameters = 'Parameters'
+        analysis_results = 'Analysis'
+        spatial_map = 'Scanning/Spatial_map'
+        cartesian_visualisation = 'Scanning/Cartesian_visualisation'
+
+    class metadata:
+        """
+        This class contains the names of the metadata groups in the brim file.
+        """
+        base_group = 'Metadata'