After years of research into how people actually experience places, I’m excited to announce the release of Chora version 1.0—the first Python library designed specifically for place-based computing.
Traditional GIS treats place as a problem of geometry: polygons, points, and coordinates. But anyone who has ever had a favorite coffee shop, a childhood park that feels like home, or a street they avoid at night knows that place is fundamentally about experience. Chora bridges this gap by providing computational tools to model, analyze, and understand place as it is actually lived by people.
What Makes Chora Different?
Chora is built on a simple but powerful insight: places are not containers in space; they are emergent phenomena arising from repeated encounters, practices, and affective responses. This isn’t just philosophy—it’s a computationally tractable framework based on rigorous theory from GIScience, cognitive geography, and social physics.
The library models places as platial graphs where nodes represent encounters, familiarity, practices, and affect, all connected through relational edges. Unlike coordinate-based systems, Chora embraces four theoretical principles:
- Relational primacy — Places are defined by relationships between agents and spatial extents, not by coordinates alone
- Encounter-centric — Every place experience begins with an atomic encounter event
- Temporal decay — Familiarity and place identity fade without reinforcement over time
- Epistemic separation — Different agents construct different places at the same location
This foundation enables Chora to answer questions that conventional GIS cannot: How does familiarity develop over time? Which places constitute someone’s routine? Why do different people experience the same location differently?
Core Capabilities
GPS Traces to Meaningful Places
Transform raw location data into meaningful place experiences. Chora can process GPS traces (GPX, GeoJSON, CSV) and automatically detect stops, classify visits, and build familiarity networks. This goes beyond simple clustering—it models how repeated visits create place identity over time.
from chora.core import PlatialGraph, Agent, SpatialExtent, Encounter
from chora.derivation import update_familiarity
# Create a platial graph
graph = PlatialGraph("My City")
# Define an agent and a place
alice = Agent.individual("Alice")
park = SpatialExtent.from_point(-0.127, 51.507, "Hyde Park")
# Record an encounter
encounter = Encounter(
agent_id=alice.id,
extent_id=park.id,
timestamp="2026-02-07T14:30:00"
)
graph.add_node(encounter)
# Derive familiarity over time
update_familiarity(graph, encounter)Detecting Routines and Practices
Identify habitual patterns in movement data. Chora’s practice detection algorithms find recurring visit patterns, regular routes, and routine behaviors that define how people actually use places.
# CLI workflow for routine detection
chora load gpx trace.gpx --agent alice
chora derive familiarity --agent alice
chora derive practices --agent aliceAffective Mapping
Map emotions and sentiments to locations. Chora supports affective tagging of encounters, allowing you to build emotional geographies that capture how different places make people feel.
H3 Hexagonal Spatial Indexing
Leverage Uber’s H3 hexagonal grid system for efficient spatial analysis. Chora integrates H3 indexing natively, enabling multi-resolution spatial aggregation and neighbor queries that respect the geometry of place.
Vibe Search with Embeddings
Find places by semantic description using vector embeddings. Rather than searching by category or proximity, ask questions like “quiet peaceful park for reading” and let Chora find matches based on experiential similarity.
from chora.search import vibe_search
results = vibe_search(
graph,
"quiet peaceful park for reading"
)
# Returns: [(park, 0.87), (garden, 0.72), ...]LLM Integration for Place Narratives
Generate natural language descriptions of place experiences using large language models. Chora can produce human-readable narratives that explain why a place matters to someone, what routines connect to it, and how it fits into their broader spatial biography.
Real-Time Streaming
Process live GPS traces and detect place events in real-time. Chora’s streaming module can detect dwelling events (stopping at a location), create encounter nodes on-the-fly, and emit events via WebSocket or webhook—perfect for tracking ongoing fieldwork or building location-aware applications.
Built for Research and Practice
Chora is designed to serve multiple communities:
Academic Researchers working in human geography, environmental psychology, mobility studies, or GIScience will find Chora provides a rigorous computational framework grounded in established theory. The library’s emphasis on encounters, temporal decay, and relational primacy aligns with contemporary place theory.
Data Scientists and Analysts processing location data can use Chora to move beyond basic clustering and heat maps. The library provides tools for extracting meaningful patterns from GPS traces, social media check-ins, or mobile phone records.
Urban Planners and Designers interested in how people actually use cities can leverage Chora’s routine detection and practice derivation to understand functional patterns that official land use maps might miss.
Digital Humanists working with historical itineraries, literary geographies, or spatial narratives can use Chora to model how places were experienced across time and by different historical actors.
Installation and Getting Started
Install Chora via pip:
pip install chora-geoThe library includes both a Python API and a comprehensive CLI tool for common workflows. Full documentation, tutorials, and API reference are available at jwilliams.science/chora.
Quick Start Tutorial
The Getting Started guide walks through creating your first platial graph, loading GPS data, and deriving familiarity relationships. It takes about 15 minutes and requires no prior knowledge of place theory.
Comprehensive Guides
Detailed guides cover specific use cases:
- GPS to Places — Process traces into meaningful places
- Affective Mapping — Map emotions to locations
- Detecting Routines — Find habits and patterns
- Visualization — Create D3.js graphs and reports
- H3 Indexing — Hexagonal spatial analysis
- Real-Time Streaming — Process live GPS data
Theoretical Foundation
Chora is not a black box. The Theory section of the documentation explains the conceptual foundations in detail, including the mathematical models for temporal decay, the graph structures underlying platial representation, and the epistemological commitments that shape the API design.
This theoretical grounding serves two purposes: it makes the library’s behavior predictable and interpretable, and it provides academic researchers with a clear basis for citing and building upon Chora in their own work.
Roadmap and Future Development
Version 1.0 represents a major milestone, including H3 indexing, vector embeddings, LLM integration, and real-time streaming. But Chora is actively evolving:
- v2.0 (in development) — Social physics models for collective place-making, digital twin integration for urban simulation
- Community contributions — As an open-source project under MIT license, Chora welcomes contributions, feature requests, and collaborative development
Start Modeling Place Today
Chora represents a shift in how we computationally understand place—from containers in space to emergent experiences built through encounter, practice, and affect. Whether you’re analyzing GPS traces from fieldwork, building location-aware applications, or researching human spatial behavior, Chora provides the tools to model place as it is actually lived.
Install the library, explore the documentation, and start asking different questions about place:
- Documentation: jwilliams.science/chora
- GitHub: github.com/jameswilliamsresearch/chora
- Installation:
pip install chora-geo
Welcome to place-based computing. Welcome to Chora.
Questions, feedback, or collaboration ideas? Connect with me via the contact page or open an issue on the GitHub repository.
