The JAS-mine platform‎ > ‎Documentation‎ > ‎Cookbook‎ > ‎

Output to CSV files and/or the database

There are two ways of storing output data from the simulation runs, either to the database or to .csv files.  Exporting to .csv is quicker than persisting to the database, so may be preferable when running simulations in time-constrained situations.  If the user wants to have the option to export the simulation data to both the database or .csv files, the DataExport class allows the functionality to be expressed in the code in a concise way.

The DataExport Class

In order to faciliate the exporting of data to .csv files and / or the database, a DataExport instance can be created in the Collector class for each object or collection of objects whose fields are to be recorded as in the code below.  The choice of whether to export to the database and / or the .csv files can be controlled by two boolean fields 'exportToDatabase' and 'exportToCSV' respectively, which are passed to the constructor of the DataExport objects and can be set from the GUI (because they have the @GUIparameter annotation, which replaces the deprecated @ModelParameter annotation). 

@GUIparameter(description = "Toggle to export snapshot to .csv files")
boolean exportToCSV = true;    //If true, data will be recorded to .csv files in the output directory

@GUIparameter(description = "Toggle to export snapshot to output database")
boolean exportToDatabase = true;  //If true, data will be recorded in the output database in the                                       // output directory

@GUIparameter(description = "Set the time at which to start exporting snaphots to the database                                                                                     and/or .csv files")
Double timeToStartDataExport = 0.;

@GUIparameter(description = "Set the time between snapshots to be exported to the database                                                                                     and/or .csv files")
Double timestepsBetweenDataDumps = 1.;

// collectionOfAgents is a Java Collection of agents e.g. an ArrayList, LinkedList or Set containing

// instances of the Agent.class
DataExport populationOutput = new DataExport(collectionOfAgents, exportToDatabase, exportToCSV);

// agent is an instance of the Agent.class and has PanelEntityKey with id = 123
DataExport agentOutput = new DataExport(agent, exportToDatabase, exportToCSV);

When executed with the exportToCSV Boolean set to true, separate .csv files will be created corresponding to the populationOutput and agentOutput objects.  The name of the .csv files will match the name of the class of object or entries of the collection of objects which were passed to the DataExport constructor.  In the case above for instance, the collectionOfAgents is a Java Collection such as a list or set whose entries are of the Agent class, so the corresponding Agent.csv file will be created.  On the other hand, the agent object is a single instance of the Agent class (not a collection), so a file named Agent123.csv will be created, with the suffix '123' matching the agent's id number in its PanelEntityKey instance.

Note that a class whose instances will have their data exported to a .csv file MUST have a PanelEntityKey; this is so that details such as the id of the instance of the class, and also the simulation time and run numbers, can be stored in the .csv as an identity stamp for the corresponding data.

When created, the .csv files will contain a first (header) line with the comma-separated names of all the fields of the underlying class to be recorded.  These include numerical values, strings, Booleans and enum constants, and both private fields and those inherited from the superclass are recorded.  References to objects, however, are not exported, although the internal fields of the PanelEntityKey associated with the object whose data is being recorded will be exported. 

In order to export the objects' data to either the .csv files or the database, the export() method must be invoked on the DataExport instances.  This can be placed in the event schedule, so that the objects' data can be recorded at regular times in the future thus providing a snapshot of the simulation run, or be invoked at any time and by any object in the simulation:

public void buildSchedule() {

   // Dump info from year 'timeToStartDataExport' onwards, with 'timestepsBetweenDataDumps'
specifying the period between data dumps thereafter
   getEngine().getEventList().scheduleRepeat(new SingleTargetEvent(this, Processes.DumpInfo),                        timeToStartDataExport, Order.AFTER_ALL.getOrdering(), timestepsBetweenDataDumps);      

   // Dump data at the (scheduled) end of the simulation
   getEngine().getEventList().schedule(new SingleTargetEvent(this, Processes.DumpInfo), endYear(),                                                                 Order.AFTER_ALL.getOrdering(), 0.);
// Event Listener
public enum Processes {
public void onEvent(Enum<?> type) {
    switch ((Processes) type) {
    case DumpInfo:
When the exportToCSV boolean is set to true, the .export() invocation will dump comma-separated data to the .csv files.  Again, the data included is either numerical, strings, Booleans or enum constants, and includes private and inherited fields belonging to the object or it's superclasses.  In the case of the Agent.csv, one line will be added for each of the agent instances contained in the collectionOfAgents object, with each line referenced by values of the PanelEntityKey:- the simulation run number, the simulation time and the agent's id.  In the case of Agent123.csv, a single line will be added containing the comma-separated data of the fields of the agent whose id is 123.

When the exportToDatabase Boolean is set to true, the DatabaseUtils.snap() method will be invoked, and JAS-mine's database functionality will kick in to export the data to the appropriate tables in the output database.  Note that in order to use the database functionality, the user must write code using the conventions discussed in the Output persistence to database page.