# Readme

This data is the result of code written to run simulations of a problem called Cost Function Firefighter, a variant of The Firefighter Problem (see
survey by Finbow and MacGillivray [1]) available at [github.com/Ethan-CS/CostFnFire](https://github.com/Ethan-CS/CostFnFire). We implement four cost functions (some with variable amount of stochasticity)
and three main heuristics, each of which can be combined with another heuristic to break ties. These data are presented
in an extended version (under review) of a conference paper by Hunter and Enright [2].

We provide contact graph files and results of simulations used to produce the plots in the extended publication in CSV format. We also provide the protection strategies, cost mappings and overall performance metrics for transparency and verification.

Simulations are based on the following experimental design.

## Heuristic strategies

Heuristics create strategies by selecting vertices per turn greedily with respect to:
1. **Highest degree**
2. **Lowest cost**
3. **Highest threat** (proximity to fire)

We also implement a strategy that defends randomly for comparison.

## Cost functions

We implemented the following cost functions:
1. **Uniform** - defaults to 1 for all vertices
2. **Uniformly random** - costs chosen uniformly at random from the specified or default range [1,5]
3. **Binary hesitation** - costs are 2 with probability given probability (defaults to 29.72%, to model average rate of 
   vaccine hesitancy reported by Pourrazavi _et al._ [3]), 1 otherwise
4. **Threat with stochasticity** - costs are proportional to the threat of the vertex (proximity to fire), with random 
   noise added to each cost by adding an integer from the specified range

## Repository Structure

Results are organised by cost function as directory, e.g. for heuristic performance on random geometric graphs with binary hesitancy-defined cost functions, the directory is: `simulation_results>hesitancy-binary>random_geometric`. In this and all other graph class directories, the four files included are:
1. `cost_mappings.csv` - gives the root and mappings of costs to vertices under this cost function, for verification of results.
2. `degrees.csv` - each row is a list of degrees for each graph generated (or the single graph read-in from a CSV), for convenience e.g. if analysing degree distributions.
3. `results.csv` - **the main results file,** in which each row contains the result of a trial and contains:
	- the name of the graph class, 
	- number of vertices, 
	- generation parameter, 
	- random generation seed, 
	- outbreak vertex (which was randomly selected), 
	- budget, 
	- cost function, 
	- heuristic, and 
	- number of vertices saved at containment of fire.
4. `strategies.csv` - for verification of results, contains the strategies used to save the number of vertices indicated in the main results file.

## Graphs used

Information about the graphs and particularly the contact graph data files.

### Formatting

Files are saved as CSV files. This repo contains two contact graph adjacency files, used for simulations in the publication

### Raccoons

- Filename: `mammalia-raccoon-proximity.csv`
- From: [Network Data Repository](https://networkrepository.com/mammalia-raccoon-proximity.php), [original source](https://bansallab.github.io/asnr/data.html)
- Used in citation: Reynolds, Jennifer JH, et al. "Raccoon contact networks predict seasonal susceptibility to rabies
  outbreaks and limitations of vaccination." Journal of Animal Ecology 84.6 (2015): 1720-1731.
- Extra data:
    - Third column: weights for edges
    - Fourth column edge timestamps.

### Lizard Social Network

Sleepy Lizard population in Australia. Two lizards were assumed to had made a social contact if they were within 2 m of
each other at any of the synchronised 10 min GPS locations.

- Filename: `reptilia-lizard-network-social.csv`
- From: [Network Data Repository](https://networkrepository.com/reptilia-lizard-network-social.php), [original source](https://bansallab.github.io/asnr/data.html)
- Used in citation: Bull, C. M., S. S. Godfrey, and D. M. Gordon. "Social networks and the spread of Salmonella in a
  sleepy lizard population." Molecular Ecology 21.17 (2012): 4386-4392.


### Random graphs

We used four classes of random graphs for simulations, generated using NetworkX: Erdos-Renyi, Barabasi-Albert, geometric and regular graphs. Graph data is included in the output data files. For random graphs, we store degrees (`degrees.csv`) of each vertex for each graph and also the random generation seed (as a column in each `results.csv` file) so each graph can be reproduced using NetworkX.


### Method

For each graph class, cost function and heuristic pair, we performed 50 trials. For each trial, we randomly select an outbreak vertex; for random graphs, we generate a new graph for each trial.


References
----------
[1]: Finbow, S. and MacGillivray, G. _The Firefighter Problem: a survey of results, directions and questions._ 
     Australasian Journal of Combinatorics. 43 (2009): 57-78.

[2]: Hunter, E. and Enright, J. (2024) _The Firefighter Game with State-varying Cost Functions._ In: 13th International Conference on Complex Networks and their Applications 
	 (COMPLEX NETWORKS 2024), Istanbul, Turkey, 10-12 December 2024, (in press as of 28/03/2025)

[3]: Pourrazavi S., Fathifar Z., Sharma M., Allahverdipour H. _COVID-19 vaccine hesitancy: A Systematic review of 
     cognitive determinants._ Health Promotion Perspect. 2023 Apr 30;13(1):21-35. doi: 10.34172/hpp.2023.03. 
     PMID: 37309435; PMCID: PMC10257562.