Examples¶

These short examples demonstrate how you can use spexread and to read your files into xarray.Datasets.

These Dataset objects enable easy analysis and aggregation of data from an SPE file.

In [1]:

Copied!





from spexread import read_spe_file
from spexread.data_models import SPEType
from pathlib import Path
import matplotlib.pyplot as plt
from spexread import read_spe_file
from spexread.data_models import SPEType
from pathlib import Path
import matplotlib.pyplot as plt

Read a file as a dataset¶

read_spe_file reads a file as a Dataset unless you specify the keyword argument as_dataset = False, in which case a list of DataArrays will be returned.

The metadata from the file willbe stored in the attrs attribute, as a deeply nested dictionary.

A more convenient way to work with this metadata, is to read it into the SPEType pydantic model, which let's you traverse it by attribute access.

In a notebook, you can easily inspect the contents of a Dataset as shown below.

In [2]:

Copied!

data = read_spe_file("../2025 April 15 11_02_25.spe")
meta_data = SPEType.model_validate(data.attrs)
data
data = read_spe_file("../2025 April 15 11_02_25.spe")
meta_data = SPEType.model_validate(data.attrs)
data

Out[2]:

<xarray.Dataset> Size: 3MB
Dimensions:     (frame: 5, y: 256, x: 1024)
Coordinates:
  * frame       (frame) int64 40B 0 1 2 3 4
  * y           (y) int64 2kB 0 1 2 3 4 5 6 7 ... 249 250 251 252 253 254 255
  * x           (x) int64 8kB 0 1 2 3 4 5 6 ... 1018 1019 1020 1021 1022 1023
    wavelength  (x) float64 8kB 331.8 331.9 332.0 332.1 ... 468.2 468.3 468.4
Data variables:
    ROI 0       (frame, y, x) uint16 3MB 8281 8281 8265 ... 12297 12249 12105
Attributes:
    version:       3.0
    FrameInfo:     {'type': 'Frame', 'count': 5, 'pixelFormat': 'uint16', 'si...
    MetaFormat:    {'MetaBlock': []}
    Calibrations:  {'WavelengthCalib': {'id': 1, 'date': datetime.datetime(19...
    GeneralInfo:   {'creator': 'TUE\\s106932', 'created': datetime.datetime(2...

xarray.Dataset

Dimensions:
- frame: 5
- y: 256
- x: 1024

Coordinates: (4)

frame
(frame)
int64
0 1 2 3 4
```
array([0, 1, 2, 3, 4])
```

(y)

int64

0 1 2 3 4 5 ... 251 252 253 254 255

array([  0,   1,   2, ..., 253, 254, 255], shape=(256,))

(x)

int64

0 1 2 3 4 ... 1020 1021 1022 1023

array([   0,    1,    2, ..., 1021, 1022, 1023], shape=(1024,))

wavelength

(x)

float64

331.8 331.9 332.0 ... 468.3 468.4

array([331.75149713, 331.88410336, 332.01671504, ..., 468.17564513,
       468.30848472, 468.4413193 ], shape=(1024,))

Data variables: (1)

ROI 0

(frame, y, x)

uint16

8281 8281 8265 ... 12249 12105

type :: Region
count :: 1
width :: 1024
height :: 256
size :: 524288
stride :: 524288
sensor_mapping :: {'id': 3, 'x': 0, 'y': 0, 'height': 256, 'width': 1024, 'xBin': 1, 'yBin': 1}

array([[[ 8281,  8281,  8265, ...,  8265,  8265,  8265],
        [ 8281,  8265,  8265, ...,  8265,  8265,  8265],
        [ 8281,  8265,  8265, ...,  8265,  8265,  8265],
        ...,
        [ 9673,  9641,  9609, ...,  9353,  9449,  9561],
        [ 9721,  9673,  9641, ...,  9385,  9497,  9609],
        [ 9753,  9721,  9673, ...,  9417,  9529,  9641]],

       [[ 8441,  8441,  8425, ...,  8329,  8361,  8409],
        [ 8441,  8425,  8409, ...,  8329,  8361,  8393],
        [ 8441,  8425,  8409, ...,  8329,  8361,  8393],
        ...,
        [10329, 10297, 10249, ...,  9961, 10073, 10201],
        [10377, 10329, 10297, ...,  9993, 10121, 10249],
        [10425, 10377, 10329, ..., 10041, 10169, 10297]],

       [[ 8761,  8745,  8713, ...,  8569,  8633,  8697],
        [ 8745,  8713,  8697, ...,  8553,  8601,  8665],
        [ 8745,  8713,  8697, ...,  8553,  8601,  8665],
        ...,
        [11065, 11017, 10969, ..., 10649, 10793, 10921],
        [11113, 11065, 11017, ..., 10697, 10825, 10969],
        [11161, 11113, 11065, ..., 10745, 10873, 11017]],

       [[ 9225,  9193,  9161, ...,  8953,  9033,  9129],
        [ 9193,  9161,  9129, ...,  8921,  9001,  9097],
        [ 9193,  9161,  9129, ...,  8921,  9001,  9097],
        ...,
        [11849, 11801, 11753, ..., 11401, 11561, 11705],
        [11897, 11849, 11801, ..., 11449, 11609, 11753],
        [11945, 11897, 11849, ..., 11497, 11657, 11801]],

       [[ 9801,  9753,  9721, ...,  9449,  9561,  9673],
        [ 9753,  9721,  9673, ...,  9417,  9529,  9641],
        [ 9753,  9721,  9673, ...,  9417,  9529,  9641],
        ...,
        [12057, 12105, 12153, ..., 12201, 12345, 12201],
        [12009, 12057, 12105, ..., 12249, 12297, 12153],
        [11945, 12009, 12057, ..., 12297, 12249, 12105]]],
      shape=(5, 256, 1024), dtype=uint16)

Attributes: (5)
version :
3.0
FrameInfo :
{'type': 'Frame', 'count': 5, 'pixelFormat': 'uint16', 'size': 524288, 'stride': 524288, 'calibrations': 1, 'metaformat_index': None, 'ROIs': [{'type': 'Region', 'count': 1, 'width': 1024, 'height': 256, 'size': 524288, 'stride': 524288, 'sensor_mapping': {'id': 3, 'x': 0, 'y': 0, 'height': 256, 'width': 1024, 'xBin': 1, 'yBin': 1}}]}
MetaFormat :
{'MetaBlock': []}
Calibrations :
{'WavelengthCalib': {'id': 1, 'date': datetime.datetime(1970, 1, 1, 1, 0), 'orientation': 'Normal', 'wavelength': array([331.75149713, 331.88410336, 332.01671504, ..., 468.17564513, 468.30848472, 468.4413193 ], shape=(1024,)), 'coefficients': array([1., 0., 0., 0., 0.])}, 'SensorInformation': {'id': 2, 'orientation': 'Normal', 'width': 1024, 'height': 256}, 'SensorMapping': [{'id': 3, 'x': 0, 'y': 0, 'height': 256, 'width': 1024, 'xBin': 1, 'yBin': 1}]}
GeneralInfo :
{'creator': 'TUE\\s106932', 'created': datetime.datetime(2025, 4, 15, 11, 2, 27, 967440, tzinfo=TzInfo(7200)), 'last_modified': datetime.datetime(2025, 11, 24, 18, 5, 31, 62565), 'notes': ''}

Plotting data¶

Datasets behave as if they are dictionary-like containers for Regions-of-Interest, meaning you can access them using a key: ROI 0 by default for the first ROI.

Each element in the Dataset, is a DataArray, which is akin to a N-dimensional DataFrame.

In this case, you access the underlying data, not by a column name, but by the name of a dimension or coordinate.

Similarly, you can use groupby operations for aggregation etc.

This makes it very easy to iterate over the frames in a ROI and plot them, for instance:

In [3]:

Copied!





by_frames = data["ROI 0"].groupby("frame")
fig, ax = plt.subplots(len(by_frames), 1, figsize=(3, 12))
for index, frame in by_frames:
    frame.plot(x="x", y="y", ax=ax[index])
by_frames = data["ROI 0"].groupby("frame")
fig, ax = plt.subplots(len(by_frames), 1, figsize=(3, 12))
for index, frame in by_frames:
    frame.plot(x="x", y="y", ax=ax[index])

No description has been provided for this image

Instead of directly plotting, you can also aggregate over your data along a dimension, before visualizing.

Note: for aggregations etc. you should use only dimensions, not coordinates, as coordinates can depend on multiple dimensions.

In [21]:

Copied!





for index, frame in by_frames:
    frame.sum("y").plot(x="wavelength", label=f"frame {index}")
plt.title("")
plt.legend()
plt.ylabel("Counts")
for index, frame in by_frames:
    frame.sum("y").plot(x="wavelength", label=f"frame {index}")
plt.title("")
plt.legend()
plt.ylabel("Counts")

Out[21]:

Text(0, 0.5, 'Counts')

December 1, 2025 December 1, 2025