GDBASE: database programs for use with GRASS

[Susan Huse]

Dear GRASS Users':

I am making available to the community a database system for use with
GRASS map layers.  The system creates reclasses of existing map layers
based on logical queries to flatfile databases.  This gdbase system was
presented at the 1994 GRASS Users' Conference.

A compressed tar file is available from our anonymous ftp site at
ohlone.ced.berkeley.edu   The file is /pub/grass/gdbase.tar.Z

An explanatory README is included with this announcement, but
a short explanation might be helpful.

The gdbase system is a set of programs that allows the user to
do various reclass operations on GRASS raster, vector, or sites maps.
They are combinations of shell scripts and gawk programs.  gawk is a
public-domain version of awk.  A user must have a copy of gawk in her
path to use gdbase.  Also included is a copy of s.reclass, which
non-interactively reclasses a sites file.

The database files are column-organized, colon-delimited text files,
where each line comprises one record.  Data stored in these files can
be alphanumeric, but should not include colons.  Field names are
user-defined.  The limit on column width and number of data fields is a
function of gawk.

The queries are logic statements based on database field names and
data values.  Valid operators include:
    and or not < > = + - / * ( )


-Sue Huse
CEDR - REGIS
University of California, Berkeley
sue at ced.berkeley.edu




Copy of the README file:


gdbase is a data query system for use with GRASS map layers.  It uses
simple ASCII text files for data, and creates new GRASS map layers
based on information stored in the data files.  It was written by Sue
Huse with assistance by James Ganong at University of California,
Berkeley.


For questions or problems contact:

Sue Huse
Center for Environmental Design Research
390 Wurster Hall
University of California
Berkeley, California 94720
sue at ced.berkeley.edu

INSTALLATION

The software is distributed is a compressed tar file called gdbase.tar.Z.
To expand the file:

zcat gdbase.tar.Z | tar -xvf -
 
This will create a directory called gdbase in the current directory.
To copy the scripts the proper directories:
 
cd gdbase ; ./install
 
INSTRUCTIONS FOR USE
 
To use the gdbase tools, you must have an executable version of gawk (the
public domain version of awk) in your path.
 
The gdbase commands are:
db.rreclass - creates a new raster reclass map layer based on a
database query.
 
db.rshow - displays the raster output of a database query as an
overlay to the current display monitor.  Similar to db.rreclass, but
it creates and removes a temporary raster reclass
 
db.sreclass - creates a new sites reclass map layer.  This assumes
that your sites file is of the format:
easting|northing|#att category
 
db.vreclass - creates a new vector reclass map layer based on a
database query.  It uses the GRASS contributed program v.reclass
including both areas and lines, and dissolving interior boundaries.
 
db.runique - creates a new raster reclass map layer comprising unique
combinations of the specified field names.
 

Database file:

Database files are to be placed in a dbase/ element directory in $LOCATION
(i.e., parallel to cell/ dig/, etc).  gdbase will find all dbase files
within you current mapset search path.

Database files are created independently of gdbase.  They are colon
delimited text files.  Line 1 is a user prompt for the name of
map layers appropriate for use with the data.  The database file
can have any name.  It does not need to follow the same naming conventions
as the cell and dig files.

The second line will be the exact data field names.  Field names cannot
include spaces or colons.  The first field name (and column) must be
the attribute number of the corresponding grass maplayer.  The second
column should be the category name.  All subsequent columns are user
defined.  There is no specific requirement for number of columns or
for size of columns, although there may be limitations to gawks ability
to handle excessive strings.

All following lines are data records.  One line represents one GRASS
category.  You do not have to include a line for all categories.  The
lines should be the att number, cat name and then the data fields,
once again separated by colons.  Data fields CAN have spaces, although
the field names can not.

Example:

raster and vector layers: groundwater at PERMANENT
att:cat:county:depth_to_gw:municipal_uses:agricultural_uses:
1:Petaluma Valley:Sonoma:20:1:0
2:Suisun-Fairfield Valley:Solano:15:0:1
3:Castro Valley:Alameda:30:1:1
10:Merced Valley:San Mateo:25:1:1


Invoking db.* commands:
To use db.* interactively, type the command without arguments.  The
following example uses db.rreclass for explanation purposes.
db.rreclass will prompt you for an existing database file, an existing
raster map that is to be reclassed (should be the map that corresponds
to the database file), and the name for the new reclass map.
Subsequent prompts will be for query rules.  You may have any number of
query rules.  Each rule will become a new category in the output
reclass file.  After entering the query rule, you will be prompted
for its new attribute and category name.  Hit return without a new
query rule to finish.

To use db.* non-interactively the syntax is:

db.rreclass input=existing_raster_file output=new_reclass_file database=dbase_file rules=rules_file.

You may substitute "i" for input, "o" for output, etc.  The rules
file must be in your current directory, or you must specify its path.
The rules file should be set up on sets of three lines.  The first
of a set is the new attribute number, the second is the new category
name, and the third is the query rule.  Blank lines between triplets
are optional.

Example rules file:
1
Alameda County
county = "Alameda"

2
deeper than 15 feet
depth_to_gw > 15


Query Syntax:
The syntax consists of basic logic statements.  Available operators are:

and or not < > = + - / * ( )
The data field names must be spelled exactly as they appear in the dbase
file.  Text fields must also be spelled exactly.

To query a text field, the text must be surrounded by double quotes:
county = "Alameda"
or
cat = "Suisun-Fairfield Valley"

The numerical operators should be in standard notation:
depth_to_gw = 15
or
agricultural_uses > 0

More complicated queries can be created using and, or, not and parentheses:
(county = "Alameda" or county = "San Mateo") and depth_to_gw > 25.


NOTE:  Be careful if your individual query rules overlap.  For instance
if your new category 1 is "Alameda" and you new category 2 is
depth_to_gw > 20.  Both these will find groundwater basin 3.  In these
cases the later rules will take precedence over all previous rules.
This is because db.* invokes GRASS reclass programs for which that is
the priority.

db.runique works in a different way from the other commands.  Rather
than specifying a query rule, the user specifies the fields on which
to sort.  db.runique will then create a new map showing the unique
combinations of those fields.  For instance in the groundwater
database above, specifying county would yield 4 output raster
categories, one for each county.  Specifying the municipal_uses would
yield only one new category.  Specifying municipal_uses and
agricultural_uses would yield 3 new categories (1:0, 0:1, 1:1).

The query syntax is one line listing the field names separated by
spaces.  The command-line version requires a one line rules file
as well.  If you want to sort on all columns, except the att and
cat columns, simply use "all" rather than typing each field name

Examples:
county
municipal_uses agricultural_uses
all