Trait Operations
All trait operations return new instances (immutable pattern).
Adding Traits
python
# Single agent
agent = agent.add_trait("weight", 150)
agent = agent.add_trait({"weight": 150, "height": 5.5})
# AgentList - single value for all agents
agents = agents.add_trait("status", value="participant")
# AgentList - different values per agent (must match length)
agents = agents.add_trait("score", values=[85, 90, 78, 92])
Updating Traits
python
# Update existing trait value (raises error if trait doesn't exist)
agent = agent.update_trait("age", 31)
Removing/Dropping Traits
python
# Single agent
agent = agent.drop("temporary_id")
agent = agent.drop("temp1", "temp2")
agent = agent.remove_trait("age")
# AgentList
agents = agents.drop("temporary_id")
agents = agents.drop("temp1", "temp2", "temp3")
agents = agents.drop(["temp1", "temp2", "temp3"])
Keeping/Selecting Traits
python
# Single agent
agent = agent.keep("age", "occupation")
agent = agent.select("age", "occupation") # Alias
# AgentList
agents = agents.keep("age", "occupation")
agents = agents.select("age", "occupation") # Alias
Renaming Traits
python
# Single agent
agent = agent.rename("old_name", "new_name")
agent = agent.rename({"old1": "new1", "old2": "new2"})
# AgentList
agents = agents.rename("old_name", "new_name")
Translating Trait Values
python
# Convert coded values to readable ones
agents = agents.translate_traits({
"gender": {1: "male", 2: "female", 3: "other"},
"education": {1: "high school", 2: "bachelor", 3: "graduate"}
})
Converting String Traits to Numbers
python
# Automatically convert numeric strings to int/float agents = agents.numberify() # "30" → 30, "5.5" → 5.5, "NYC" → "NYC" (unchanged)
Filtering Agents
Filter using boolean expressions that reference trait values:
python
# Simple comparisons
young_agents = agents.filter("age < 30")
doctors = agents.filter("occupation == 'doctor'")
# Multiple conditions
young_doctors = agents.filter("age < 30 and occupation == 'doctor'")
# Using agent name
alice = agents.filter("name == 'Alice'")
# Numeric comparisons
high_earners = agents.filter("income > 100000")
Filtering NA Values
python
# Remove agents with any None/NaN values
clean_agents = agents.filter_na()
# Remove agents with None/NaN in specific traits
clean_agents = agents.filter_na("age")
clean_agents = agents.filter_na(["age", "income"])
Quick Reference
| Operation | Single Agent | AgentList |
|---|---|---|
| Add trait | agent.add_trait("key", value) | agents.add_trait("key", values=[...]) |
| Update trait | agent.update_trait("key", value) | N/A |
| Drop trait | agent.drop("key") | agents.drop("key") |
| Keep traits | agent.keep("k1", "k2") | agents.keep("k1", "k2") |
| Rename trait | agent.rename("old", "new") | agents.rename("old", "new") |
| Filter | N/A | agents.filter("age > 30") |
| Filter NA | N/A | agents.filter_na() |
| Translate | agent.translate_traits({...}) | agents.translate_traits({...}) |
| Numberify | N/A | agents.numberify() |