msr-reader 0.2.1.dev0__tar.gz → 0.3.1__tar.gz

msr_reader-0.3.1/.gitignore

@@ -0,0 +1,6 @@
+*.egg-info
+dist
+.idea
+*__pycache__
+msr-test-files
+.DS_Store

{msr_reader-0.2.1.dev0 → msr_reader-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: msr-reader
-Version: 0.2.1.dev0
+Version: 0.3.1
 Summary: Pure Python reader for MSR/OBF (Imspector) image data
 Project-URL: Homepage, https://github.com/hoerlteam/msr-reader
 Project-URL: Bug Tracker, https://github.com/hoerlteam/msr-reader/issues
@@ -12,6 +12,8 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.7
 Requires-Dist: numpy
+Provides-Extra: xarray
+Requires-Dist: xarray; extra == 'xarray'
 Description-Content-Type: text/markdown
 
 # msr
@@ -41,6 +43,29 @@ with OBFFile('file_path.msr') as f:
     idx = 0
     img = f.read_stack(idx) # read stack with index idx into numpy array
 
+    # multi-channel (or confocal + STED) data is acquired into separate stacks by Imspector.
+    # stack_groups groups stacks with same series number in the stack name and identical geometry.
+    # every stack belongs to exactly one group, unmatched stacks
+    # (e.g. line profiles, rescue_info maps) form single-member groups.
+    groups = f.stack_groups # list of StackGroup
+    img = f.read_stack_group(0) # read all "channels", stacked along a new first axis: e.g. (C, Z, Y, X)
+
+    # xarray integration (optional dependency: pip install msr-reader[xarray]):
+    # stacks as xarray.DataArray with labelled dims and physical coordinates
+    # (SI units of the file: meters for spatial axes, seconds for time)
+    da = f.read_stack_xr(idx) # dims e.g. ('z', 'y', 'x'), coords in meters
+    dag = f.read_stack_group_xr(0) # one DataArray with a leading 'channel' dim, labelled with channel names
+
+    # stacks without names (sometimes found in old files) can be grouped by geometry alone:
+    # with OBFFile('file_path.msr', group_unnamed_stacks=True) as f:
+
+    # Lightbox files use hierarchical stack names ('Overview 1/Image 1/14:03:01/STAR RED'):
+    # for .obf files, grouping by the path up to the last component (the
+    # acquisition) and the last component (the channel name) is enabled by
+    # default. for .msr files (Imspector), enable it explicitly:
+    # with OBFFile('file_path.msr', group_hierarchical_stacks=True) as f:
+    # pass group_hierarchical_stacks=False to disable it for .obf files.
+
     # metadata
     stack_shapes = f.shapes # list of stack shapes, including stack and dimension names
     pixel_sizes = f.pixel_sizes # like shapes, but with pixel sizes (unit: meters)

msr_reader-0.3.1/README.md

@@ -0,0 +1,67 @@
+# msr
+
+Pure Python and cross-platform reader for MSR/OBF image files as created by Imspector.
+
+Implementation follows the description at: https://imspectordocs.readthedocs.io/en/latest/fileformat.html
+
+**WARNING:** Only tested on data from our own Abberior Expert Line STED microscope with a narrow range of Imspector versions.
+
+## Installation
+
+```
+pip install msr-reader
+```
+
+## Usage
+
+```python
+from msr_reader import OBFFile
+from xml.etree import ElementTree
+import ome_types
+
+with OBFFile('file_path.msr') as f:
+
+    # reading image data
+    idx = 0
+    img = f.read_stack(idx) # read stack with index idx into numpy array
+
+    # multi-channel (or confocal + STED) data is acquired into separate stacks by Imspector.
+    # stack_groups groups stacks with same series number in the stack name and identical geometry.
+    # every stack belongs to exactly one group, unmatched stacks
+    # (e.g. line profiles, rescue_info maps) form single-member groups.
+    groups = f.stack_groups # list of StackGroup
+    img = f.read_stack_group(0) # read all "channels", stacked along a new first axis: e.g. (C, Z, Y, X)
+
+    # xarray integration (optional dependency: pip install msr-reader[xarray]):
+    # stacks as xarray.DataArray with labelled dims and physical coordinates
+    # (SI units of the file: meters for spatial axes, seconds for time)
+    da = f.read_stack_xr(idx) # dims e.g. ('z', 'y', 'x'), coords in meters
+    dag = f.read_stack_group_xr(0) # one DataArray with a leading 'channel' dim, labelled with channel names
+
+    # stacks without names (sometimes found in old files) can be grouped by geometry alone:
+    # with OBFFile('file_path.msr', group_unnamed_stacks=True) as f:
+
+    # Lightbox files use hierarchical stack names ('Overview 1/Image 1/14:03:01/STAR RED'):
+    # for .obf files, grouping by the path up to the last component (the
+    # acquisition) and the last component (the channel name) is enabled by
+    # default. for .msr files (Imspector), enable it explicitly:
+    # with OBFFile('file_path.msr', group_hierarchical_stacks=True) as f:
+    # pass group_hierarchical_stacks=False to disable it for .obf files.
+
+    # metadata
+    stack_shapes = f.shapes # list of stack shapes, including stack and dimension names
+    pixel_sizes = f.pixel_sizes # like shapes, but with pixel sizes (unit: meters)
+
+    # imspector metadata as xml string
+    xml_imspector_metadata = f.get_imspector_xml_metadata(idx)
+    
+    # can be parsed with ElementTree, for example    
+    et = ElementTree.fromstring(xml_imspector_metadata)
+    # find, e.g. x pixel size in XML
+    et.find('doc/ExpControl/scan/range/x/psz').text
+
+    # OME-XML metadata as xml string
+    xml_ome_metadata = f.get_ome_xml_metadata()
+    # can be parsed with ome-types, for example
+    ome_meta = ome_types.from_xml(xml_ome_metadata)
+```

{msr_reader-0.2.1.dev0 → msr_reader-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "msr-reader"
-version = "0.2.1-dev"
+version = "0.3.1"
 authors = [
   { name="David Hörl", email="hoerldavid@gmail.com" },
 ]
@@ -19,6 +19,9 @@ classifiers = [
 ]
 dependencies = ["numpy"]
 
+[project.optional-dependencies]
+xarray = ["xarray"]
+
 [project.urls]
 "Homepage" = "https://github.com/hoerlteam/msr-reader"
 "Bug Tracker" = "https://github.com/hoerlteam/msr-reader/issues"

msr_reader-0.3.1/src/msr_reader/__init__.py

@@ -0,0 +1,2 @@
+from .obffile import OBFFile, OBFHeader, OBFStackHeader, OBFStackFooter, OBFSIFraction, OBFSIUnit, StackGroup, StackSizes
+from .xml_metadata import imspector_xml_to_dict