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 fromenhancement().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, sotz_offset_hoursis 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, andfreq[bin, point]andmag[bin, point]fromdetection_frequency()andmagnitude()(median) on the transits of each bin.- Return type:
See also
transit_timesGives
times.detection_frequencyThe frequency it computes in each bin.
magnitudeThe 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