Chapter 6 API Reference
This chapter provides detailed documentation for all functions in the ASA ABM v2. Functions are organized by module with complete specifications.
6.1 Core Modules
6.1.1 core/organization.R
Functions for creating and managing organizations.
6.1.1.1 create_organization()
Create an organization data.table with agents.
Usage
Arguments
- n_agents
: Number of agents to create (default: 100)
- identity_categories
: Vector of possible identity categories
Value
Returns a data.table with columns:
- agent_id
: Unique identifier
- identity_category
: Agent’s identity group
- openness
, conscientiousness
, extraversion
, agreeableness
, emotional_stability
: Big Five traits
- homophily_preference
, diversity_preference
: Agent preferences
- attraction
, satisfaction
: State variables
- tenure
, hire_date
, is_active
: Employment tracking
Examples
6.1.1.2 calculate_identity_diversity()
Calculate Shannon entropy for identity diversity.
Usage
Arguments
- org
: Organization data.table
Value Returns numeric Shannon entropy value (0 = homogeneous, higher = more diverse)
6.1.1.3 calculate_blau_index()
Calculate Blau’s Index of heterogeneity for identity categories (I-O psychology standard).
Usage
Arguments
- org
: Organization data.table
Value Returns numeric Blau’s Index (0 = homogeneous, 1 = maximum diversity). Represents the probability that two randomly selected members are from different categories.
6.1.1.4 get_category_proportions()
Get proportions of each identity category.
Usage
Arguments
- org
: Organization data.table
Value Returns named vector with proportions for each category (A-E)
Usage
Arguments
- org
: Organization data.table
Value
Numeric Shannon entropy value (0 = homogeneous, higher = more diverse)
Examples
6.1.1.5 calculate_personality_averages()
Get mean personality traits for active employees.
Usage
Arguments
- org
: Organization data.table
Value
Numeric vector of trait means in order: openness, conscientiousness, extraversion, agreeableness, emotional_stability
6.1.1.6 calculate_personality_variance()
Get standard deviations of personality traits.
Usage
Arguments
- org
: Organization data.table
Value
Numeric vector of trait SDs
6.1.1.7 get_organization_size()
Count active employees.
Usage
Arguments
- org
: Organization data.table
Value
Integer count of employees where is_active == TRUE
6.1.1.8 calculate_average_satisfaction()
Compute mean satisfaction of active employees.
Usage
Arguments
- org
: Organization data.table
Value
Numeric mean satisfaction score
6.1.1.9 get_organization_summary()
Generate comprehensive organizational metrics.
Usage
Arguments
- org
: Organization data.table
Value
List containing:
- size
: Active employee count
- identity_diversity
: Shannon entropy
- avg_satisfaction
: Mean satisfaction
- avg_tenure
: Mean tenure
- personality_means
: Vector of trait means
- personality_sds
: Vector of trait SDs
- turnover_rate
: Proportion inactive
6.1.2 core/agent.R
Functions for managing applicant pools.
6.1.2.1 create_applicant_pool()
Generate pool of potential applicants.
Usage
Arguments
- n_applicants
: Number of applicants to generate
- identity_categories
: Possible identity categories
Value
data.table with applicant information including unique IDs and application_time field
Examples
6.1.2.2 calculate_applicant_attraction()
Calculate attraction scores for applicants.
Usage
Arguments
- applicants
: Applicant pool data.table
- org
: Organization data.table
- diversity_metric
: Character string specifying which diversity metric to use (“blau” or “shannon”, default: “blau”)
Value
Updated applicants data.table with attraction scores based on identity fit and diversity
Examples
6.1.2.3 filter_applicant_pool()
Remove applicants below attraction threshold.
Usage
Arguments
- applicants
: Applicant pool data.table
- min_attraction
: Minimum attraction score to remain
Value
Filtered applicants data.table
6.1.2.4 age_applicant_pool()
Increment application time and remove stale applications.
Usage
Arguments
- applicants
: Applicant pool data.table
- max_application_time
: Maximum time before removal
Value
Updated applicants with incremented time and stale applications removed
6.1.3 core/interactions.R
Functions for agent interactions and satisfaction.
6.1.3.1 initialize_interactions()
Create empty interactions tracking table.
Usage
Arguments
- org
: Organization data.table
Value
Empty data.table with columns: focal_agent, partner_agent, time_step, valence
6.1.3.2 execute_interactions_vectorized()
Perform one round of interactions using vectorized operations.
Usage
Arguments
- org
: Organization data.table
- interactions
: Interaction history table
- time_step
: Current simulation time
- n_interactions
: Interactions per agent
Value
Updated interactions table with new interaction records
Details
Interaction valence calculated as:
valence = -|ΔExtraversion| + (Consc_focal - Extra_partner) +
Agree_focal + IdentityBonus + ε
Where IdentityBonus depends on homophily/diversity preferences and identity match.
6.1.3.3 update_satisfaction_vectorized()
Update all agent satisfaction scores efficiently.
Usage
Arguments
- org
: Organization data.table
- interactions
: Interaction history
- window_size
: Recent time steps to consider
- diversity_metric
: Character string specifying which diversity metric to use (“blau” or “shannon”, default: “blau”)
Value
Updated organization with new satisfaction scores
6.1.3.4 get_interaction_summary()
Summarize recent interaction patterns.
Usage
Arguments
- interactions
: Interaction history table
- last_n_steps
: Number of recent steps to analyze
Value
List with summary statistics:
- total_interactions
: Count
- avg_valence
: Mean interaction quality
- sd_valence
: Valence standard deviation
- n_unique_pairs
: Unique interaction pairs
6.1.4 simulation/hiring.R
Functions for recruitment and selection.
6.1.4.1 execute_hiring()
Main hiring process function.
Usage
execute_hiring(org, applicant_pool, growth_rate = 0.1,
selection_criteria = "conscientiousness",
current_time = 0)
Arguments
- org
: Organization data.table
- applicant_pool
: Available applicants
- growth_rate
: Proportion of current size to hire
- selection_criteria
: “conscientiousness”, “fit”, or “random”
- current_time
: Current simulation time
Value
List containing:
- organization
: Updated with new hires
- applicant_pool
: Remaining applicants
Examples
6.1.4.2 recruit_applicants()
Generate new applicants or add to existing pool.
Usage
recruit_applicants(existing_pool = NULL, n_new_applicants = 50,
identity_categories = c("A","B","C","D","E"))
Arguments
- existing_pool
: Current applicant pool (optional)
- n_new_applicants
: Number to generate
- identity_categories
: Possible identities
Value
Updated applicant pool data.table
6.1.4.3 calculate_fit_metrics()
Calculate person-organization fit scores.
Usage
Arguments
- org
: Organization data.table
- applicants
: Applicant pool
Value
Applicants with added fit metrics:
- personality_fit
: Based on trait distance
- preference_fit
: Based on preference alignment
- overall_fit
: Combined fit score
6.1.5 simulation/turnover.R
Functions for managing attrition.
6.1.5.1 execute_turnover()
Remove employees below satisfaction threshold.
Usage
Arguments
- org
: Organization data.table
- turnover_threshold
: Satisfaction threshold
- current_time
: Current simulation time
Value
Updated organization with low-satisfaction employees marked inactive
6.1.5.2 calculate_turnover_probability()
Compute probabilistic turnover likelihood.
Usage
Arguments
- org
: Organization data.table
- base_turnover_rate
: Baseline probability
- satisfaction_weight
: Impact of satisfaction
Value
Organization with added turnover_prob
column
6.1.5.3 execute_probabilistic_turnover()
Execute turnover based on probabilities.
Usage
Arguments
- org
: Organization with turnover probabilities
- current_time
: Current simulation time
Value
Updated organization after probabilistic departures
6.1.5.4 update_tenure()
Increment tenure for active employees.
Usage
Arguments
- org
: Organization data.table
- time_increment
: Time units to add
Value
Organization with updated tenure values
6.1.6 simulation/engine.R
Main simulation control functions.
6.1.6.1 run_asa_simulation()
Execute complete ASA simulation.
Usage
Arguments
- n_steps
: Number of time steps
- initial_size
: Starting organization size
- params
: Simulation parameters (see details)
- verbose
: Print progress messages
Parameters List
params = list(
identity_categories = c("A","B","C","D","E"),
growth_rate = 0.01,
hiring_frequency = 12,
selection_criteria = "conscientiousness",
n_interactions_per_step = 5,
interaction_window = 10,
turnover_threshold = -10,
turnover_type = "threshold",
base_turnover_rate = 0.05,
n_new_applicants = 50,
applicant_attraction_threshold = -0.5,
max_application_time = 12,
diversity_metric = "blau" # "blau" or "shannon"
)
Value
List containing:
- final_organization
: End state
- metrics
: Time series data.table
- parameters
: Used parameters
- organization_snapshots
: Periodic saves
Examples
6.1.6.2 calculate_step_metrics()
Compute metrics for single time step.
Usage
Arguments
- org
: Organization data.table
- time_step
: Current time
Value
data.table row with comprehensive metrics
6.1.6.3 save_simulation_results()
Save simulation outputs to files.
Usage
Arguments
- results
: Simulation results list
- filename
: Base filename
- save_snapshots
: Whether to save snapshots
Details
Creates files:
- {filename}_metrics.csv
- {filename}_params.rds
- {filename}_final_org.csv
- {filename}_snapshots.rds
(optional)