s.in.ascii

NAME

s.in.ascii - Converts an ASCII listing of site locations and their descriptions into a GRASS site list file.
(GRASS Sites Program)

SYNOPSIS

s.in.ascii
s.in.ascii help
s.in.ascii sites=name [input=name] [d=value] [fs=character|space|tab] [date=timestamp[/timestamp]]

DESCRIPTION

s.in.ascii converts an ASCII listing of site locations and category labels into a file in GRASS site list file format.

Input can be entered via standard input or from the file input=name. Each line of input should contain the easting, northing, and either the category value or category label associated with a site. The fs=name option (where name is either a character, a space, or a tab) can be used to specify the use of a particular field separator between these three input fields. This is useful when input is obtained from other programs (see NOTES, below). Output is stored in the file sites=name and placed in the site_lists/ directory under the user's current mapset.

The GRASS program s.out.ascii can be used to perform the reverse function, converting a file in GRASS site list format into an ASCII listing of eastings, northings, and category labels associated with site locations.

Parameters:

sites=name: Name of the new GRASS site list file to be output.
input=name: Name of an existing ASCII file containing site locations and labels.
d=value: number of dimensions (default=2)
fs=character|space|tab: The field separator separating the easting, northing, and category label in each line of the input file. The field separator can be a character, a space, or a tab.
Default: space
date=timestamp[/timestamp]: String specifying timestamp or timestamp range.

s.in.ascii can be run either non-interactively or interactively. The program will be run non-interactively if the user specifies a name to be assigned to the sites file output, the name of an existing ASCII file containing input, and (optionally) a field separator fs appearing in the input file.

Alternately, the user can simply type s.in.ascii on the command line, without program arguments. In this case, the user will be prompted for parameter values using the standard GRASS parser interface described in the manual entry for parser. If the user does not specify the name of an input file containing site locations and category attributes, these should be entered to the program via standard input. The d parameter allows the user to specify that more than 2 dimensions will be imported. Otherwise the third (or further) column in the input file will be treated as an attribute.

To define a date (timestamp), several date strings are accepted. Please see r.timestamp for details.

NOTES

Importing from other GRASS programs

Other GRASS programs can be used to produce output in a format suitable for input to s.in.ascii. For example, the user might pipe output produced by d.where into s.in.ascii to create a site list file called my.sites containing site locations pointed to with the mouse, as illustrated below. In this example it is unnecessary to specify the field separator used in the input, since d.where output separates the easting and northing values with spaces, and spaces are the default field separator assumed by s.in.ascii.

d.where | s.in.ascii sites=my.sites

Importing from a spreadsheet

Data may be imported from many spreadsheet programs by saving the spreadsheet as a comma separated variable (.csv) text file, and then using the "fs=," command line parameter with s.in.ascii. Note s.in.ascii currently requires there to be at least three columns of data for the import to work properly.

Importing latitude/longitude data

Latitude/longitude data may be imported either in decimal degree format:

    8.314824 54.921730 site1
    8.897605 54.872353 site2
    9.549371 54.834080 site3

or in DMS (degree, minutes, seconds) format:

    8:18:53.3664E 54:55:18.228N site1
    8:53:51.378E  54:52:20.4708N site2
    9:32:57.7356E 54:50:02.688N site3

Time as String Attributes

In this example, we will work with the following site list:

    10.8 0 9.8 Fri Sep 13 10:00:00 1986 31.4
    11 5.5 9.9 Fri Sep 14 00:20:00 1985 36.4
    5.1 3.9 10 Fri Sep 15 00:00:30 1984 28.4

This data has three dimensions (assume easting, northing, and elevation), five string attributes, and one decimal attribute.

GRASS 5.0 internal sites format in "site_lists/"

If the user wishes to generate site list files directly, the internal format is described below.

Header:

    #any comment, can be inserted anywhere
    name|mysoils.site
    desc|3D soils data for location A
    time|15 Jan 1999
    labels|east north elevation ID pH Corg color
    form||||#%%@

Data:

Each line of the ASCII file should contain either two or three coordinates (x,y and optionally z) separated by a pipe ("|") character. After the coordinates there should be trailing pipe character, and optionally attribute fields may follow separated from each other with blank spaces.

The attribute field may be a category number, a decimal value or a string. Category numbers must come first and be preceded by the "#" character, while string values must be preceded by the "@" character. Floating point values may be preceded by the "%" character but if there is no "#" or "@" preceding the attribute then it is assumed to be a floating point (FP) value. Also, string values that contain blanks must be quoted or the part of the string following the first blank will be parsed as a separate field, which may cause an error.

General form
easting|northing|[z|[d4|]...][#category_int] [ [@attr_text OR %FP] ... ]

Example
739865.8|4279785.5|#2965 %396685 %194919 %2.473222 @"St.Louis" @MO @city

There can be many dimensions between pipes (|), but no #%@.

There can be only one cat, preceded by #, after which there may be many FP or text attributes.

For more information, see the GRASS ASCII formats page or the GRASS 5 Programmer's manual.

AUTHOR

Michael Shapiro, U.S. Army Construction Engineering Research Laboratory

Last changed: $Date$