PET LM Unlisting `parallelproj.unlist`¶

Helpers for converting listmode events into sinograms (“unlisting”). Given per-event detector (and TOF) indices, these functions produce the corresponding sinogram-bin mapping, which is useful when histogramming measured listmode data into sinograms. For working directly in listmode instead, see the listmode projector and the 04_listmode_algorithms gallery examples.

Listmode-to-sinogram histogramming for regular-polygon PET scanners.

Converts per-event crystal and ring indices into a binned sinogram array, for both non-TOF and TOF acquisitions. A companion function converts raw detection-time differences (in nanoseconds) to projector-convention TOF bin indices ready for histogramming.

parallelproj.unlist.detection_times_to_tof_bin(d_red: Any, d_blue: Any, dt_blue_minus_red: Any, projector: RegularPolygonPETProjector) → Array[source]¶

Convert raw detection-time differences to projector-convention TOF bins.

Each coincidence event is characterised by two crystal hits and the signed arrival-time difference t_blue - t_red (in nanoseconds). This function maps that physical timing to the unsigned integer TOF bin used by regular_polygon_events_to_sinogram(), taking into account whether the projector’s canonical ray direction runs from red to blue or vice versa.

Parameters:

d_red (array-like, shape (N,), dtype int32) – In-ring crystal indices for the red detector.
d_blue (array-like, shape (N,), dtype int32) – In-ring crystal indices for the blue detector.
dt_blue_minus_red (array-like, shape (N,), dtype float) – t_blue - t_red in nanoseconds. Positive = blue photon arrived later = emission closer to the red side. Internally cast to float32.
projector (RegularPolygonPETProjector) – TOF projector that defines the bin grid. Must have tof_parameters set.

Returns:

tof_bin – Unsigned TOF bin numbers in the projector convention (bin 0 = closest to xstart). Returns -1 for events whose emission falls outside the sinogram’s TOF window, or for invalid crystal pairs (self-pairs / out-of-bounds). These -1 values are silently discarded by regular_polygon_events_to_sinogram().

Return type:

Array, shape (N,), dtype int32

Raises:

ValueError – If projector.tof_parameters is None.

Notes

The signed spatial off-centre displacement (positive toward the red detector) is

\[\Delta x_{\text{blue->red}} = \frac{c}{2}\,(t_{\text{blue}} - t_{\text{red}})\]

where \(c\) = C_MM_PER_NS mm/ns. Letting \(s = \text{sign}[d_{\text{red}}, d_{\text{blue}}]\) (+1 if d_red is the canonical xstart, -1 otherwise) and \(W\) = tofbin_width, the bin index is

\[k = \operatorname{round}\!\left( \frac{N-1}{2} - \frac{s\,\Delta x_{\text{blue->red}} + \Delta_{\text{center}}}{W} \right)\]

where \(\Delta_{\text{center}}\) = tofcenter_offset.

Examples

Listmode to sinogram unlisting

parallelproj.unlist.regular_polygon_events_to_sinogram(projector: RegularPolygonPETProjector, d_red: Any, r_red: Any, d_blue: Any, r_blue: Any, unsigned_sinogram_tof_bin: Any | None = None) → Array[source]¶

Histogram listmode events into a sinogram.