pytsf 1.0.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
pytsf/__init__.py ADDED
@@ -0,0 +1,40 @@
1
+ """pytsf — read Bruker timsTOF data (TSF and TDF) without the Bruker SDK.
2
+
3
+ Bruker's tdf-sdk ships `timsdata.dll` (Windows) and `libtimsdata.so`
4
+ (Linux x86-64) only, so `.d` data cannot be read on macOS — including Apple
5
+ Silicon — using the vendor library. This package reimplements the reading path
6
+ in pure Python so it runs anywhere NumPy does.
7
+
8
+ from pytsf import TsfData, TdfData
9
+
10
+ with TsfData("/path/to/imaging.d") as tsf: # TSF: single spectra
11
+ mz, intensity = tsf.line_spectrum_mz(1)
12
+
13
+ with TdfData("/path/to/pasef.d") as tdf: # TDF: ion mobility
14
+ mz, oneoverk0, intensity = tdf.frame_mz_mobility(1)
15
+
16
+ See README.md for how m/z and mobility are calibrated and how accurate they are.
17
+ """
18
+
19
+ from pytsf.api import TsfData
20
+ from pytsf.meta import Frame, MzCalibrationRow, TsfError, TsfMetadata
21
+ from pytsf.mobility import MobilityCalibration, ccs_to_oneoverk0, find_reference_ions, oneoverk0_to_ccs
22
+ from pytsf.tdf import TdfData, TdfFrame, TdfMetadata
23
+
24
+ __all__ = [
25
+ "Frame",
26
+ "MobilityCalibration",
27
+ "MzCalibrationRow",
28
+ "TdfData",
29
+ "TdfFrame",
30
+ "TdfMetadata",
31
+ "TsfData",
32
+ "TsfError",
33
+ "TsfMetadata",
34
+ "__version__",
35
+ "ccs_to_oneoverk0",
36
+ "find_reference_ions",
37
+ "oneoverk0_to_ccs",
38
+ ]
39
+
40
+ __version__ = "1.1.0"
pytsf/api.py ADDED
@@ -0,0 +1,169 @@
1
+ """Public API for reading Bruker TSF analyses without the Bruker library.
2
+
3
+ `TsfData` deliberately mirrors the method names of Bruker's own
4
+ `examples/py/tsfdata.py` wrapper, so existing scripts can usually be ported by
5
+ changing only the import:
6
+
7
+ # before
8
+ import tsfdata
9
+ tsf = tsfdata.TsfData(analysis_dir)
10
+
11
+ # after
12
+ from pytsf import TsfData
13
+ tsf = TsfData(analysis_dir)
14
+
15
+ Pythonic aliases (`read_line_spectrum`, `index_to_mz`, ...) are provided
16
+ alongside the camelCase originals.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import contextlib
22
+ import os
23
+ from collections.abc import Iterator
24
+
25
+ import numpy as np
26
+
27
+ from pytsf import bin as _bin
28
+ from pytsf import calibration_fitted as _fitted
29
+ from pytsf.meta import Frame, TsfError, TsfMetadata
30
+
31
+ __all__ = ["Frame", "TsfData", "TsfError"]
32
+
33
+
34
+ class TsfData:
35
+ """A Bruker timsTOF .d analysis directory in TSF format.
36
+
37
+ Parameters
38
+ ----------
39
+ analysis_directory
40
+ The `.d` directory containing `analysis.tsf` and `analysis.tsf_bin`.
41
+ use_recalibrated_state
42
+ Accepted for signature compatibility with the Bruker wrapper. Post-hoc
43
+ post-hoc recalibration states are not interpreted by this reader;
44
+ passing True raises rather than silently returning values the caller
45
+ would believe were recalibrated.
46
+ """
47
+
48
+ def __init__(
49
+ self,
50
+ analysis_directory: str | os.PathLike,
51
+ use_recalibrated_state: bool = False,
52
+ ) -> None:
53
+ if use_recalibrated_state:
54
+ raise TsfError(
55
+ "use_recalibrated_state=True is not supported: this reader only "
56
+ "implements the raw acquisition-time calibration. Pass False to "
57
+ "read raw-calibration m/z values."
58
+ )
59
+ self.meta = TsfMetadata(analysis_directory)
60
+ self.analysis_directory = self.meta.analysis_directory
61
+
62
+ if not os.path.isfile(self.meta.binary_path):
63
+ raise TsfError(f"Missing binary file: {self.meta.binary_path}")
64
+ self._bin = _bin.BinaryFile(self.meta.binary_path)
65
+ self._fitted = _fitted.FittedCalibration(self.meta.sqlite_path)
66
+
67
+ @property
68
+ def calibration(self) -> _fitted.FittedCalibration:
69
+ """The fitted calibration. One fit covers the whole analysis."""
70
+ return self._fitted
71
+
72
+ # -- compatibility shim ----------------------------------------------
73
+
74
+ @property
75
+ def conn(self):
76
+ """The underlying sqlite3 connection, as Bruker's wrapper exposes."""
77
+ return self.meta.conn
78
+
79
+ # -- m/z conversion ---------------------------------------------------
80
+
81
+ def index_to_mz(self, frame_id: int, indices) -> np.ndarray:
82
+ """Convert (possibly non-integer) index values to m/z for one spectrum."""
83
+ return self._fitted.index_to_mz(indices)
84
+
85
+ def mz_to_index(self, frame_id: int, mzs) -> np.ndarray:
86
+ """Convert m/z values to index values for one spectrum."""
87
+ return self._fitted.mz_to_index(mzs)
88
+
89
+ indexToMz = index_to_mz
90
+ mzToIndex = mz_to_index
91
+
92
+ # -- spectra ----------------------------------------------------------
93
+
94
+ def read_line_spectrum(self, frame_id: int):
95
+ """Centroided ("line") spectrum as (index, intensity).
96
+
97
+ Use `index_to_mz` to turn the indices into m/z values.
98
+ """
99
+ if not self.meta.has_line_spectra:
100
+ raise TsfError("This analysis contains no line spectra " "(GlobalMetadata.HasLineSpectra == 0).")
101
+ frame = self.meta.frame(frame_id)
102
+ idx, inten, _ = self._bin.read_line_spectrum(frame.tims_id, frame.num_peaks)
103
+ return idx, inten
104
+
105
+ def read_line_spectrum_with_width(self, frame_id: int):
106
+ """Centroided spectrum as (index, intensity, width)."""
107
+ if not self.meta.has_line_spectra:
108
+ raise TsfError("This analysis contains no line spectra " "(GlobalMetadata.HasLineSpectra == 0).")
109
+ if not self.meta.has_line_spectra_peak_width:
110
+ raise TsfError("This analysis contains no peak widths " "(GlobalMetadata.HasLineSpectraPeakWidth == 0).")
111
+ frame = self.meta.frame(frame_id)
112
+ return self._bin.read_line_spectrum(frame.tims_id, frame.num_peaks, want_width=True)
113
+
114
+ def read_profile_spectrum(self, frame_id: int) -> np.ndarray:
115
+ """Profile spectrum as a dense uint32 intensity array; the position in
116
+ the array is the index (so `index_to_mz(frame_id, arange(len(a)))`
117
+ gives the m/z axis).
118
+ """
119
+ if not self.meta.has_profile_spectra:
120
+ raise TsfError("This analysis contains no profile spectra " "(GlobalMetadata.HasProfileSpectra == 0).")
121
+ frame = self.meta.frame(frame_id)
122
+ return self._bin.read_profile_spectrum(frame.tims_id)
123
+
124
+ readLineSpectrum = read_line_spectrum
125
+ readLineSpectrumWithWidth = read_line_spectrum_with_width
126
+ readProfileSpectrum = read_profile_spectrum
127
+
128
+ # -- conveniences the Bruker wrapper lacks ----------------------------
129
+
130
+ def line_spectrum_mz(self, frame_id: int):
131
+ """(m/z, intensity) for a centroided spectrum, in one call."""
132
+ idx, inten = self.read_line_spectrum(frame_id)
133
+ return self.index_to_mz(frame_id, idx), inten
134
+
135
+ def profile_spectrum_mz(self, frame_id: int):
136
+ """(m/z, intensity) for a profile spectrum, in one call."""
137
+ inten = self.read_profile_spectrum(frame_id)
138
+ # One fit per analysis, so the axis depends only on the length and is
139
+ # cached; recomputing it per spectrum would dominate an imaging run.
140
+ return self._fitted.index_axis(inten.size), inten
141
+
142
+ @property
143
+ def frames(self) -> list[Frame]:
144
+ return self.meta.frames()
145
+
146
+ def __len__(self) -> int:
147
+ return self.meta.frame_count
148
+
149
+ def __iter__(self) -> Iterator[Frame]:
150
+ return iter(self.meta.frames())
151
+
152
+ # -- lifecycle --------------------------------------------------------
153
+
154
+ def close(self) -> None:
155
+ if getattr(self, "_bin", None) is not None:
156
+ self._bin.close()
157
+ self._bin = None # type: ignore[assignment]
158
+ if getattr(self, "meta", None) is not None:
159
+ self.meta.close()
160
+
161
+ def __enter__(self) -> TsfData:
162
+ return self
163
+
164
+ def __exit__(self, *exc: object) -> None:
165
+ self.close()
166
+
167
+ def __del__(self) -> None:
168
+ with contextlib.suppress(Exception):
169
+ self.close()
pytsf/bin.py ADDED
@@ -0,0 +1,250 @@
1
+ """Reader for the ``analysis.tsf_bin`` binary spectrum file.
2
+
3
+ The structure of this file is documented by `timsrust-tsf`_ (MannLabs, MIT),
4
+ on which this reader is based; see LICENSE for its terms. Behaviour not covered
5
+ there was established by testing against the vendor library through its
6
+ documented public C API, and is expressed here in the implementation rather
7
+ than restated as a specification. See PROVENANCE.md.
8
+
9
+ Spectra are located by ``Frames.TimsId`` and decompressed with zstd. Line
10
+ (centroided) spectra yield index, intensity and -- where the acquisition
11
+ recorded them -- peak width arrays; profile spectra yield a dense array in
12
+ which position is the index.
13
+
14
+ .. _timsrust-tsf: https://github.com/MannLabs/timsrust
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import contextlib
20
+ import struct
21
+
22
+ import numpy as np
23
+ import zstandard as zstd
24
+
25
+ __all__ = [
26
+ "MAX_SUBBLOCK_SIZE",
27
+ "BinaryFile",
28
+ "TsfBinError",
29
+ "decode_line_block",
30
+ "decode_profile_block",
31
+ "encode_line_block",
32
+ "encode_profile_block",
33
+ "encode_spectrum_block",
34
+ "transpose_to_byte_planes",
35
+ ]
36
+
37
+ #: Largest sub-block this reader will attempt to read (1 GiB). A declared
38
+ #: size beyond this is treated as corruption rather than allocated.
39
+ MAX_SUBBLOCK_SIZE = 0x40000000
40
+
41
+ _HEADER = struct.Struct("<II")
42
+ _DCTX = zstd.ZstdDecompressor()
43
+
44
+
45
+ class TsfBinError(Exception):
46
+ """Raised when a .tsf_bin block cannot be parsed."""
47
+
48
+
49
+ def _decompress(buf: bytes, what: str) -> bytes:
50
+ """Decompress one raw zstd frame.
51
+
52
+ Frames written by the acquisition software declare their content size; we
53
+ try that path first and fall back to streaming for any that do not.
54
+ """
55
+ try:
56
+ return _DCTX.decompress(buf)
57
+ except zstd.ZstdError:
58
+ pass
59
+ try:
60
+ dobj = zstd.ZstdDecompressor().decompressobj()
61
+ return dobj.decompress(buf) + dobj.flush()
62
+ except zstd.ZstdError as exc:
63
+ raise TsfBinError(f"error decompressing {what} data: {exc}") from exc
64
+
65
+
66
+ # -- decoding -------------------------------------------------------------
67
+
68
+
69
+ def decode_line_block(raw: bytes, num_peaks: int, with_width: bool | None = None):
70
+ """Decode an already-decompressed line sub-block.
71
+
72
+ Returns ``(index, intensity, width_or_None)``.
73
+ """
74
+ n = int(num_peaks)
75
+ if n < 0:
76
+ raise TsfBinError("NumPeaks is NULL/negative; no line spectrum stored")
77
+ if n == 0:
78
+ return _empty_line(bool(with_width))
79
+
80
+ if with_width is None:
81
+ with_width = len(raw) >= n * 16
82
+ need = n * (16 if with_width else 12)
83
+ if len(raw) < need:
84
+ raise TsfBinError(f"line sub-block too short: {len(raw)} bytes, need {need} for {n} peaks")
85
+
86
+ index = np.frombuffer(raw, dtype="<f8", count=n, offset=0).copy()
87
+ inten = np.frombuffer(raw, dtype="<f4", count=n, offset=n * 8).copy()
88
+ width = np.frombuffer(raw, dtype="<f4", count=n, offset=n * 12).copy() if with_width else None
89
+ return index, inten, width
90
+
91
+
92
+ def _empty_line(with_width: bool):
93
+ return (
94
+ np.empty(0, dtype="<f8"),
95
+ np.empty(0, dtype="<f4"),
96
+ np.empty(0, dtype="<f4") if with_width else None,
97
+ )
98
+
99
+
100
+ def decode_profile_block(raw: bytes) -> np.ndarray:
101
+ """Decode an already-decompressed profile sub-block (byte planes)."""
102
+ n = len(raw) // 4 # a non-multiple-of-4 tail is ignored
103
+ if n == 0:
104
+ return np.empty(0, dtype=np.uint32)
105
+ planes = np.frombuffer(raw, dtype=np.uint8, count=4 * n).reshape(4, n)
106
+ out = planes[0].astype(np.uint32)
107
+ out |= planes[1].astype(np.uint32) << np.uint32(8)
108
+ out |= planes[2].astype(np.uint32) << np.uint32(16)
109
+ out |= planes[3].astype(np.uint32) << np.uint32(24)
110
+ return out
111
+
112
+
113
+ # -- file access ----------------------------------------------------------
114
+
115
+
116
+ class BinaryFile:
117
+ """An open ``analysis.tsf_bin``.
118
+
119
+ Holds one file handle for the lifetime of the object, which matters for
120
+ MALDI imaging analyses where a single file can contain >10^5 spectra.
121
+ """
122
+
123
+ def __init__(self, path: str):
124
+ self.path = str(path)
125
+ self._f = open(self.path, "rb")
126
+
127
+ # -- lifecycle --
128
+ def close(self) -> None:
129
+ if getattr(self, "_f", None) is not None:
130
+ self._f.close()
131
+ self._f = None # type: ignore[assignment]
132
+
133
+ def __enter__(self) -> BinaryFile:
134
+ return self
135
+
136
+ def __exit__(self, *exc: object) -> None:
137
+ self.close()
138
+
139
+ def __del__(self) -> None:
140
+ with contextlib.suppress(Exception):
141
+ self.close()
142
+
143
+ # -- header --
144
+ def block_header(self, tims_id: int | None) -> tuple[int, int, int]:
145
+ """Return ``(total_size, line_size, profile_size)`` for one block."""
146
+ if tims_id is None or tims_id < 0:
147
+ return (0, 0, 0)
148
+ self._f.seek(tims_id)
149
+ hdr = self._f.read(8)
150
+ if len(hdr) != 8:
151
+ raise TsfBinError(f"error reading binary header at offset {tims_id}")
152
+ total, line_size = _HEADER.unpack(hdr)
153
+ # [rust blobs.rs:91] checks chunk_padded >= 8 and >= compressed_len.
154
+ # The stricter relation total >= 8 + line_size must hold, because
155
+ # total delimits the profile sub-block.
156
+ if total < 8 or line_size > total - 8:
157
+ raise TsfBinError(f"corrupt block header at offset {tims_id}: " f"total={total} line={line_size}")
158
+ return (total, line_size, total - 8 - line_size)
159
+
160
+ def _sub_block(self, tims_id: int, which: str) -> bytes:
161
+ total, line_size, prof_size = self.block_header(tims_id)
162
+ if total == 0:
163
+ return b""
164
+ if which == "line":
165
+ offset, size = tims_id + 8, line_size
166
+ else:
167
+ offset, size = tims_id + 8 + line_size, prof_size
168
+ if size == 0:
169
+ return b""
170
+ if size > MAX_SUBBLOCK_SIZE:
171
+ raise TsfBinError(f"compressed {which} spectrum size too large ({size})")
172
+ self._f.seek(offset)
173
+ buf = self._f.read(size)
174
+ if len(buf) != size:
175
+ raise TsfBinError(
176
+ f"error reading {which} frame data at offset {offset}: " f"wanted {size} bytes, got {len(buf)}"
177
+ )
178
+ return buf
179
+
180
+ # -- reads --
181
+ def read_line_spectrum(
182
+ self,
183
+ tims_id: int | None,
184
+ num_peaks: int | None,
185
+ want_width: bool | None = None,
186
+ ):
187
+ """Read one line spectrum as ``(index, intensity, width_or_None)``.
188
+
189
+ ``want_width`` defaults to inferring from the payload length rather
190
+ than trusting ``GlobalMetadata.HasLineSpectraPeakWidth``, so that a
191
+ flag inconsistent with the payload cannot cause an out-of-bounds read.
192
+ """
193
+ if tims_id is None or tims_id < 0 or num_peaks is None or int(num_peaks) <= 0:
194
+ return _empty_line(bool(want_width))
195
+ raw = self._sub_block(tims_id, "line")
196
+ if not raw:
197
+ return _empty_line(bool(want_width))
198
+ return decode_line_block(_decompress(raw, "line"), num_peaks, want_width)
199
+
200
+ def read_profile_spectrum(self, tims_id: int | None) -> np.ndarray:
201
+ """Read one profile spectrum as a dense uint32 array (position == index)."""
202
+ if tims_id is None or tims_id < 0:
203
+ return np.empty(0, dtype=np.uint32)
204
+ raw = self._sub_block(tims_id, "profile")
205
+ if not raw:
206
+ return np.empty(0, dtype=np.uint32)
207
+ return decode_profile_block(_decompress(raw, "profile"))
208
+
209
+
210
+ # -- encoding (used by the test suite to build synthetic fixtures) --------
211
+
212
+
213
+ def transpose_to_byte_planes(values) -> bytes:
214
+ """uint32 sequence -> the byte-plane layout of a profile sub-block.
215
+
216
+ Inverse of :func:`decode_profile_block`.
217
+ """
218
+ v = np.asarray(values, dtype="<u4")
219
+ if v.size == 0:
220
+ return b""
221
+ return np.frombuffer(v.tobytes(), dtype=np.uint8).reshape(-1, 4).T.tobytes()
222
+
223
+
224
+ def encode_line_block(index, intensity, width=None, level: int = 3) -> bytes:
225
+ if len(index) != len(intensity):
226
+ raise ValueError("index/intensity length mismatch")
227
+ if width is not None and len(width) != len(index):
228
+ raise ValueError("width length mismatch")
229
+ parts = [
230
+ np.asarray(index, dtype="<f8").tobytes(),
231
+ np.asarray(intensity, dtype="<f4").tobytes(),
232
+ ]
233
+ if width is not None:
234
+ parts.append(np.asarray(width, dtype="<f4").tobytes())
235
+ return zstd.ZstdCompressor(level=level).compress(b"".join(parts))
236
+
237
+
238
+ def encode_profile_block(values, level: int = 3) -> bytes:
239
+ return zstd.ZstdCompressor(level=level).compress(transpose_to_byte_planes(values))
240
+
241
+
242
+ def encode_spectrum_block(index=(), intensity=(), width=None, profile=None, level: int = 3) -> bytes:
243
+ """Build one complete per-spectrum block (8-byte header + both sub-blocks).
244
+
245
+ ``profile=None`` omits the profile sub-block entirely; ``profile=[]``
246
+ stores an empty zstd frame, which is how "no profile" is represented.
247
+ """
248
+ line = encode_line_block(index, intensity, width, level) if len(index) else b""
249
+ prof = b"" if profile is None else encode_profile_block(profile, level)
250
+ return _HEADER.pack(8 + len(line) + len(prof), len(line)) + line + prof