This project performs a migration analysis using a NetLogo model to simulate migration patterns based on place attachment levels. The analysis includes setting up experiments, running simulations, generating visualizations, and creating summary reports.
- Python 3.x
- NetLogo 6.x
- Required Python packages:
numpy,pandas,seaborn,matplotlib,pyNetLogo
- Clone the repository :
git clone https://github.com/gabemgem/migration-place-attachment- Install Python dependencies :
pip install numpy pandas seaborn matplotlib pyNetLogo- Download and install NetLogo :
- Download NetLogo from NetLogo's official website.
- Install NetLogo following the ins 8000 tructions for your operating system.
migration-analysis.py: Main Python script to run the migration analysismigration_place_attachment_model.nlogo: NetLogo model file defining the migration simulationshock_visualization.py: Standalone module for visualizing shock effectsanalyze_shock_interactions.py: Script for analyzing shock interaction effectsREADME.md: This readme filespec.md: Technical specification and implementation details
- Prepare the NetLogo model :
- Ensure the
migration_place_attachment_model.nlogofile is in the same directory as themigration-analysis.pyscript.
-
Run the analysis :
python migration-analysis.py
-
Output :
- The script will generate visualizations and save them as PNG files.
- The raw data and summary report will be saved as CSV files.
Here is an example of how to run the migration analysis:
python migration-analysis.py
The script will perform the following steps:
- Load the NetLogo model.
- Set up and run experiments with different attachment levels.
- Generate visualizations of the results.
- Create a summary report with correlations and summary statistics.
- Save the results to files.
This script contains the MigrationAnalyzer class, which handles the entire analysis process:
- Initialization :
analyzer = MigrationAnalyzer(model_path)- Setup and run experiments :
analyzer.setup_experiment(attachment_levels=np.linspace(0, 1, 10))
analyzer.run_experiments(n_iterations=10)- Generate visualizations and report :
fig = analyzer.visualize_results()
report = analyzer.generate_report()
- Save results :
timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
fig.savefig(f'migration_patterns_{timestamp}.png')
report['raw_data'].to_csv(f'migration_results_{timestamp}.csv')
- Cleanup :
analyzer.cleanup()
This NetLogo model defines the simulation environment, including agents (people and places), their properties, and behaviors. The model includes procedures for setting up the simulation, running it, and reporting results.
A standalone module for visualizing shock effects across different attachment levels. The module is framework-agnostic and can be used with any data source that follows the specified format.
Key Features:
- Independent from main simulation pipeline
- Supports both JSON and CSV input formats
- Generates comparative visualizations of individual vs place shock effects
- Includes error bars and statistical summaries
- Command-line interface for batch processing
- Importable as a Python module for custom analysis workflows
Usage Examples:
from shock_visualization import visualize_shock_effects
# Basic usage - save to file
visualize_shock_effects('experiment_data.json', 'shock_effects.png')
# Advanced usage - get figure for customization
fig = visualize_shock_effects('experiment_data.json')
fig.axes[0].set_title('Custom Title')
fig.savefig('custom_shock_effects.png')The module accepts JSON or CSV files with the following structure:
{
"experiments": [
{
"shock_type": "individual|place",
"mean_attachment": <float>,
"avg_satisfaction_shocked": <float>,
"avg_satisfaction_not_shocked": <float>,
"avg_moves_shocked": <float>,
"avg_moves_not_shocked": <float>,
"n_shocked": <int>,
"n_not_shocked": <int>
}
],
"metadata": {
"date": "YYYY-MM-DD",
"shock_probability": {"individual": <float>, "place": <float>},
"shock_magnitude": {"individual": <float>, "place": <float>}
}
}For CSV format, include the same fields as columns.
python shock_visualization.py data.json -o shock_effects.pngThis script analyzes aggregated results (specifically those containing RCT metrics like avg_satisfaction_shocked) to visualize how the effect of attachment shocks interacts with other parameters, particularly mean_attachment.
Functionality:
- Reads an aggregated results CSV file.
- Calculates the difference in outcomes (satisfaction and moves) between agents who experienced shocks and those who didn't (
satisfaction_diff,moves_diff). This represents the Average Treatment Effect (ATE) of the shock. - Automatically identifies potential parameter columns in the CSV (excluding known metric/shock/attachment columns).
- Groups the data based on unique combinations of these identified parameters.
- For each parameter combination (group), it generates and saves a faceted plot (
shock_interaction_group_*.png). This plot shows:- The calculated ATE (
satisfaction_diffandmoves_diff) on the y-axis. - The
mean_attachmentlevel on the x-axis. - Points colored by the
individual_shock_probability. - Separate columns for the effect on 'Satisfaction' and 'Moves'.
- This visualization helps understand how the impact of shocks (ATE) changes depending on the baseline attachment level and the probability of the shock itself, within specific experimental conditions defined by the other parameters.
- The calculated ATE (
Prerequisites:
- Python 3.x
- Required Python libraries:
pandas,matplotlib,seabornpip install pandas matplotlib seaborn
Input Data:
- A CSV file containing aggregated simulation results. This file must include:
- The shock probability column (e.g.,
individual_shock_probability). - The mean attachment column (e.g.,
mean_attachment). - The RCT outcome metric columns (
avg_satisfaction_shocked,avg_satisfaction_not_shocked,avg_moves_shocked,avg_moves_not_shocked). - Columns for all other parameters that define the different simulation runs.
- The shock probability column (e.g.,
Configuration:
Before running, edit analyze_shock_interactions.py and configure the following variables:
INPUT_CSV: (Required) Set the path to your specific aggregated results CSV file.OUTPUT_DIR: (Optional) Change the directory name for saved plots (default:shock_interaction_graphs_v2).SHOCK_PROB_COL,ATTACHMENT_COL,SAT_SHOCKED_COL, etc.: (Verify) Ensure these match the exact column names in your CSV.NON_PARAMETER_COLS: (Optional) Review this list. Add any other column names from your CSV that should not be treated as parameters for grouping (e.g., run IDs, iteration counters, specific metric columns not used for grouping).
Running the Script:
- Ensure your results CSV file exists and the path in
INPUT_CSVis correct. - Verify the column name configurations in the script match your data file.
- Run from the terminal:
python analyze_shock_interactions.py
Output:
- Log messages printed to the console, including the list of automatically identified parameter columns.
- A directory named
shock_interaction_graphs_v2(or your configured name). - Inside the output directory:
- One PNG image file (
shock_interaction_group_*.png) for each unique combination of the automatically identified parameters, where*is a numerical index. Each plot shows the interaction effect of shocks and attachment on satisfaction and moves for that specific parameter setting. - A CSV file named
group_parameter_mapping.csvthat links eachgroup_index(used in the PNG filenames) to the specific parameter values defining that group.
- One PNG image file (
- Ensure that NetLogo is correctly installed and the path to the NetLogo executable is correctly set in your environment.
- Verify that all required Python packages are installed.
- Check for any error messages in the console and address them accordingly.
Contributions are welcome! Please fork the repository and submit a pull request with your changes.
This project is licensed under the MIT License. See the LICENSE file for details.
- NetLogo: NetLogo
- Python: Python
For any questions or issues, please open an issue on the GitHub repository.