Histograms & Labels

Native 1-D / 2-D histograms and per-photon label lookup, used as the fastest way to build images and decay curves from photon streams.

from photonscore import histogram, label

# 2-D image of a LINCam recording
img = histogram(x, 0, 4096, 512, y, 0, 4096, 512)

# Decay curve
dt_hist = histogram(dt, 0, 4096, 1024)

# Tag each photon with a label image
roi = label(label_image, x, 0, 4096, y, 0, 4096)

histogram

histogram.histogram(x, x_min, x_max, x_bins, y=None, y_min=None, y_max=None, y_bins=None)

Compute a 1-D or 2-D histogram of x (and optionally y).

When y is omitted the function returns a 1-D histogram of x with x_bins equal-width bins in the half-open range [x_min, x_max). When y is supplied, a 2-D histogram is returned instead; if any of y_min, y_max, y_bins are omitted they default to the matching x_* value so the result is square.

Parameters:

Name	Type	Description	Default
x	ndarray	Sample values along the first axis.	required
x_min	float	Lower edge of the first-axis range.	required
x_max	float	Upper edge of the first-axis range (exclusive).	required
x_bins	int	Number of bins along the first axis.	required
y	ndarray | None	Sample values along the second axis. Pass None for a 1-D histogram.	None
y_min	float | None	Lower edge for the second axis. Defaults to x_min.	None
y_max	float | None	Upper edge for the second axis. Defaults to x_max.	None
y_bins	int | None	Number of second-axis bins. Defaults to x_bins.	None

Returns:

Type	Description
ndarray	NumPy array of counts — shape (x_bins,) or
ndarray	(x_bins, y_bins).

Source code in histogram.py

def histogram(
  x: np.ndarray,
  x_min: float,
  x_max: float,
  x_bins: int,
  y: np.ndarray | None = None,
  y_min: float | None = None,
  y_max: float | None = None,
  y_bins: int | None = None,
) -> np.ndarray:
  """Compute a 1-D or 2-D histogram of `x` (and optionally `y`).

  When `y` is omitted the function returns a 1-D histogram of `x` with
  `x_bins` equal-width bins in the half-open range
  ``[x_min, x_max)``. When `y` is supplied, a 2-D histogram is returned
  instead; if any of `y_min`, `y_max`, `y_bins` are omitted they
  default to the matching `x_*` value so the result is square.

  Args:
      x: Sample values along the first axis.
      x_min: Lower edge of the first-axis range.
      x_max: Upper edge of the first-axis range (exclusive).
      x_bins: Number of bins along the first axis.
      y: Sample values along the second axis. Pass ``None`` for a 1-D
          histogram.
      y_min: Lower edge for the second axis. Defaults to `x_min`.
      y_max: Upper edge for the second axis. Defaults to `x_max`.
      y_bins: Number of second-axis bins. Defaults to `x_bins`.

  Returns:
      NumPy array of counts — shape ``(x_bins,)`` or
      ``(x_bins, y_bins)``.
  """
  x = x if isinstance(x, np.ndarray) else np.array(x)
  if y is None:
    return hist_1d(x, x_min, x_max, x_bins)

  y = y if isinstance(y, np.ndarray) else np.array(y)
  y_min = x_min if y_min is None else y_min
  y_max = x_max if y_max is None else y_max
  y_bins = x_bins if y_bins is None else y_bins
  return hist_2d(x, x_min, x_max, x_bins, y, y_min, y_max, y_bins)

label

labels.label(labels, x, x_min, x_max, y, y_min=None, y_max=None)

Look up the label at each (x, y) coordinate.

Parameters:

Name	Type	Description	Default
labels	ndarray	2-D integer NumPy array — the label image.	required
x	ndarray	Per-photon x-coordinates.	required
x_min	float	Lower bound of the x-axis (maps to label column 0).	required
x_max	float	Upper bound of the x-axis (maps to the last column).	required
y	ndarray	Per-photon y-coordinates.	required
y_min	float | None	Lower bound of the y-axis. Defaults to x_min.	None
y_max	float | None	Upper bound of the y-axis. Defaults to x_max.	None

Returns:

Type	Description
ndarray	1-D NumPy array of label values, one per photon.

Source code in labels.py

def label(
  labels: np.ndarray,
  x: np.ndarray,
  x_min: float,
  x_max: float,
  y: np.ndarray,
  y_min: float | None = None,
  y_max: float | None = None,
) -> np.ndarray:
  """Look up the label at each ``(x, y)`` coordinate.

  Args:
      labels: 2-D integer NumPy array — the label image.
      x: Per-photon x-coordinates.
      x_min: Lower bound of the x-axis (maps to label column 0).
      x_max: Upper bound of the x-axis (maps to the last column).
      y: Per-photon y-coordinates.
      y_min: Lower bound of the y-axis. Defaults to `x_min`.
      y_max: Upper bound of the y-axis. Defaults to `x_max`.

  Returns:
      1-D NumPy array of label values, one per photon.
  """
  x = x if isinstance(x, np.ndarray) else np.array(x)
  y = y if isinstance(y, np.ndarray) else np.array(y)
  y_min = x_min if y_min is None else y_min
  y_max = x_max if y_max is None else y_max
  return labels_2d(labels, x, x_min, x_max, y, y_min, y_max)