making and importing data

Description

Various pems.utils functions to make and import data as pems objects.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
#making pems objects
 
is.pems(x, full.test = TRUE, ...)

pems(x, units = NULL, constants = NULL, history = NULL,  
          ...)

pems.element(x, name = NULL, units = NULL,   
          ...)

#associated 

isPEMS(...)
makePEMS(...)
makePEMSElement(...)

## S3 method for class 'data.frame'
as.pems(x, ...)


#importing data as pems objects

#general

import2PEMS(file.name = file.choose(), time.stamp = NULL, local.time = NULL,
          time.format = NULL, units = NULL, constants = NULL, history = NULL, 
          ..., file.type = NULL, file.reader = read.delim)

importTAB2PEMS(..., file.reader = read.delim)

importCSV2PEMS(..., file.reader = read.csv)


#Horiba OBS

importOBS2PEMS(file.name = file.choose(), pems = "Horiba OBS", 
          constants = NULL, history = NULL, 
          analytes = c("co", "co2", "nox", "hc"),  
          fuel = c("petrol", "diesel", "gasoline"), ...)

importOB12PEMS(file.name = file.choose(), pems = "Horiba OBS", 
          constants = NULL, history = NULL, 
          analytes = c("co", "co2", "nox", "hc"),  
          fuel = c("petrol", "diesel", "gasoline"), ...)


#3DATX parSYNC

importParSYNC2PEMS(file.name = file.choose(), reset.signals = TRUE, 
         history = NULL, constants = NULL, pm.analyzer = "parSYNC",
         ... )


#3DATX CAGE
importCAGE2PEMS(..., calibrator = "CAGE")


#RoyalTek GPS

importRoyalTek2PEMS(file.name = file.choose(), 
          file.type = c("special", "txt", "nmea"),
          vbox = "RoyalTEk", history = NULL, constants = NULL, ...) 

Arguments

x

(A required object) For is.pems, any object to be tested as a pems object. For pems, an object to be used as the starting point to make a pems object, so typically a data.frame or another pems object.

full.test

(Logical) For is.pems, should the full pems test be applied and the pems structure confirmed?

...

(Optional) Other arguments, handling varies. For is.pems these are ignored. For pems these are added to the pems object unmodified. For import... functions, these are passed on and added to the constants component of the pems object. Note: This different handling is experimental and may be subject to change in future.

units, constants, history

(Default pems arguments) These are arguments that are routinely generated for pems objects. units holds unit ids for unit management, constants holds constants that should used specifically with data in the pems object, and history holds the pems object modification history.

name

(Default pems.element argument) name (and units) are arguments that are routinely generated for pems.element objects.

file.name

(file connection, etc.) For import... functions, the file/source to be imported. Note: the default, file.name = file.choose(), automatically opens a file browser if this argument is not supplied.

time.stamp, local.time, time.format

Relatively crude import... functions are useful for importing data from the clipboard or simple file types. However, these sometimes need careful handling of time data. If supplied, time.stamp and local.time are used as indices or ids (column numbers or names) for data series that the user would like to use as the data time stamp and local time records, respectively. If supplied, time.format sets the format in which the time.stamp should be imported if present/idenified.

file.type, file.reader

Data reader parameters for some import... functions. file.type is the type of file to be imported. Note: Some import... functions can handle more than one file type, and file.type = "[option]" should be used to identify these. (Note: file.type options are typically file type identifiers, such as the file extensions, and a default 'special', which leaves the choice to the function. This way this option can typically be ignored unless, e.g. the function does not recognise the file type but the user knows it and wants to force the method.) file.reader identifies the R method/function that should be used to read data from the supplied file. For example, for importTAB2PEMS and importCSV2PEMS, by default, these are the standard R read... functions read.delim and read.csv, respectively.

pems, vbox, pm.analyzer, calibrator

(Character vectors) For some import... functions, data source descriptions may be automatically added to the pems object. pems and vbox are two examples, but others, such as vehicle and fuel descritpions can also be added in a similar fashion. Note: These are for user-reference, so can say whatever you want.

analytes

(Character vector) For import... functions, the names of any pems elements to be tagged as analyte concentrations. Note: If the PEMS unit reports concentrations rather than emissions it is often useful to identify these at import to avoid confusion, and to simplify later handling. So, if encountered, analyte names are prefixed with the term 'conc.'.

fuel

Some import... functions that handle exhaust monitoring system data may assume fuel types when calibrating inputs or calculating constants. In such cases the fuel argument is also included to identify which fuel was used.

reset.signals

(Logical or Character vector) For importParSYNC2PEMS, should any raw signal be reset? The default (TRUE) reverses the sign of opacity and ionization signals.

Details

is.pems tests if an object is/is not a pems object.

pems makes a pems object using supplied data and information.

pems.element makes a pems.element object using supplied data and information.

as.pems... functions attempt to convert a supplied object into a pems object. Currently, there is only a data.frame method and (by default) a pems method.

isPEMS, makePEMS and makePEMSElement are historical code, retained for backward compatibility.

Crude import... functions import simple file structures, and are useful for getting data quickly into R:pems.utils. importTAB2PEMS imports tab delimited files and clipboard content. importCSV2PEMS imports comma delimited files. Both assume a simple file structure (i.e. data series in columns with names as headers), but require some time data management by the user. Note: These are wrappers for import2PEMS.

Other import... import specific file types.

importOBS2PEMS imports standard Horiba OBS files and converts them to pems objects. See Notes below.

importOB12PEMS imports .OB1 files and converts them to pems objects. OB1 files are generated by a Visual Basic PEMS data handler used during the RETEMM project. Notes below.

importParSYNC2PEMS imports standard parSYNC files and converts them to pems objects. See Notes below.

importCAGE2PEMS imports standard CAGE files and converts them to pems objects. See importParSYNC2PEMS Notes below.

importRoyalTek2PEMS imports .txt and .nmea format Royal Tek GPS files and converts them to pems objects. See Notes below.

Value

is.pems return a logical, TRUE if the supplied object is pems class, otherwise FALSE. If the argument full.test = TRUE is also supplied, additional information about the object is returned as comment(output).

pems and pems.element functions return pems and pems.element objects, respectively, made using the supplied file and any additional information also supplied in the same call.

import... functions return a pems object, made using the supplied file and any additional information also supplied in the same call.

Note

isPEMS, makePEMS and makePEMSElement were earlier functions that performed the same functions as is.pems, pems and pems.elements, respectively. The the current versions of these functions are wrappers for their replacements.

With the crude import... functions (import2PEMS, importTAB2PEMS, importCSV2PEMS) modifications are minimal. Unless any additional changes are requested in the import...(...) call, the data is simply read in as a data.frame and converted to a pems object.

With importOBS2PEMS, OBS data is also modified as follows: data series names are simplified and converted to lower case to simplify use in R; the data series time.stamp and local.time are added (generated using the file time stamp, the row counter and the log.rate constant); data series latitude and longitude are resigned according to set N/S and E/W values, if these are present/valid; latitude and longitude units are also reset to 'd.degLat' and 'd.degLon'. Any data series names in analytes is renamed 'conc.[analyte name]'. If not supplied in the importOBS2PEMS, typical OBS constants are currently assumed. Several of these are based on emission source fuel. Defaults for these are generated according to fuel (default 'petrol').

With importOB12PEMS, handling is similar to that with importOBS2PEMS.

With importParSYNC2PEMS, the parSYNC data modifications are as follows: parSYNC Date and Time data-series are merged and converted into *POSIX as time.stamp; local.time is calculated from this; the parSYNC data series Timestamp is retained as parsync.timestamp; by default units are removed from data-series names, but retained as units(pems); (again by default) all names are converted to lower case. The default option reset.signal = TRUE reverses the voltage reading of opacity and ionization time-series (x = - x), if present. Alternatively, imports can be identified specifically by name, e.g. reset.signal = "opacity" to just reset opacity. Typical OBS constants are currently assumed, if not supplied. Several of these are based on emission source fuel. The default assumption is that the fuel is 'petrol' unless fuel has been assigned.

With importCAGE2PEMS, handling is similar to that with importParSYNC2PEMS.

With importRoyalTek2PEMS, the Royal Tek data modifications are currently being documented.

Author(s)

Karl Ropkins

References

References in preparation.

See Also

See ref.unit.conversions and convertUnits for general unit handling; merge.pems for pems data merging and alignment.

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
###########
##example 1 
###########

#make little pems

data <- data.frame(speed=1:10, emissions=1:10)
units <- c("m/s", "g/s")
pems <- pems(x = data, units=units, example="my record") 
 
pems                       #the pems object
summary(pems)              #summary of held data
pems$speed                 #the speed pems.element

#import data file as pems using import... functions

#For example, to import CSV file as pems object 
#pems <- importCSV2PEMS()