Skip to main content
Version: 🚧 2024-06 🚧

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