Chapter 10 ASA ABM v2 Quick Reference
10.1 Quick Start
# Load and run simulation
source("simulation/engine.R")
results <- run_asa_simulation(n_steps = 260, initial_size = 100)
# View results
tail(results$metrics, 10) # Recent metrics
summary(results$final_organization) # Final state
# Quick visualization
library(ggplot2)
ggplot(results$metrics, aes(x = time_step, y = organization_size)) +
geom_line()
10.2 Parameter Reference
Parameter | Type | Default | Range/Values | Description |
---|---|---|---|---|
n_steps |
int | 260 | 1-∞ | Simulation duration |
initial_size |
int | 100 | 1-10000 | Starting employees |
growth_rate |
num | 0.01 | 0-1 | Hiring growth per cycle |
hiring_frequency |
int | 12 | 1-52 | Steps between hiring |
selection_criteria |
chr | “conscientiousness” | “conscientiousness”, “fit”, “random” | Hiring strategy |
n_interactions_per_step |
int | 5 | 1-100 | Interactions per agent |
interaction_window |
int | 10 | 1-52 | Memory for interactions |
turnover_threshold |
num | -10 | -20-0 | Satisfaction exit level |
turnover_type |
chr | “threshold” | “threshold”, “probabilistic” | Attrition method |
base_turnover_rate |
num | 0.05 | 0-1 | Base attrition probability |
n_new_applicants |
int | 50 | 1-1000 | Applicants per cycle |
applicant_attraction_threshold |
num | -0.5 | -5-5 | Min attraction to apply |
max_application_time |
int | 12 | 1-52 | Applicant pool timeout |
diversity_metric |
chr | “blau” | “blau”, “shannon” | Diversity calculation |
identity_categories |
vec | c(“A”,“B”,“C”,“D”,“E”) | Any | Identity types |
10.3 Key Functions
10.3.1 Core Functions
# Organization Management
create_organization(n_agents, identity_categories)
get_organization_size(org)
get_active_employees(org)
calculate_blau_index(categories)
calculate_shannon_diversity(categories)
# Agent Creation
create_applicant_pool(n_applicants, identity_categories)
calculate_attraction(agents, org_diversity, diversity_metric)
create_agent(identity_category)
# Simulation Engine
run_asa_simulation(n_steps, initial_size, params, verbose)
execute_interactions_vectorized(org, interactions, step, n_interactions)
update_satisfaction_vectorized(org, interactions, window, diversity_metric)
execute_turnover(org, threshold, current_time)
execute_hiring(org, applicant_pool, selection_criteria, n_positions)
10.4 Data Structures
10.4.1 Organization Table
org <- data.table(
agent_id # chr: Unique ID "agent_XXX"
identity_category # chr: "A", "B", "C", "D", or "E"
openness # num: 0-1 (Big Five trait)
conscientiousness # num: 0-1 (Big Five trait)
extraversion # num: 0-1 (Big Five trait)
agreeableness # num: 0-1 (Big Five trait)
emotional_stability # num: 0-1 (Big Five trait)
homophily_preference # num: 0-1 (similarity preference)
diversity_preference # num: 0-1 (diversity preference)
attraction # num: -∞-∞ (to organization)
satisfaction # num: -∞-∞ (current satisfaction)
tenure # int: Steps in organization
hire_date # int: Step when hired
is_active # lgl: TRUE if employed
)
10.4.2 Metrics Output
metrics <- data.table(
time_step # int: Simulation step
organization_size # int: Active employees
prop_A - prop_E # num: Identity proportions
shannon_diversity # num: Shannon entropy
blau_index # num: Blau's index
avg_satisfaction # num: Mean satisfaction
sd_satisfaction # num: SD satisfaction
avg_openness # num: Mean trait value
sd_openness # num: SD trait value
# ... other personality traits
)
10.5 Common Code Patterns
10.5.2 Batch Analysis
# Extract final metrics
final_metrics <- lapply(results, function(r) {
tail(r$metrics, 1)
})
comparison <- rbindlist(final_metrics, idcol = "scenario")
# Time series comparison
all_metrics <- lapply(seq_along(results), function(i) {
results[[i]]$metrics[, scenario := names(scenarios)[i]]
})
combined <- rbindlist(all_metrics)
10.5.3 Custom Metrics
# Add to organization
org[, network_centrality := degree_centrality / (.N - 1)]
org[, cultural_distance := abs(conscientiousness - mean(conscientiousness))]
# Calculate in simulation
custom_metric <- org[is_active == TRUE,
.(cultural_variance = var(conscientiousness),
satisfaction_gini = ineq::Gini(satisfaction))]
10.6 Visualization Recipes
10.6.1 Time Series with Phases
ggplot(metrics, aes(x = time_step)) +
geom_line(aes(y = organization_size), size = 1.2) +
geom_vline(xintercept = c(50, 100, 150),
linetype = "dashed", alpha = 0.5) +
annotate("rect", xmin = 0, xmax = 50,
ymin = -Inf, ymax = Inf,
alpha = 0.1, fill = "blue") +
labs(title = "Organizational Growth",
x = "Time", y = "Size") +
theme_minimal()
10.6.2 Multi-Metric Dashboard
library(patchwork)
p1 <- ggplot(metrics, aes(time_step, organization_size)) +
geom_line(color = "blue")
p2 <- ggplot(metrics, aes(time_step, blau_index)) +
geom_line(color = "red")
p3 <- ggplot(metrics, aes(time_step, avg_satisfaction)) +
geom_line(color = "green")
p4 <- ggplot(metrics, aes(time_step, avg_conscientiousness)) +
geom_line(color = "purple")
(p1 + p2) / (p3 + p4) +
plot_annotation(title = "Simulation Dashboard")
10.7 Performance Tips
- Vectorize Everything: Use data.table operations, not loops
- Pre-allocate Memory:
vector("list", n_steps)
for results - Selective Updates: Use
:=
for in-place modifications - Index Key Columns:
setkey(org, agent_id)
for fast lookups - Avoid Copying: Pass by reference when possible
- Profile Code: Use
system.time()
andprofvis::profvis()
- Batch Operations: Group similar calculations
- Limit Snapshots: Store only necessary time points
10.8 Debugging Commands
10.8.2 Data Validation
# Check for NAs
org[, lapply(.SD, function(x) sum(is.na(x)))]
# Verify constraints
stopifnot(all(org$satisfaction > -100))
stopifnot(all(org$tenure >= 0))
# Test single step
test_org <- org[1:10] # Small subset
test_result <- execute_interactions_vectorized(
test_org, interactions, step = 1, n_interactions = 2
)
10.8.3 Performance Profiling
# Time specific operations
system.time({
for(i in 1:100) {
calculate_blau_index(org$identity_category)
}
})
# Memory usage
pryr::object_size(org)
gc() # Garbage collection
# Full profiling
profvis::profvis({
run_asa_simulation(n_steps = 50)
})
ASA ABM v2 - Agent-Based Model for Attraction-Selection-Attrition