Example: Anchor Queries

Behavioral Pathways only processes events that occur after an entity's anchor for forward queries. Events before the anchor are ignored unless you query backward in time. This example shows the behavior and two ways to handle it.

Scenario

We model a person with a childhood trauma that occurred before they enter the simulation. We show how that event is excluded by default and how to include its effects.

Step 1: Anchor After the Event (Event Ignored)

// Anchor at age 20
use behaviorsim_rs::entity::EntityBuilder;
use behaviorsim_rs::enums::{EventPayload, EventType, Species};
use behaviorsim_rs::event::EventBuilder;
use behaviorsim_rs::simulation::Simulation;
use behaviorsim_rs::types::{Duration, EntityId, Timestamp};

let john = EntityBuilder::new()
    .id("john")
    .species(Species::Human)
    .age(Duration::years(20))
    .build()?;
let john_id = EntityId::new("john").unwrap();

let trauma = EventBuilder::new(EventType::ExperienceShamingPublic)
    .target(john_id.clone())
    .severity(0.9)
    .payload(EventPayload::Humiliation {
        public: true,
        perpetrator: None,
    })
    .build()?;

let anchor = Timestamp::from_ymd_hms(2010, 1, 1, 0, 0, 0);
let mut sim = Simulation::new(anchor);
sim.add_entity(john, anchor);

// Trauma at age 5 (before anchor)
sim.add_event(trauma, Timestamp::from_ymd_hms(1995, 3, 15, 0, 0, 0));

// Query forward from anchor
let state = sim.entity(&john_id).unwrap().state_at(anchor);
// Trauma NOT included

Solution A: Anchor Earlier

// Anchor before trauma
let early_anchor = Timestamp::from_ymd_hms(1995, 1, 1, 0, 0, 0);
let mut sim = Simulation::new(early_anchor);
sim.add_entity(john, early_anchor);

// Trauma now occurs after anchor
sim.add_event(trauma, Timestamp::from_ymd_hms(1995, 3, 15, 0, 0, 0));

// Query later in life
let state = sim
    .entity(&john_id)
    .unwrap()
    .state_at(Timestamp::from_ymd_hms(2010, 1, 1, 0, 0, 0));
// Trauma included

Solution B: Set Initial State

use behaviorsim_rs::state::{Mood, SocialCognition};

let john = EntityBuilder::new()
    .id("john")
    .species(Species::Human)
    .age(Duration::years(20))
    .mood(Mood::new().with_valence_base(-0.2))
    .social_cognition(SocialCognition::new().with_loneliness_base(0.4))
    .build()?;

let anchor = Timestamp::from_ymd_hms(2010, 1, 1, 0, 0, 0);
let mut sim = Simulation::new(anchor);
sim.add_entity(john, anchor);
// Trauma effects baked into baseline

Key Rule

Events before the anchor only affect results if you query a time before the anchor. For forward queries, only events after anchor matter.