Skip to content

RECAST Social Relationships

fastmob.social implements RECAST (Random rElationship ClASsifier sTrategy) for temporal physical contacts inferred from globally assigned staypoints.

recast_from_staypoints uses UTC calendar days as its event snapshots. This matches RECAST's human-mobility setting and avoids exposing an arbitrary time delta as a social parameter. A daily edge is created only when two users' stay intervals overlap at a shared global location for at least min_minutes_for_encounter (default: 5 minutes). It then uses the paper's T-RND: each daily event graph is independently sampled with the degree-product RND probability. This preserves degrees in expectation rather than exactly in every replica. The pooled randomized persistence and topological-overlap distributions define both thresholds at p_rnd.

Every observed aggregate edge is returned as one of:

  • Friends: social persistence and social overlap.
  • Bridges: social persistence and random-like overlap.
  • Acquaintances: random-like persistence and social overlap.
  • Random: random-like persistence and overlap.

The defaults reproduce the paper's five randomized replicas, while keeping the graph construction, randomization, and metric calculations in Rust.

RECAST parallelizes independent (day, location) contact buckets and T-RND replica/window work through Rayon. The public API intentionally has no worker parameter: use the RAYON_NUM_THREADS environment variable to bound the process-wide Rayon pool when coordinating CPU use with other workloads.

validate_recast_from_staypoints adds the validation artifacts from the paper without expanding into its application-specific routing experiments: pooled null distributions for the Figure 4 CCDFs, full cumulative clustering curves (Figure 3), and random-edge-only clustering curves (Figure 8). The dedicated temporal_graph_from_staypoints, rnd, and t_rnd APIs expose the underlying Arrow-backed event graphs for independent inspection.

fastmob.social.RecastClass

Bases: IntEnum

Relationship classes defined by RECAST Algorithm 1.

fastmob.social.RecastResult dataclass

Classification arrays aligned one-for-one with aggregate observed edges.

fastmob.social.RecastTemporalGraph dataclass

Packed Arrow event graphs; offsets delimit the edges for each day.

fastmob.social.RecastValidation dataclass

Section 4/5 RECAST validation artifacts, all in Arrow arrays.

*_null arrays are the pooled RND/T-RND distributions used to infer thresholds and plot the paper's CCDF diagnostics. full_clustering corresponds to Figure 3; random_only_clustering corresponds to Figure 8 after retaining only edges classified as Random.

fastmob.social.recast_from_staypoints(staypoints, locations, *, min_minutes_for_encounter=5, p_rnd=0.001, random_replicates=5, seed=42)

Classify contacts into Friends, Bridges, Acquaintances, and Random.

The random null model is the paper's degree-product RND, independently sampled per daily event graph by T-RND. It preserves snapshot degrees in expectation, not exactly in each realization.

fastmob.social.validate_recast_from_staypoints(staypoints, locations, *, min_minutes_for_encounter=5, p_rnd=0.001, random_replicates=5, seed=42)

Return the classifier plus Figure 3/4/8 validation diagnostics.

This library-scope API intentionally stops at validating RECAST's temporal graph model; the paper's opportunistic-routing and Facebook studies remain application-level evaluations.