I work on a URAP project building an agent-based simulation of how people evacuate high-rise residential buildings during a fire. Full-scale evacuation experiments under real fire conditions are neither ethical nor practical, so egress performance has to be assessed in simulation — and existing tools (Pathfinder, BuildingEXODUS, PyroSim) model smoke and bodies well while modelling decisions barely at all. Our premise is that occupants should be persona-conditioned cognitive agents: they perceive, interpret, talk to each other, and choose.
Nothing in the project said what a persona was. That is the piece I built.
What I Built
egress-personas turns a hand-maintained Google Sheet of literature-backed parameters into a reproducible population of residents for a 27-floor tower — households, social ties, dispositions, commitments, and a readable text card per person. A run emits four things: the lean JSON contract a simulation loads, a provenance file recording every number's derivation, a human-readable report, and the narrative cards.
A persona is six blocks, each answering to one of the project's four behaviour categories: who someone is, their physical stats, where they are and whether they are asleep, how well they know the building, their dispositions (milling, seeking confirmation, compliance, altruism, leadership), and their commitments — the cat, the toddler, the documents, each with a delay attached.
Adding a parameter is one row in a spreadsheet and no code. A typo is an error with a cell reference and a suggestion, never a row that silently does nothing.
The Hard Parts
Reproducibility against a living document. The Sheet is collaboratively edited and changes under you; a generator has to be reproducible. Resolved by snapshotting: personas pull refreshes a committed CSV snapshot and personas build reads the snapshot and never the network, so every run names the exact revision it came from, and pulling is a commit whose diff shows what moved.
One change moving one thing. Every random draw comes from its own stream keyed by a content hash of a stable path, never an array index — so editing one hand-authored case cannot shift another resident's numbers. Two things genuinely are population-level and do move: membership, and the repair passes that enforce building-wide shares. The determinism tests assert that boundary rather than a cleaner claim that would not be true.
Targets that contradict each other. Census household sizes imply 1.99 people per household; large San Francisco buildings run nearer 1.66 per flat. I reconciled them with an exponential tilt whose single parameter is reported (θ = 0.69) rather than by quietly editing either number. Tenure and age constrain each other — somebody of 22 cannot have lived somewhere five years — so tenure bands are fitted by iterative proportional fitting instead of drawn independently. And since a child needs an adult in the flat, the under-18 share and the occupancy target bound each other; when a target is unreachable the report prints the arithmetic ceiling.
Noise versus bias. A share measured over twenty-five occupants moves four percentage points when one person changes. Every target carries a standard error and a z-score so the report can separate "outside tolerance but within noise" from "the sampler is actually off."
From a Heuristic to a Number a Model Acts On
The registry gives a resident dispositions and knowledge. No egress simulation reads any of that — what simulations read is a pre-movement time, a walking speed, a queue patience, a smoke turn-back threshold. Bridging that gap is the part I find most interesting, and the mechanism is one sentence:
The literature keeps the shape of the population; the persona decides who is early and who is late.
A persona could be handed an absolute pre-movement time, but that throws away Lovreglio's Weibull fit — 149 and 78 observations — and substitutes a guess. Instead I compose a score from weighted traits, rank it within the population, and read the value off the published fit at that quantile. The realized mean lands on the published one to within 1%, and the ordering becomes something the model can explain.
That check validates the plumbing, not the weights. Ranks are uniform by construction, so the published distribution comes out right for any scoring function — including one with the signs reversed. I say so in the reports, because the alternative is a validation figure doing work it has not earned.
Engines are adapters, not code: a TOML file maps canonical outputs to one simulation's field names and lists what that engine cannot use. A new engine is a file.
The Result I Did Not Expect
The most valuable thing this has produced is not a model of people. It is a measurement of how little is known about them.
Every parameter carries SOURCED, ESTIMATE or INVENTED — the same three words the simulation's own provenance layer uses, so the two speak one language. Tracing end to end, from a heuristic through a persona field through an effect to a quantity the engine reads, 34 of 42 chains reach the simulation: 2 sourced, 20 estimates, 12 invented. Each chain is labelled by its weakest link, because a value read off a sourced distribution at a quantile decided by an invented ordering is invented, not sourced. Reporting it otherwise would launder a guess into a citation.
The individual heuristics look better — 7 of 31 are sourced — and the end-to-end view is worse precisely because it refuses to credit a strong source carried by a weak mechanism.
That number is not good, and nobody had it before. It is also the list that says what to do next: the sensitivity analysis that would tell us which of those guesses actually matter is the semester's main deliverable, and everything else is in service of it.
Reading the Output
A population JSON is a good contract and a poor thing to read, so there are two ways to look at who the sampler produced. personas show samples somebody and prints them in the terminal — their card, the blocks the simulation will act on, who they would reach for, and which paper each number came from. personas explore writes a self-contained page: the tower floor by floor, a filtered resident list, the selected person's card, and their ties drawn as a graph you can click through. It embeds the population and the source list, so it opens from disk and can be sent to someone without the repository.
Following the ties is the point — who could pass a warning to whom, and who would hear from nobody.
The repository depends on jsonschema and nothing else. Sheets arrive as CSV over urllib; the generator and its distributions are pure Python.