metrics

nomad.metrics.metrics.rog(stops, agg_freq='d', weighted=True, traj_cols=None, time_weights=None, exploded=True, **kwargs)[source]
if weighted AND time_weights, then

  1. weights = duration * time_weights

if (weighted) AND (time_weights is None and not found in colunmns), then

  1. weights = duration

if (weighted) AND (time_weights is None and found in columns), then

  1. weights = duration * time_weights

if NOT weighted, then

  1. weights = 1

Compute radius of gyration per bucket (and per user, if present).

Parameters:

  • stops (pd.DataFrame)

  • agg_freq (str) – Pandas offset alias for time‐bucketing (e.g. ‘d’,’w’,’m’).

  • weighted (bool) – If True, weight by duration; else unweighted.

  • traj_cols (dict, optional) – Mapping for x/y (or lon/lat), timestamp/datetime, duration, user_id.

  • time_weights (pd.Series, optional) – If None or 1 and weighted is True, weights = duration. Otherwise, stops have weights = time_weights * duration.

  • weight_freq (str, optional) – ‘D’ for daily, ‘H’ for hourly weights. Default is ‘D’.

Returns:

Columns = [bucket, user_id? , rog].

Return type:

pd.DataFrame

nomad.metrics.metrics.self_containment(stops, threshold, agg_freq='d', weighted=True, home_activity_type='home', traj_cols=None, time_weights=None, exploded=True, **kwargs)[source]

Compute self-containment (proportion of non-home time spent within threshold distance from home).

Self-containment describes the propensity of individuals to stay close to home. It is calculated as the time-weighted proportion of non-home activities that are within a threshold distance from home.

Parameters:

  • stops (pd.DataFrame) – Stop data with spatial coordinates, duration, and location_id.

  • threshold (float) – Distance threshold in the same units as coordinates (meters for projected, degrees for lat/lon). Activities within this distance from home are considered “contained”.

  • agg_freq (str) – Pandas offset alias for time-bucketing (e.g. ‘d’,’w’,’m’).

  • weighted (bool) – If True, weight by duration; else unweighted (count activities).

  • home_activity_type (str) – Value in location_id column that identifies home locations. Default is ‘home’. Can be ‘home_id’ or any other location_id value.

  • traj_cols (dict, optional) – Mapping for x/y (or lon/lat), timestamp/datetime, duration, user_id, location_id.

  • time_weights (pd.Series, optional) – Additional time weights to multiply with duration (if weighted=True).

  • exploded (bool) – If True, explode stops that straddle multiple time periods. Default is True.

  • **kwargs – Additional arguments passed to explode_stops or column overrides.

Returns:

Columns = [period, user_id?, self_containment]. self_containment is the proportion [0, 1] of non-home time spent within threshold from home.

Return type:

pd.DataFrame

nomad.metrics.metrics.social_interaction_potential(contacts, weight='duration')[source]

Aggregate undirected contact events into user-level SIP.

Each contact contributes its weight to both users.

Parameters:

  • contacts (pandas.DataFrame) – Contact event table with one row per undirected contact and canonical user_id_1 and user_id_2 columns.

  • weight (str, default "duration") – Name of the column containing the weight contributed by each contact.

Returns:

User-level SIP table with columns user_id and sip.

Return type:

pandas.DataFrame