The Analysis module of Pandora allows the user to calculate basic statistics generated from the data stored during a simulation. This tutorial will define how to use it using the Python interface of the framework. These analysis generate a set of csv files (Comma Separated Values) that can be loaded from any spreadsheet application (like LibreOffice Calc), as well as from several statistical packages (like R).
We will generate a basic dataset, and will try to load it afterwards. First of all let's create the simulation. Follow the tutorial (Link 01_GETTING_STARTED_PYPANDORA) and execute the simulation. It will create a folder called 'data' with the files 'results.h5' and 'agents-0.abm' in it. These files contain the data from rasters and agents collected during each time step.
To analyse the data, we need to create a new python program where we load the data into an instance of the class SimulationRecord. Create a file tutorial_pyAnalysis.py with the following content:
import sys,os
pandoraPath = os.getenv('PANDORAPATH', '/usr/local/pandora') sys.path.append(pandoraPath+'/bin') sys.path.append(pandoraPath+'/lib') from pyPandora import SimulationRecord
record = SimulationRecord() record.loadHDF5('data/results.h5', True, True)
These lines create a SimulationRecord and loads the file 'data/results.h5'.
The method loadHDF5 has three parameters. The first one is the file to be loaded. If the folder generated by the simulation is in another path please modify this parameter. The two other parameters allow the user to specify if agents and rasters must be loaded (flag set toTrue) or not (flag set to False).
Once that data is loaded, we will create a set of tools to analyze the agents, as well as the values of the rasters. This is done using classes such as GlobalAgentStats and GlobalRasterStats. They are useful to gather global statistics of the results (i.e. mean values of agent properties, sum of raster values, etc). There are other analysis, like AgentHistogram or Individual Stats that can be used to collect additional information about the output of our simulations (you can even create your own analysis, inheriting from Output base class).
The constructors of the analysis classes need to specify the token that we will use as separator:
agentResults = GlobalAgentStats(';') rasterResults = GlobalRasterStats(';')
We will add several analysis to both of them. Each analysis is a different class, and has a different set of parameters:
agentResults.addAnalysis(AgentNum()) agentResults.addAnalysis(AgentMean('x')) agentResults.addAnalysis(AgentMean('y')) agentResults.addAnalysis(AgentMean('resources')) agentResults.addAnalysis(AgentSum('resources'))
The first analysis stores the number of agents for each time step. The second, third and fourth ones compute the mean of each variable amongst the entire set of agents. The fifth one analysis calculates the sum of ressource values gathered by the agents.
(TODO and finally the last analysis generate a georeferenced file (Shapefile http://www.esri.com/library/whitepapers/pdfs/shapefile.pdf) that can be loaded by any GIS software.)
Regarding rasters, given the fact that each instance of GlobalRasterResults is defined for a raster, we can calculate the Mean and Sum of values: rasterResults.addAnalysis(RasterMean()) rasterResults.addAnalysis(RasterSum())
Finally, we will need to add import the analysis classes from pyPandora:
from pyPandora import SimulationRecord, GlobalAgentStats, AgentMean, AgentSum, AgentNum, RasterMean, RasterSum, GlobalRasterStats
and apply the results to a file:
agentResults.applyTo(record, 'agents.csv', 'MyAgent') rasterResults.applyTo(record, 'rasters.csv', 'resources')
As you can see the method applyTo receives 3 parameters: the SimulationRecord instance where data was loaded, the output CSV filename and the type of agent or raster name to be analysed. In this way you can apply the same analysis to different types of agents (or diferent rasters), storing the information on CSVs files.