readCGATS: read tables from files in ANSI/CGATS.17 format
In colorSpec: Color Calculations with Emphasis on Spectral Data
readCGATS R Documentation
read tables from files in ANSI/CGATS.17 format
Description
The CGATS text format supports a preamble followed by N tables, where N \ge 1.
Each table can have a separate header.
A table may or may not contain spectral data, see Note.
The function converts each table to a data.frame with attributes;
see Details.
Usage
readCGATS( path, collapsesingle=FALSE )
Arguments
path
the path name of a single file, in CGATS format
collapsesingle
If path has only one table (N=1) and collapsesingle is TRUE,
then return the single data.frame (instead of a list with 1 data.frame).
If path has multiple tables (N \ge 2), then collapsesingle is ignored.
Details
The returned list is given attributes: "path", "preamble",
and (if present) "date", "created", "originator", and "file_descriptor".
The attribute values are all character vectors.
The value of attribute "path" is the argument path,
and the other values are extracted from "preamble".
The length of "preamble" is (typically) greater than 1, and the others have length 1.
Each line of the preamble is a keyword-value pair.
The keyword ORIGINATOR is converted to attribute "originator".
The keyword FILE_DESCRIPTOR is converted to attribute "file_descriptor".
The keyword CREATED is converted to attributes "created" and "date".
The list is also given names.
If the keyword TABLE_NAME is present in the table header, then its value is used.
Otherwise the names are "TABLE_1", "TABLE_2", ...
Each data.frame in the list is assigned attributes: "header",
and (if present) "descriptor".
The length of "header" is (typically) greater than 1, and "descriptor" has length 1.
Each line of the table header is a keyword-value pair.
The keywords DESCRIPTOR and TABLE_DESCRIPTOR
are converted to attribute "descriptor".
For the lines between BEGIN_DATA and END_DATA,
two conventions for separating the values are supported:
In the standard convention, fields are separated by contiguous spaces or tabs, and character strings (which may have embedded spaces or even tabs)
are enclosed by double-quotes.
This is is the convention in the CGATS standard.
The function scan() is used here.
In the non-standard convention, fields are separated by a single tab,
and character strings (which may have embedded spaces but not tabs) are not enclosed by double-quotes.
This convention is often easier to work with in spreadsheet software.
The function strsplit() is used here.
The function readCGATS() selects the separation convention
by examining the line after BEGIN_DATA_FORMAT.
If this line is split by a single tab and the number of fields
matches that given on the NUMBER_OF_FIELDS line,
then the non-standard convention is selected;
otherwise, the standard convention is selected.
Value
readCGATS() returns a list of data.frames -
one data.frame for each table found in path.
The list and each individual data.frame have attributes, see Details.
If path has only a single table (the majority of files have only 1)
and collapsesingle is TRUE, then the attributes of the list
are copied to those of the data.frame,
and the data.frame is then returned.
The name of the table is lost.
If there is an error in any table, then the function returns NULL.
Note
In the BEGIN_DATA_FORMAT line(s),
field names may not be quoted and may not have embedded spaces.
The CGATS standard allows duplicated field names,
and readCGATS() returns them as they appear, with no attempt to append numbers
in order to make them unique.
Examples of field names which may be duplicated are:
SPECTRAL_NM, SPECTRAL_DEC, and SPECTRAL_PCT;
for more on these see readSpectraCGATS().
No attempt is made to recognize those tables that contain spectral data.
For conversion of spectral data to colorSpec objects, see readSpectraCGATS().
References
ANSI/CGATS.17.
Graphic technology - Exchange format for colour and process control data using XML or ASCII text.
https://webstore.ansi.org/
2009.
ISO/28178. Graphic technology - Exchange format for colour and process control data using XML or ASCII text.
https://www.iso.org/standard/44527.html.
2009.
CGATS.17 Text File Format.
http://www.colorwiki.com/wiki/CGATS.17_Text_File_Format.
See Also
readSpectraCGATS,
scan,
strsplit,
names
Examples
# read file with 2 tables of non-spectral data
A70 = readSpectra( system.file( "tests/A70.ti3", package='colorSpec' ) )
length(A70) # [1] 2 # the file has 2 tables
ncol( A70[[1]] ) # [1] 7 # the 1st table has 7 columns
ncol( A70[[2]] ) # [1] 4 # the 2nd table has 4 columns
colorSpec documentation built on May 29, 2024, 6 a.m.
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
| readCGATS | R Documentation |
read tables from files in ANSI/CGATS.17 format
Description
The CGATS text format supports a preamble followed by N tables, where N \ge 1.
Each table can have a separate header.
A table may or may not contain spectral data, see Note.
The function converts each table to a data.frame with attributes;
see Details.
Usage
readCGATS( path, collapsesingle=FALSE )
Arguments
path |
the path name of a single file, in CGATS format |
collapsesingle |
If |
Details
The returned list is given attributes: "path", "preamble",
and (if present) "date", "created", "originator", and "file_descriptor".
The attribute values are all character vectors.
The value of attribute "path" is the argument path,
and the other values are extracted from "preamble".
The length of "preamble" is (typically) greater than 1, and the others have length 1.
Each line of the preamble is a keyword-value pair.
The keyword ORIGINATOR is converted to attribute "originator".
The keyword FILE_DESCRIPTOR is converted to attribute "file_descriptor".
The keyword CREATED is converted to attributes "created" and "date".
The list is also given names.
If the keyword TABLE_NAME is present in the table header, then its value is used.
Otherwise the names are "TABLE_1", "TABLE_2", ...
Each data.frame in the list is assigned attributes: "header",
and (if present) "descriptor".
The length of "header" is (typically) greater than 1, and "descriptor" has length 1.
Each line of the table header is a keyword-value pair.
The keywords DESCRIPTOR and TABLE_DESCRIPTOR
are converted to attribute "descriptor".
For the lines between BEGIN_DATA and END_DATA,
two conventions for separating the values are supported:
In the standard convention, fields are separated by contiguous spaces or tabs, and character strings (which may have embedded spaces or even tabs) are enclosed by double-quotes. This is is the convention in the CGATS standard. The function
scan()is used here.In the non-standard convention, fields are separated by a single tab, and character strings (which may have embedded spaces but not tabs) are not enclosed by double-quotes. This convention is often easier to work with in spreadsheet software. The function
strsplit()is used here.
The function readCGATS() selects the separation convention
by examining the line after BEGIN_DATA_FORMAT.
If this line is split by a single tab and the number of fields
matches that given on the NUMBER_OF_FIELDS line,
then the non-standard convention is selected;
otherwise, the standard convention is selected.
Value
readCGATS() returns a list of data.frames -
one data.frame for each table found in path.
The list and each individual data.frame have attributes, see Details.
If path has only a single table (the majority of files have only 1)
and collapsesingle is TRUE, then the attributes of the list
are copied to those of the data.frame,
and the data.frame is then returned.
The name of the table is lost.
If there is an error in any table, then the function returns NULL.
Note
In the BEGIN_DATA_FORMAT line(s),
field names may not be quoted and may not have embedded spaces.
The CGATS standard allows duplicated field names,
and readCGATS() returns them as they appear, with no attempt to append numbers
in order to make them unique.
Examples of field names which may be duplicated are:
SPECTRAL_NM, SPECTRAL_DEC, and SPECTRAL_PCT;
for more on these see readSpectraCGATS().
No attempt is made to recognize those tables that contain spectral data.
For conversion of spectral data to colorSpec objects, see readSpectraCGATS().
References
ANSI/CGATS.17. Graphic technology - Exchange format for colour and process control data using XML or ASCII text. https://webstore.ansi.org/ 2009.
ISO/28178. Graphic technology - Exchange format for colour and process control data using XML or ASCII text. https://www.iso.org/standard/44527.html. 2009.
CGATS.17 Text File Format. http://www.colorwiki.com/wiki/CGATS.17_Text_File_Format.
See Also
readSpectraCGATS,
scan,
strsplit,
names
Examples
# read file with 2 tables of non-spectral data
A70 = readSpectra( system.file( "tests/A70.ti3", package='colorSpec' ) )
length(A70) # [1] 2 # the file has 2 tables
ncol( A70[[1]] ) # [1] 7 # the 1st table has 7 columns
ncol( A70[[2]] ) # [1] 4 # the 2nd table has 4 columns
R Package Documentation
Browse R Packages
We want your feedback!
Note that we can't provide technical support on individual packages. You should contact the package authors for that.
Embedding an R snippet on your website
Add the following code to your website.
For more information on customizing the embed code, read Embedding Snippets.