abm_liv Documentation

Developer Guide

This guide provides information for both contributing to the abm_liv project, and for adjusting the existing program to suit your own needs.

Contributing on GitHub

Here are the basic steps required to contribute to existing code.

  1. Install git on your system.

  2. Fork the abm_liv repository to your GitHub account and get the source code using:

    git clone https://github.com/<your_username>/abm_liv
cd abm_liv

  3. Look at the Known Bugs section to get inspiration for code contributions.

  4. Submit a pull request to GitHub. Guidance may be found here: https://opensource.guide/how-to-contribute/

Customising the Code

The program has been written to provide several simplistic methods for customisation as the user requires. Some basic customisation has been self contained within the main.py script.

  • Customising the geographic area of interest.

    • The bounds variable reads a shapefile called bounds.gpkg contained within the data directory. This file may be changed by placing a different Geopackage polygon in this location with a matching name. Note that for the model to run, the data_clean.py script must be ran first.

    • Additionally, a *.shp polygon may be used, but the name and location must be edited when the bounds variable is assigned in both the main.py, data_clean.py and api.py scripts.

    • NOTE: Ensure that projections are correct when reading in new shapefiles. The default crs used is British National Grid (EPSG: 27700). Police api data comes with a mercator projection (EPSG: 4326).

  • Adding Class level functions.

    • Additional functions may be added to either the crime.py or police.py scripts. These should be contained within the respective class and appended below existing functions.

An example function added to the crime.py crime Class could take the form:

def shift(self):
   if random.random < 0.5:
       self.x + 1
       self.y + 1

This would cause a crime to randomly move a small distance every so often. This function should then be added to the update function in the main.py script. In the section:

for c in self.crime_list:
    c.solve(self.police_list)
    c.shift()
  • Changing the selection of crime points from police.uk API.

    • The api.py script contains the variable months which may be edited to change the selection of crimes.

The line that requires editing is:

months = pd.date_range('2018-02-01', '2018-02-01',
                       freq='MS').strftime("%Y-%m").tolist()

Known Bugs

  1. At present the plot cannot be cleared with every iteration. If fig.clear() or equivalent is added to the update function, the plot will never render. This causes severe performance issues when more than 10 iterations are used.