contact_estimation

Various algorithms for estimating individual co-location

nomad.contact_estimation.compute_contact_weights(contacts, method='duration', distance_threshold=None, traj_cols=None, **kwargs)[source]

Compute contact weights from a contact event table.

Supported methods are "duration" and "linear_distance". Linear distance weighting uses duration * max(0, 1 - distance / threshold).

Parameters:

  • contacts (pd.DataFrame) – Contact event table from estimate_contacts.

  • method (str) – Either ‘duration’ or ‘linear_distance’.

  • distance_threshold (float, optional) – Contact radius used by ‘linear_distance’; required for that method. Linear-distance weights require contacts generated with complete_output=True.

  • traj_cols (dict, optional) – Mapping for duration and distance.

  • **kwargs – Column-name overrides forwarded to the traj_cols resolver.

Returns:

Series named contact_weight and indexed like contacts.

Return type:

pandas.Series

nomad.contact_estimation.estimate_contacts(stops, distance_threshold=None, complete_output=False, traj_cols=None, **kwargs)[source]

Estimate undirected co-location/contact events from a stop table.

With distance_threshold=None, contacts are stops from different users at the same location_id with strictly overlapping times. With a distance threshold, contacts are stops from different users within that radius and with strictly overlapping times. Latitude/longitude thresholds are meters; projected x/y thresholds use the coordinate units.

Parameters:

  • stops (pd.DataFrame) – Stop table with user_id, a start time (datetime or timestamp), an end time or duration, and either location_id (exact mode) or coordinates (radius mode).

  • distance_threshold (float, optional) – Contact radius. None selects exact-location mode. Meters for lat/lon, coordinate units for projected x/y.

  • complete_output (bool, default False) – Include the contact end time and location_id or distance.

  • traj_cols (dict, optional) – Mapping for user_id, time, duration, location_id, and coordinates.

  • **kwargs – Column-name overrides forwarded to the traj_cols resolver.

Returns:

Contact events with user_id_1, user_id_2, start time, and duration. With complete_output=True, also includes end time and location_id or distance. Time columns preserve the input representation and duration is in minutes.

Return type:

pd.DataFrame

nomad.contact_estimation.overlapping_visits(left, right, match_location=False, traj_cols=None, right_traj_cols=None, **kwargs)[source]
nomad.contact_estimation.precision_recall_f1_from_minutes(total_pred, total_truth, tp)[source]

Compute P/R/F1 from minute totals.