Skip to content

FileTypes

Jump to bottom
Baptiste Lesquoy edited this page Sep 8, 2023 · 15 revisions

File Types

GAMA provides modelers with a generic type for files called file. It is possible to load a file using the file operator:

file my_file <- file("../includes/data.csv");

However, internally, GAMA makes the difference between the different types of files. Indeed, for instance:

global {
	init {
		file my_file <- file("../includes/data.csv");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

sepallength
sepalwidth
petallength
petalwidth
type
5.1
3.5
1.4
0.2
Iris-setosa
4.9
3.0
1.4
0.2
Iris-setosa
...

Indeed, the content of CSV file is a matrix: each row of the matrix is a line of the file; each column of the matrix is value delimited by the separator (by default ",").

In contrary:

global {
	init {
		file my_file <- file("../includes/data.shp");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon
Polygon
Polygon
Polygon
Polygon
Polygon
Polygon

The content of a shapefile is a list of geometries corresponding to the objects of the shapefile.

In order to know how to load a file, GAMA analyzes its extension. For instance for a file with a ".csv" extension, GAMA knows that the file is a csv one and will try to split each line with the , separator. However, if the modeler wants to split each line with a different separator (for instance ;) or load it as a text file, he/she will have to use a specific file operator.

Indeed, GAMA integrates specific operators corresponding to different types of files.

Table of contents

Text File

Extensions

Here the list of possible extensions for text file:

  • "txt"
  • "data"
  • "csv"
  • "text"
  • "tsv"
  • "xml"

Note that when trying to define the type of a file with the default file loading operator (file), GAMA will first try to test the other type of file. For example, for files with ".csv" extension, GAMA will cast them as csv file and not as text file.

Content

The content of a text file is a list of string corresponding to each line of the text file. For example:

global {
	init {
		file my_file <- text_file("../includes/data.txt");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

sepallength,sepalwidth,petallength,petalwidth,type
5.1,3.5,1.4,0.2,Iris-setosa
4.9,3.0,1.4,0.2,Iris-setosa
4.7,3.2,1.3,0.2,Iris-setosa

Operators

List of operators related to text files:

  • text_file(string path): load a file (with an authorized extension) as a text file.
  • text_file(string path, list content): load a file (with an authorized extension) as a text file and fill it with the given content.
  • is_text(op): tests whether the operand is a text file

CSV File

Extensions

Here the list of possible extensions for csv file:

* "csv"
* "tsv"

Content

The content of a csv file is a matrix of objects: each row of the matrix is a line of the file; each column of the matrix is values delimited by the separator. By default, the delimiter is the "," and the datatype depends on the dataset. For example:

global {
	init {
		file my_file <- csv_file("../includes/data.csv");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

sepallength
sepalwidth
petallength
petalwidth
type
5.1
3.5
1.4
0.2
Iris-setosa
4.9
3.0
1.4
0.2
Iris-setosa
...

To manipulate easily the data, we can consider the contents of the data file, that is a matrix. As an example, we can access the number of lines and columns of a data file named my_file with my_file.contents.dimension.

Operators

There are many operators available to load a csv_file.

  • csv_file(string path): load a file (with an authorized extension) as a csv file with default separator (","), and no assumption on the type of data.
  • csv_file(string path,bool header)": load a file as a CSV file with the default separator (coma), with specifying if the model has a header or not (boolean), and no assumption on the type of data.
  • csv_file(string path, string separator): load a file (with an authorized extension) as a csv file with the given separator, without making any assumption on the type of data. Headers should be detected automatically if they exist.
file my_file <- csv_file("../includes/data.csv", ";");
  • csv_file(string path, string separator, bool header): load a file (with an authorized extension) as a csv file, specifying (1) the separator used; (2) if the model has a header or not, without making any assumption on the type of data.
  • csv_file(string path, string separator, string text_qualifier, bool header): load a file as a csv file specifying (1) the separator used; (2) the text qualifier used; (3) if the model has a header or not, without making any assumption on the type of data",
  • csv_file(string path, string separator, type datatype): load a file as a csv file specifying a given separator, no header, and the type of data. No text qualifier will be used.
file my_file <- csv_file("../includes/data.csv", ";", int);
  • csv_file(string path, string separator, string text_qualifier, type datatype): load a file as a csv file specifying the separator, text qualifier to use, and the type of data to read. Headers should be detected automatically if they exist.
  • csv_file(string path, string separator, type datatype, bool header): load a file as a csv file specifying the given separator, the type of data, with specifying if the model has a header or not (boolean). No text qualifier will be used".
  • csv_file(string path, string separator, type datatype, bool header, point dimensions): load a file as a csv file specifying a given separator, the type of data, with specifying the number of cols and rows taken into account. No text qualifier will be used.
  • csv_file(string path, matrix content): This file constructor allows to store a matrix in a CSV file (it does not save it - just store it in memory)

Finally, it is possible to check whether a file is a csv file:

  • is_csv(op): tests whether the operand is a csv file

Shapefile

Shapefiles are classical GIS data files. A shapefile is not simple file, but a set of several files (source: wikipedia):

  • Mandatory files :
    • .shp - shape format; the feature geometry itself
    • .shx - shape index format; a positional index of the feature geometry to allow seeking forwards and backwards quickly
    • .dbf - attribute format; columnar attributes for each shape, in dBase IV format
  • Optional files :
    • .prj - projection format; the coordinate system and projection information, a plain text file describing the projection using well-known text format
    • .sbn and .sbx - a spatial index of the features
    • .fbn and .fbx - a spatial index of the features for shapefiles that are read-only
    • .ain and .aih - an attribute index of the active fields in a table
    • .ixs - a geocoding index for read-write shapefiles
    • .mxs - a geocoding index for read-write shapefiles (ODB format)
    • .atx - an attribute index for the .dbf file in the form of shapefile.columnname.atx (ArcGIS 8 and later)
    • .shp.xml - geospatial metadata in XML format, such as ISO 19115 or other XML schema
    • .cpg - used to specify the code page (only for .dbf) for identifying the character encoding to be used

More details about shapefiles can be found here.

Extensions

Here the list of possible extension for shapefile:

  • "shp"

Content

The content of a shapefile is a list of geometries corresponding to the objects of the shapefile. For example:

global {
	init {
		file my_file <- shape_file("../includes/data.shp");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon
Polygon
Polygon
Polygon
Polygon
Polygon
Polygon
...

Note that the attributes of each object of the shapefile are stored in their corresponding GAMA geometry. The operator "get" (or "read") allows to get the value of corresponding attributes.

For example:

file my_file <- shape_file("../includes/data.shp");
write "my_file: " + my_file.contents;
loop el over: my_file {
	write (el get "TYPE");
}

Operators

List of operators related to shapefiles:

  • shape_file(string path): load a file (with an authorized extension) as a shapefile with default projection (if a prj file is defined, use it, otherwise use the default projection defined in the preference).
  • shape_file(string path, string code): load a file (with an authorized extension) as a shapefile with the given projection (GAMA will automatically decode the code. For a list of the possible projections see: http://spatialreference.org/ref/)
  • shape_file(string path, int EPSG_ID): load a file (with an authorized extension) as a shapefile with the given projection (GAMA will automatically decode the epsg code. For a list of the possible projections see: http://spatialreference.org/ref/)
file my_file <- shape_file("../includes/data.shp", "EPSG:32601");
  • shape_file(string path, list content): load a file (with an authorized extension) as a shapefile and fill it with the given content.
  • is_shape(op): tests whether the operand is a shapefile

OSM File

OSM (Open Street Map) is a collaborative project to create a free editable map of the world. The data produced in this project (OSM File) represent physical features on the ground (e.g., roads or buildings) using tags attached to its basic data structures (its nodes, ways, and relations). Each tag describes a geographic attribute of the feature being shown by that specific node, way or relation (source: openstreetmap.org).

More details about OSM data can be found here.

Extensions

Here the list of possible extension for shapefile:

  • "osm"
  • "pbf"
  • "bz2"
  • "gz"

Content

The content of an OSM data is a list of geometries corresponding to the objects of the OSM file. For example:

global {
	init {
		file my_file <- osm_file("../includes/data.gz");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Point
Point
Point
Point
Point
LineString
LineString
Polygon
Polygon
Polygon
...

Note that like for shapefiles, the attributes of each object of the osm file is stored in their corresponding GAMA geometry. The operator "get" (or "read") allows to get the value of corresponding attributes.

Operators

List of operators related to osm file:

  • osm_file(string path): load a file (with an authorized extension) as an osm file with default projection (if a prj file is defined, use it, otherwise use the default projection defined in the preference). In this case, all the nodes and ways of the OSM file will become a geometry.
  • osm_file(string path, string code): load a file (with an authorized extension) as an osm file with the given projection (GAMA will automatically decode the code. For a list of the possible projections see: http://spatialreference.org/ref/). In this case, all the nodes and ways of the OSM file will become a geometry.
  • osm_file(string path, int EPSG_ID): load a file (with an authorized extension) as an osm file with the given projection (GAMA will automatically decode the epsg code. For a list of the possible projections see: http://spatialreference.org/ref/). In this case, all the nodes and ways of the OSM file will become a geometry.
file my_file <- osm_file("../includes/data.gz", "EPSG:32601");
  • osm_file(string path, map filter): load a file (with an authorized extension) as an osm file with default projection (if a prj file is defined, use it, otherwise use the default projection defined in the preference). In this case, only the elements with the defined values are loaded from the file.
//map used to filter the object to build from the OSM file according to attributes. 
map filtering <- map(["highway"::["primary", "secondary", "tertiary", "motorway", "living_street","residential", "unclassified"], "building"::["yes"]]);

//OSM file to load
file<geometry> osmfile <-  file<geometry (osm_file("../includes/rouen.gz", filtering))  ;
  • osm_file(string path, map filter, string code): load a file (with an authorized extension) as a osm file with the given projection (GAMA will automatically decode the code. For a list of the possible projections see: http://spatialreference.org/ref/). In this case, only the elements with the defined values are loaded from the file.
  • osm_file(string path, map filter, int EPSG_ID): load a file (with an authorized extension) as a osm file with the given projection (GAMA will automatically decode the epsg code. For a list of the possible projections see: http://spatialreference.org/ref/). In this case, only the elements with the defined values are loaded from the file.
  • is_osm(op): tests whether the operand is a osm file

Grid File

Esri ASCII Grid files are classic text raster GIS data.

More details about Esri ASCII grid file can be found here.

Note that grid files can be used to initialize a grid species. The number of rows and columns will be read from the file. Similarly, the values of each cell contained in the grid file will be accessible through the grid_value attribute.

grid cell file: grid_file {
}

Extensions

Here the list of possible extension for grid file:

  • "asc"

Content

The content of a grid file is a list of geometries corresponding to the cells of the grid. For example:

global {
	init {
		file my_file <- grid_file("../includes/data.asc");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon
Polygon
Polygon
Polygon
Polygon
Polygon
Polygon
...

Note that the values of each cell of the grid file is stored in their corresponding GAMA geometry (grid_value attribute). The operator "get" (or "read") allows to get the value of this attribute.

For example:

file my_file <- grid_file("../includes/data.asc");
write "my_file: " + my_file.contents;
loop el over: my_file {
	write el get "grid_value";
}

Operators

List of operators related to shapefiles:

  • grid_file(string path): load a file (with an authorized extension) as a grid file with default projection (if a prj file is defined, use it, otherwise use the default projection defined in the preference).
  • grid_file(string path, string code): load a file (with an authorized extension) as a grid file with the given projection (GAMA will automatically decode the code. For a list of the possible projections see: http://spatialreference.org/ref/)
  • grid_file(string path, int EPSG_ID): load a file (with an authorized extension) as a grid file with the given projection (GAMA will automatically decode the epsg code. For a list of the possible projections see: http://spatialreference.org/ref/)
file my_file <- grid_file("../includes/data.shp", "EPSG:32601");
  • is_grid(op): tests whether the operand is a grid file.

Image File

Extensions

Here the list of possible extensions for image file:

  • "tif"
  • "tiff"
  • "jpg"
  • "jpeg"
  • "png"
  • "gif"
  • "pict"
  • "bmp"

Content

The content of an image file is a matrix of int: each pixel is a value in the matrix.

For example:

global {
	init {
		file my_file <- image_file("../includes/DEM.png");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

-9671572
-9671572
-9671572
-9671572
-9934744
-9934744
-9868951
-9868951
-10000537
-10000537
...

Operators

List of operators related to csv files:

  • image_file(string path): load a file (with an authorized extension) as an image file.
  • image_file(string path, matrix content): load a file (with an authorized extension) as an image file and fill it with the given content.
  • is_image(op): tests whether the operand is an image file

SVG File

Scalable Vector Graphics (SVG) is an XML-based vector image format for two-dimensional graphics with support for interactivity and animation. Note that interactivity and animation features are not supported in GAMA.

More details about SVG file can be found here.

Extensions

Here the list of possible extension for SVG file:

  • "svg"

Content

The content of a SVG file is a list of geometries. For example:

global {
	init {
		file my_file <- svg_file("../includes/data.svg");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon

Operators

List of operators related to svg files:

  • shape_file(string path): load a file (with an authorized extension) as a SVG file.
  • shape_file(string path, point size): load a file (with an authorized extension) as a SVG file with the given size:
file my_file <- svg_file("../includes/data.svg", {5.0,5.0});
  • is_svg(op): tests whether the operand is a SVG file

Property File

Extensions

Here the list of possible extensions for property file:

  • "properties"

Content

The content of a property file is a map of string corresponding to the content of the file. For example:

global {
	init {
		file my_file <- property_file("../includes/data.properties");
		loop el over: my_file {
			write el;
		}
	}
}

with the given property file:

sepallength = 5.0
sepalwidth = 3.0
petallength = 4.0
petalwidth = 2.5
type = Iris-setosa

will give:

3.0
4.0
5.0
Iris-setosa
2.5

Operators

List of operators related to text files:

  • property_file(string path): load a file (with an authorized extension) as a property file.
  • is_property(op): tests whether the operand is a property file

R File

R is a free software environment for statistical computing and graphics. GAMA allows to execute R script (if R is installed on the computer).

More details about R can be found here.

Note that GAMA also integrates some operators to manage R scripts:

Extensions

Here the list of possible extensions for R file:

  • "r"

Content

The content of a R file corresponds to the results of the application of the script contained in the file.

For example:

global {
	init {
		file my_file <- R_file("../includes/data.r");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

3.0

Operators

List of operators related to R files:

  • R_file(string path): load a file (with an authorized extension) as a R file.
  • is_R(op): tests whether the operand is a R file.

3DS File

3DS is one of the file formats used by the Autodesk 3ds Max 3D modeling, animation and rendering software. 3DS files can be used in GAMA to load 3D geometries.

More details about 3DS file can be found here.

Extensions

Here the list of possible extension for 3DS file:

  • "3ds"
  • "max"

Content

The content of a 3DS file is a list of geometries. For example:

global {
	init {
		file my_file <- threeds_file("../includes/data.3ds");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon

Operators

List of operators related to 3ds files:

  • threeds_file(string path): load a file (with an authorized extension) as a 3ds file.
  • is_threeds(op): tests whether the operand is a 3DS file

OBJ File

OBJ file is a geometry definition file format first developed by Wavefront Technologies for its Advanced Visualizer animation package. The file format is open and has been adopted by other 3D graphics application vendors.

More details about Obj file can be found here.

Extensions

Here the list of possible extension for OBJ files:

  • "obj"

Content

The content of a OBJ file is a list of geometries. For example:

global {
	init {
		file my_file <- obj_file("../includes/data.obj");
		loop el over: my_file {
			write el;
		}
	}
}

will give:

Polygon

Operators

List of operators related to obj files:

  • obj_file(string path): load a file (with an authorized extension) as a obj file.
  • is_obj(op): tests whether the operand is a OBJ file

Home

  1. What's new (Changelog)

Platform

  1. Installation and Launching
    1. Installation
    2. Launching GAMA
    3. Updating GAMA
    4. Installing Plugins
  2. Workspace, Projects and Models
    1. Navigating in the Workspace
    2. Changing Workspace
    3. Importing Models
  3. Editing Models
    1. GAML Editor (Generalities)
    2. GAML Editor Tools
    3. Validation of Models
  4. Running Experiments
    1. Launching Experiments
    2. Experiments User interface
    3. Controls of experiments
    4. Parameters view
    5. Inspectors and monitors
    6. Displays
    7. Batch Specific UI
    8. Errors View
  5. Running Headless
    1. Headless Batch
    2. Headless Server
    3. Headless Legacy
  6. Preferences
  7. Troubleshooting

Learn GAML step by step

  1. Introduction
    1. Start with GAML
    2. Organization of a Model
    3. Basic programming concepts in GAML
  2. Manipulate basic Species
  3. Global Species
    1. Regular Species
    2. Defining Actions and Behaviors
    3. Interaction between Agents
    4. Attaching Skills
    5. Inheritance
  4. Defining Advanced Species
    1. Grid Species
    2. Graph Species
    3. Mirror Species
    4. Multi-Level Architecture
  5. Defining GUI Experiment
    1. Defining Parameters
    2. Defining Displays Generalities
    3. Defining 3D Displays
    4. Defining Charts
    5. Defining Monitors and Inspectors
    6. Defining Export files
    7. Defining User Interaction
  6. Exploring Models
    1. Run Several Simulations
    2. Batch Experiments
    3. Exploration Methods
  7. Optimizing Model Section
    1. Runtime Concepts
    2. Optimizing Models
  8. Multi-Paradigm Modeling
    1. Control Architecture
    2. Defining Differential Equations

Recipes

  1. Manipulate OSM Data
  2. Diffusion
  3. Using Database
  4. Using FIPA ACL
  5. Using BDI with BEN
  6. Using Driving Skill
  7. Manipulate dates
  8. Manipulate lights
  9. Using comodel
  10. Save and restore Simulations
  11. Using network
  12. Headless mode
  13. Using Headless
  14. Writing Unit Tests
  15. Ensure model's reproducibility
  16. Going further with extensions
    1. Calling R
    2. Using Graphical Editor
    3. Using Git from GAMA

GAML References

  1. Built-in Species
  2. Built-in Skills
  3. Built-in Architecture
  4. Statements
  5. Data Type
  6. File Type
  7. Expressions
    1. Literals
    2. Units and Constants
    3. Pseudo Variables
    4. Variables And Attributes
    5. Operators [A-A]
    6. Operators [B-C]
    7. Operators [D-H]
    8. Operators [I-M]
    9. Operators [N-R]
    10. Operators [S-Z]
  8. Exhaustive list of GAMA Keywords

Developing GAMA

  1. Installing the GIT version
  2. Developing Extensions
    1. Developing Plugins
    2. Developing Skills
    3. Developing Statements
    4. Developing Operators
    5. Developing Types
    6. Developing Species
    7. Developing Control Architectures
    8. Index of annotations
  3. Introduction to GAMA Java API
    1. Architecture of GAMA
    2. IScope
  4. Using GAMA flags
  5. Creating a release of GAMA
  6. Documentation generation

Tutorials

  1. Predator Prey
  2. Road Traffic
  3. 3D Tutorial
  4. Incremental Model
  5. Luneray's flu
  6. BDI Agents

Community

  1. Team
  2. Projects using GAMA
  3. Scientific References
  4. Training Sessions

Versions of GAMA

Resources

  1. Videos
  2. Conferences
  3. Code Examples
  4. Pedagogical materials
Clone this wiki locally