lair.transects.profile#

lair.transects.profile(enh, times, by='hour', threshold=0.0, min_transits=10, tz_offset_hours=0.0)[source]#

Return the detection frequency and median magnitude per point, binned by time.

Parameters:
  • enh (np.ndarray) – Enhancement matrix enh[transit, point], as from enhancement().

  • times (pd.DatetimeIndex) – One time per transit, as from transit_times(). A naive time is UTC; a time-zone-aware time is converted to UTC first, so tz_offset_hours is the only shift.

  • by (str, optional) – The bins: "hour" (the default), "weekday" or "month" of the transit time.

  • threshold (float, optional) – Enhancement above which a transit counts as a detection. Default 0.

  • min_transits (int, optional) – Fewest transits with data a point needs in a bin. Default 10.

  • tz_offset_hours (float, optional) – Hours added to the UTC times before binning, to bin by local time (e.g. -7 for MST). Default 0.

Returns:

tuple[np.ndarray, np.ndarray, np.ndarray] – (bins, freq, mag): the bin values, and freq[bin, point] and mag[bin, point] from detection_frequency() and magnitude() (median) on the transits of each bin.

Return type:

tuple[ndarray, ndarray, ndarray]

See also

transit_times

Gives times.

detection_frequency

The frequency it computes in each bin.

magnitude

The magnitude it computes in each bin.

Examples

One transit an hour for a day, with point 0 enhanced before noon only. Each hour has one transit, so min_transits=1:

>>> import numpy as np
>>> import pandas as pd
>>> from lair.transects import profile
>>> enh = np.array([[1.0, 0.0]] * 12 + [[0.0, 0.0]] * 12)
>>> times = pd.date_range("2024-01-15 00:00", periods=24, freq="1h")
>>> bins, freq, mag = profile(enh, times, min_transits=1)
>>> freq[[0, 12]]
array([[1., 0.],
       [0., 0.]])
>>> mag[[0, 12]]
array([[ 1., nan],
       [nan, nan]])

A time with a time zone is converted to UTC first, so the same moments give the same bins:

>>> local = times.tz_localize("UTC").tz_convert("America/Denver")
>>> bins, freq_local, mag_local = profile(enh, local, min_transits=1)
>>> bool(np.array_equal(freq, freq_local, equal_nan=True))
True