Quick start¶
Displaying attributes¶
An attribute that is stored in a single file can be displayed by simply specifying the file name on the command line (see section Program options). Basic commands for maps and time series are:
# Show a map.
aguila dem.map
![../_images/dem_Map.png](../_images/dem_Map.png)
# Show time series.
aguila rain.tss
![../_images/rain_TimeGraph.png](../_images/rain_TimeGraph.png)
# Show some maps and a time series.
aguila dem.map soil.map rain.tss
# Show a map in 2.5D.
aguila --drapeView dem.map
Each attribute is displayed in a separate window, here called a view (see section Views). To display multiple attributes in a single view insert a +
-symbol between the names, with spaces surrounding the +
-symbol.
# Multiple data items as drape.
aguila --drapeView dem.map + soil.map
![../_images/dem%2Bsoil_Drape.png](../_images/dem%2Bsoil_Drape.png)
Spatio-temporal attributes stored in the PCRaster raster format, is not stored in a single file but as a sequence of numbered rasters. This is true for most raster formats. To show such a spatio-temporal data set, two notations are allowed:
# Old style: show discharge and rainfall map stack.
aguila dis00000.001+36 rainfall.001+36
# New style: show discharge and rainfall map stack.
aguila --timesteps [1,36] dis rainfall
That is all information you need to display spatio-temporal raster attributes and timeseries. This manual will further instruct you how to create more sophisticated and combined views of data.
Required information¶
There are three types of information Aguila has to know about before it can visualise your data: 1) the name(s) of the attributes you want to visualise, 2) the dimensions of the attributes in which it is defined (see section Dimensions), and 3) the views you want to use.
Of course, the name of the data is required. Telling Aguila about the dimensions of the data may be required or not, depending on the data format (see Data formats). For each type of data there is a default view which may be fine or has to be chosen otherwise by configuring specific start up options. See Program options for information about using program options to pass information to Aguila.
Once Aguila has started visualising data it maintains links between data properties and the views, and between the views. For example, if two spatial data sets are visualised with 2D map views and in one of them the map shown is zoomed into, the other view will also zoom into the same area.
Program options¶
Aguila can be configured by passing it program options on the command line. For example, the command
aguila dem.map
starts Aguila with the name of a dataset to visualise. If Aguila can read the data it will show it in the default view. Type
aguila --help
for a list of all command line options supported.
Since typing long commands with a lot of options can be tedious, some program options can also be read from a configuration file. For example, the command
aguila --config settings.cfg
tells Aguila to look for program options in the file settings.cfg.
Aguila can also be started from an XML specification file, which allows for more fine grained control over the Aguila configuration:
aguila --xml settings.xml
See section Xml Startup Configuration for details.
Command line options and configuration file options can be used at the same time, so
aguila -f settings.cfg dem.map
starts Aguila with options on the command line and in a configuration file. Some options will be combined when given more than once and others will be overridden (this is documented in the tables below or obvious). When an option is overridden because it is given both on the command line and in a configuration file, the one on the command line is given precedence. One way to use configuration files is to put common options in them which can be used together with the command line (see also the examples below).
Some options take a range or a set of values as an argument. The syntax for a range of values is [first, last, step]
where first
is the first value, last
is the last value and step
is the interval between individual values between first and last. For example, the range [1,6,2]
consists of the values 1
, 3
, 5
(note that 6
is not used in this case because 5 + step
equals 7
, which is considered outside the range). The step is optional and the default value is dependent on the kind of range values. The range of timesteps [1,6]
consists of the values 1
, 2
, 3
, 4
, 5
, 6
. The syntax for a set of values is {value1, value2, ..., valuen}
.
Warning
The range and set notations can lead to suprising effects when used in a Unix (or Cygwin) shell (eg: bash). If you use such a shell, you must escape the {
, }
, [
and ]
characters, because these have special meaning to the shell interpreter. Or you may quote the whole argument:
aguila --scenarios \{a,b,c\} concentration
aguila --scenarios "{a, b, c}" concentration
When quoting the argument, you can use spaces between the values, otherwise you cannot.
Some options take the name of a data set as an argument. Aguila supports certain naming conventions which depend on the format the data is stored in. For example, a table stored in an ASCII column file is named by its filename, but the same table stored by a database management system might be named as myname(mypasswd)@mydbmsserver:mydatabase/mytable
or just mydatabase/mytable
. For more information about these naming conventions see section Data formats.
Command line options which can also occur in a configuration file must be named by the long option name, without the leading double dash. So, while -n
and --scenarios
are equivalent when used on the command line, only scenarios
can be used in a configuration file. Furthermore, the value of an option given on the command line is put immediately after the option name or character, optionally separated by white space. In a configuration file the option name and value are separated by an equals sign, optionally surrounded by white space. See also section Examples.
Option |
Description |
---|---|
-f [ –config ] arg |
Read options from the configuration file
named |
-x [ –xml ] arg |
Read options from the xml file named
|
-h [ –help ] |
Show the command synopsis and exit. |
-l [ –lock ] arg |
Create a lock file named |
–license |
Show the software license and exit. |
-v [ –version ] |
Show the software version and exit. |
-2 [ –mapView ] arg |
Show attribute named |
-3 [ –drapeView ] arg |
Show attribute named |
-t [ –timeGraphView ] arg |
Show attribute named |
-p [ –probabilityGraphView ] arg |
Show attribute named |
–valueOnly arg |
Show attribute named |
Option |
Description |
---|---|
-n [ –scenarios ] arg |
Configures the scenario dimension using the set
of scenarios in |
-s [ –timesteps ] arg |
Configures the time dimension using the range
or set of time steps in |
-q [ –quantiles] arg |
Configures the cumulative probability dimension
using the range or set of quantiles in
|
–cursorValueMonitorFile arg |
Tells Aguila to append an |
-m [ –multi ] arg |
When visualising scenarios of a spatial
attribute, this option can be used to
put all scenario’s side by side in one 2D
map view. |
Examples¶
These examples assume dem
, ldd
and erosion
are valid names of raster attributes and discharge
is a valid name of a time series attribute. These attributes are presented in a format supported by Aguila. Note that attributes in different formats can be combined.
2D raster¶
Visualise a raster in 2D. Default view for rasters is 2D map.
aguila dem
See also section Map view.
2D rasters on top of each other¶
Stack rasters on each other. Spaces around the +
-sign.
aguila dem + ldd
See also section Map view.
2.5D raster draped¶
2.5D is also possible.
aguila -3 dem + ldd
See also section Drape View.
2D raster stack¶
Raster attribute might be temporal. dem00000.001+100
is deprecated. Separate the name of the dataset from the dimension information.
aguila --timesteps [1,100] dem
See also sections Map view, Time Graph View.
Time series¶
Visualise all time series in one time series plot.
aguila discharge
See also section Time Graph View.
Time series selection¶
Select some time series (the fifth and seventh columns) from discharge.
aguila discharge{1,5} + discharge{1,7}
See also section Time Graph View.
2D raster draped and time series¶
Combine rasters and time series data.
aguila dem + ldd discharge
See also sections Map view, Time Graph View.
Scenarios of temporal quantiles¶
Select some more dimensions. For each scenario one 2D map view of the median value of erosion
.
aguila --scenarios {simple,complex} --quantiles [0.01,0.99] --timesteps [1,100] erosion
This example assumes that two erosion models where created, a simple one and a more complex one. Each of these models was used in a Monte Carlo analysis resulting in a distribution of erosion outcomes. For each timestep the distribution in erosion outcomes was summarised by a range of percentiles, for example the 0.01
, 0.05
, 0.1
, 0.25
, 0.5
, 0.75
, 0.9
, 0.95
, 0.99
percentiles. Aguila starts by presenting the median value of erosion
for each scenario as a 2D map view. Given this attribute it is possible to get a time series plot and a cumulative distribution plot for each location. All views can be animated. Aguila interpolates the data for percentiles that are not provided.
See also sections Map view, Time Graph View, Probability Graph View.
Environment variables¶
Aguila has support for many data set formats. While searching for data, Aguila tries each format driver in turn to see whether it is able to read the data. If you only use a fixed set of formats for your data sets, you can decrease startup time by limiting the number of potential data set formats Aguila considers. For this, define the environment variable called PCRASTER_DAL_FORMATS
. Its contents should be a comma separated list of format names. Most of them correspond to the names used in the GDAL and OGR data I/O libraries used by Aguila (Data set types).
Example:
$ export PCRASTER_DAL_FORMATS="CSF, HDF4, WCS, ESRI Shapefile"
Note
Although GDAL comes with a PCRaster driver built in, Aguila makes use of its own PCRaster driver and skips GDAL’s one. The name of the PCRaster raster format driver is CSF
.
Unknown format names are skipped. If none of the format names are known, Aguila will use all formats it knows of.
Warning
Whenever Aguila is unable to read your attributes, make sure the setting of PCRASTER_DAL_FORMATS is not excluding a format driver required for reading the attribute.