Working with Units

Carl Boettiger

2017-05-01

Overview

library("EML")

One essential role of EML metadata is in precisely defining the units in which data is measured. To make sure these units can be understood by (and thus potentially converted to other units by) a computer, it’s necessary to be rather precise about our choice of units. EML knows about a lot of commonly used units, referred to as “standardUnits,” already. If a unit is in EML’s standardUnit dictionary, we can refer to it without further explanation as long as wer are careful to use the precise id for that unit, as we will see below.

Sometimes data involves a unit that is not in standardUnit dictionary. In this case, the metadata must provide additional information about the unit, including how to convert the unit into the SI system. EML uses an existing standard, stmml, to represent this information, which must be given in the additionalMetadata section of an EML file. The stmml standard is also used to specify EML’s own standardUnit definitions.

Reading EML: parsing unit information, including custom unit types

Let us start by examining the numeric attributes in an example EML file. First we read in the file:

f <- system.file("xsd/test/eml-datasetWithUnits.xml", package = "EML")
eml <- read_eml(f)

We extract the attributeList, and examine the numeric attributes (e.g. those which have units):

attribute_tables <- eml_get(eml, "attributeList")


a <- attribute_tables$attributes
numerics <- a[a$domain == "numericDomain",]
numerics
##    attributeName        domain precision minimum maximum
## 3             sr numericDomain      0.50       0    <NA>
## 4         pctcov numericDomain      0.10       0     1e2
## 5        avesr91 numericDomain      0.10       0    <NA>
## 6        avesr92 numericDomain      0.10       0        
## 7        avesr93 numericDomain      0.10       0        
## 8        avesr94 numericDomain      0.10       0        
## 9        avesr95 numericDomain      0.10       0        
## 10       avesr96 numericDomain      0.10       0        
## 11        MeanSR numericDomain      0.10       0        
## 12       biomass numericDomain      0.01       0    <NA>
## 13         sppm2 numericDomain      0.01       0    <NA>
##                     unit numberType formatString definition pattern source
## 3                 number       real         <NA>       <NA>    <NA>   <NA>
## 4          dimensionless       real         <NA>       <NA>    <NA>   <NA>
## 5                 second       real         <NA>       <NA>    <NA>   <NA>
## 6     cubicFeetPerSecond       real         <NA>       <NA>    <NA>   <NA>
## 7             cubicMeter       real         <NA>       <NA>    <NA>   <NA>
## 8                 radian       real         <NA>       <NA>    <NA>   <NA>
## 9                  meter       real         <NA>       <NA>    <NA>   <NA>
## 10                  inch       real         <NA>       <NA>    <NA>   <NA>
## 11              nanogram       real         <NA>       <NA>    <NA>   <NA>
## 12   gramsPerSquareMeter       real         <NA>       <NA>    <NA>   <NA>
## 13 speciesPerSquareMeter       real         <NA>       <NA>    <NA>   <NA>
##                       attributeLabel storageType missingValueCode
## 3                   Species Richness       float             <NA>
## 4                      percent cover       float             <NA>
## 5  Average Species Richness for 1991       float             <NA>
## 6  Average Species Richness for 1992       float             <NA>
## 7  Average Species Richness for 1993       float             <NA>
## 8  Average Species Richness for 1994       float             <NA>
## 9  Average Species Richness for 1995       float             <NA>
## 10 Average Species Richness for 1996       float             <NA>
## 11             mean species richness       float             <NA>
## 12                           Biomass       float             <NA>
## 13          Species Per Square Meter       float             <NA>
##    missingValueCodeExplanation measurementScale
## 3                         <NA>         interval
## 4                         <NA>            ratio
## 5                         <NA>            ratio
## 6                         <NA>            ratio
## 7                         <NA>            ratio
## 8                         <NA>            ratio
## 9                         <NA>            ratio
## 10                        <NA>            ratio
## 11                        <NA>            ratio
## 12                        <NA>            ratio
## 13                        <NA>            ratio
##                                             attributeDefinition
## 3                                      Species richness for CDR
## 4               The percent ground cover on the field\n        
## 5  The average species richness for the field in 1991\n        
## 6  The average species richness for the field in 1992\n        
## 7  The average species richness for the field in 1993\n        
## 8  The average species richness for the field in 1994\n        
## 9  The average species richness for the field in 1995\n        
## 10 The average species richness for the field in 1996\n        
## 11        the mean species richness from 1991 to 1996\n        
## 12           The total biomass measured in this field\n        
## 13                Calculated species per square meter\n

We see this data contains eleven columns containing numeric data, with metadata for the unit, precision, range, and number type (integer, real complex) given in the resulting table.

EML knows about many standard units already, but a metadata file may occassionally need to define a unit that is not in the StandardUnit dictionary. We can use the function is_standardUnit() to quickly check if the units shown here are in EML’s dictionary:

units <- numerics$unit
units[ !is_standardUnit(units) ]
## [1] "speciesPerSquareMeter"

This shows us that the unit speciesPerSquareMeter is the only unit not in the Standard Unit Dictionary. We can have a look at the definitions for all units that are in the Standard Unit dictionary using the function get_unitList() with no arguments:

standardUnits <- get_unitList()
standardUnits$units
##                                      id
## 1                         dimensionless
## 2                                second
## 3                                 meter
## 4                              kilogram
## 5                                kelvin
## 6                               coulomb
## 7                                ampere
## 8                                  mole
## 9                               candela
## 10                               number
## 11                           cubicMeter
## 12                        nominalMinute
## 13                          nominalHour
## 14                           nominalDay
## 15                          nominalWeek
## 16                          nominalYear
## 17                      nominalLeapYear
## 18                             nanogram
## 19                            microgram
## 20                            milligram
## 21                            centigram
## 22                             decigram
## 23                                 gram
## 24                             dekagram
## 25                            hectogram
## 26                             megagram
## 27                                tonne
## 28                                pound
## 29                                  ton
## 30                              celsius
## 31                           fahrenheit
## 32                            nanometer
## 33                           micrometer
## 34                               micron
## 35                           millimeter
## 36                           centimeter
## 37                            decimeter
## 38                            dekameter
## 39                           hectometer
## 40                            kilometer
## 41                            megameter
## 42                             angstrom
## 43                                 inch
## 44                              Foot_US
## 45                                 foot
## 46                      Foot_Gold_Coast
## 47                               fathom
## 48                         nauticalMile
## 49                                 yard
## 50                          Yard_Indian
## 51                          Link_Clarke
## 52                           Yard_Sears
## 53                                 mile
## 54                           nanosecond
## 55                          microsecond
## 56                          millisecond
## 57                          centisecond
## 58                           decisecond
## 59                           dekasecond
## 60                          hectosecond
## 61                           kilosecond
## 62                           megasecond
## 63                               minute
## 64                                 hour
## 65                            kiloliter
## 66                           microliter
## 67                           milliliter
## 68                                liter
## 69                               gallon
## 70                                quart
## 71                               bushel
## 72                            cubicInch
## 73                                 pint
## 74                               radian
## 75                               degree
## 76                                 grad
## 77                            megahertz
## 78                            kilohertz
## 79                                hertz
## 80                           millihertz
## 81                               newton
## 82                                joule
## 83                              calorie
## 84                   britishThermalUnit
## 85                            footPound
## 86                                lumen
## 87                                  lux
## 88                            becquerel
## 89                                 gray
## 90                              sievert
## 91                                katal
## 92                                henry
## 93                             megawatt
## 94                             kilowatt
## 95                                 watt
## 96                            milliwatt
## 97                             megavolt
## 98                             kilovolt
## 99                                 volt
## 100                           millivolt
## 101                               farad
## 102                                 ohm
## 103                            ohmMeter
## 104                              siemen
## 105                               weber
## 106                               tesla
## 107                              pascal
## 108                          megapascal
## 109                          kilopascal
## 110                          atmosphere
## 111                                 bar
## 112                            millibar
## 113             kilogramsPerSquareMeter
## 114                 gramsPerSquareMeter
## 115            milligramsPerSquareMeter
## 116                 kilogramsPerHectare
## 117                     tonnePerHectare
## 118                 poundsPerSquareInch
## 119               kilogramPerCubicMeter
## 120             milliGramsPerMilliLiter
## 121                       gramsPerLiter
## 122             milligramsPerCubicMeter
## 123                  microgramsPerLiter
## 124                  milligramsPerLiter
## 125             gramsPerCubicCentimeter
## 126                  gramsPerMilliliter
## 127                 gramsPerLiterPerDay
## 128                     litersPerSecond
## 129                cubicMetersPerSecond
## 130                  cubicFeetPerSecond
## 131                         squareMeter
## 132                                 are
## 133                             hectare
## 134                    squareKilometers
## 135                   squareMillimeters
## 136                   squareCentimeters
## 137                                acre
## 138                          squareFoot
## 139                          squareYard
## 140                          squareMile
## 141                litersPerSquareMeter
## 142                      bushelsPerAcre
## 143                    litersPerHectare
## 144              squareMeterPerKilogram
## 145                     metersPerSecond
## 146                        metersPerDay
## 147                          feetPerDay
## 148                       feetPerSecond
## 149                         feetPerHour
## 150                      yardsPerSecond
## 151                        milesPerHour
## 152                      milesPerSecond
## 153                      milesPerMinute
## 154                centimetersPerSecond
## 155                millimetersPerSecond
## 156                   centimeterPerYear
## 157                               knots
## 158                   kilometersPerHour
## 159              metersPerSecondSquared
## 160                          waveNumber
## 161               cubicMeterPerKilogram
## 162             cubicMicrometersPerGram
## 163                amperePerSquareMeter
## 164                      amperePerMeter
## 165                   molePerCubicMeter
## 166                            molarity
## 167                            molality
## 168               candelaPerSquareMeter
## 169              metersSquaredPerSecond
## 170                 metersSquaredPerDay
## 171                   feetSquaredPerDay
## 172   kilogramsPerMeterSquaredPerSecond
## 173  gramsPerCentimeterSquaredPerSecond
## 174         gramsPerMeterSquaredPerYear
## 175               gramsPerHectarePerDay
## 176          kilogramsPerHectarePerYear
## 177     kilogramsPerMeterSquaredPerYear
## 178                    molesPerKilogram
## 179                        molesPerGram
## 180                   millimolesPerGram
## 181           molesPerKilogramPerSecond
## 182           nanomolesPerGramPerSecond
## 183                  kilogramsPerSecond
## 184                       tonnesPerYear
## 185                        gramsPerYear
## 186               numberPerMeterSquared
## 187           numberPerKilometerSquared
## 188                 numberPerMeterCubed
## 189                      numberPerLiter
## 190                 numberPerMilliliter
## 191                       metersPerGram
## 192                       numberPerGram
## 193                        gramsPerGram
## 194                   microgramsPerGram
## 195 cubicCentimetersPerCubicCentimeters
##                                    name                       unitType
## 1                         dimensionless                  dimensionless
## 2                                second                           time
## 3                                 meter                         length
## 4                              kilogram                           mass
## 5                                kelvin                    temperature
## 6                               coulomb                         charge
## 7                                ampere                        current
## 8                                  mole                         amount
## 9                               candela                     luminosity
## 10                               number                  dimensionless
## 11                           cubicMeter                         volume
## 12                        nominalMinute                           time
## 13                          nominalHour                           time
## 14                           nominalDay                           time
## 15                          nominalWeek                           time
## 16                          nominalYear                           time
## 17                      nominalLeapYear                           time
## 18                             nanogram                           mass
## 19                            microgram                           mass
## 20                            milligram                           mass
## 21                            centigram                           mass
## 22                             decigram                           mass
## 23                                 gram                           mass
## 24                             dekagram                           mass
## 25                            hectogram                           mass
## 26                             megagram                           mass
## 27                                tonne                           mass
## 28                                pound                           <NA>
## 29                                  ton                           <NA>
## 30                              celsius                           <NA>
## 31                           fahrenheit                           <NA>
## 32                            nanometer                           <NA>
## 33                           micrometer                           <NA>
## 34                               micron                           <NA>
## 35                           millimeter                           <NA>
## 36                           centimeter                           <NA>
## 37                            decimeter                           <NA>
## 38                            dekameter                           <NA>
## 39                           hectometer                           <NA>
## 40                            kilometer                           <NA>
## 41                            megameter                           <NA>
## 42                             angstrom                           <NA>
## 43                                 inch                           <NA>
## 44                              Foot_US                           <NA>
## 45                                 foot                           <NA>
## 46                      Foot_Gold_Coast                           <NA>
## 47                               fathom                           <NA>
## 48                         nauticalMile                           <NA>
## 49                                 yard                           <NA>
## 50                          Yard_Indian                           <NA>
## 51                          Link_Clarke                           <NA>
## 52                           Yard_Sears                           <NA>
## 53                                 mile                           <NA>
## 54                           nanosecond                           <NA>
## 55                          microsecond                           <NA>
## 56                          millisecond                           <NA>
## 57                          centisecond                           <NA>
## 58                           decisecond                           <NA>
## 59                           dekasecond                           <NA>
## 60                          hectosecond                           <NA>
## 61                           kilosecond                           <NA>
## 62                           megasecond                           <NA>
## 63                               minute                           <NA>
## 64                                 hour                           <NA>
## 65                            kiloliter                         volume
## 66                           microliter                         volume
## 67                           milliliter                         volume
## 68                                liter                         volume
## 69                               gallon                           <NA>
## 70                                quart                           <NA>
## 71                               bushel                         volume
## 72                            cubicInch                         volume
## 73                                 pint                           <NA>
## 74                               radian                          angle
## 75                               degree                          angle
## 76                                 grad                          angle
## 77                            megahertz                      frequency
## 78                            kilohertz                      frequency
## 79                                hertz                      frequency
## 80                           millihertz                      frequency
## 81                               newton                          force
## 82                                joule                         energy
## 83                              calorie                         energy
## 84                   britishThermalUnit                         energy
## 85                            footPound                         energy
## 86                                lumen                     luminosity
## 87                                  lux                    illuminance
## 88                            becquerel        radionucleotideActivity
## 89                                 gray                 specificEnergy
## 90                              sievert                 doseEquivalent
## 91                                katal              catalyticActivity
## 92                                henry                     inductance
## 93                             megawatt                          power
## 94                             kilowatt                          power
## 95                                 watt                          power
## 96                            milliwatt                          power
## 97                             megavolt            potentialDifference
## 98                             kilovolt            potentialDifference
## 99                                 volt            potentialDifference
## 100                           millivolt            potentialDifference
## 101                               farad                    capacitance
## 102                                 ohm                     resistance
## 103                            ohmMeter                    resistivity
## 104                              siemen                    conductance
## 105                               weber                   magneticFlux
## 106                               tesla            magneticFluxDensity
## 107                              pascal                       pressure
## 108                          megapascal                       pressure
## 109                          kilopascal                       pressure
## 110                          atmosphere                       pressure
## 111                                 bar                       pressure
## 112                            millibar                       pressure
## 113             kilogramsPerSquareMeter               arealMassDensity
## 114                 gramsPerSquareMeter               arealMassDensity
## 115            milligramsPerSquareMeter               arealMassDensity
## 116                 kilogramsPerHectare               arealMassDensity
## 117                     tonnePerHectare               arealMassDensity
## 118                 poundsPerSquareInch               arealMassDensity
## 119               kilogramPerCubicMeter                    massDensity
## 120             milliGramsPerMilliLiter                    massDensity
## 121                       gramsPerLiter                    massDensity
## 122             milligramsPerCubicMeter                    massDensity
## 123                  microgramsPerLiter                    massDensity
## 124                  milligramsPerLiter                    massDensity
## 125             gramsPerCubicCentimeter                    massDensity
## 126                  gramsPerMilliliter                    massDensity
## 127                 gramsPerLiterPerDay      volumetricMassDensityRate
## 128                     litersPerSecond                 volumetricRate
## 129                cubicMetersPerSecond                 volumetricRate
## 130                  cubicFeetPerSecond                 volumetricRate
## 131                         squareMeter                           area
## 132                                 are                           area
## 133                             hectare                           area
## 134                    squareKilometers                           area
## 135                   squareMillimeters                           area
## 136                   squareCentimeters                           area
## 137                                acre                           area
## 138                          squareFoot                           area
## 139                          squareYard                           area
## 140                          squareMile                           area
## 141                litersPerSquareMeter                 volumetricArea
## 142                      bushelsPerAcre                 volumetricArea
## 143                    litersPerHectare                 volumetricArea
## 144              squareMeterPerKilogram                   specificArea
## 145                     metersPerSecond                          speed
## 146                        metersPerDay                          speed
## 147                          feetPerDay                          speed
## 148                       feetPerSecond                          speed
## 149                         feetPerHour                          speed
## 150                      yardsPerSecond                          speed
## 151                        milesPerHour                          speed
## 152                      milesPerSecond                          speed
## 153                      milesPerMinute                          speed
## 154                centimetersPerSecond                          speed
## 155                millimetersPerSecond                          speed
## 156                   centimeterPerYear                          speed
## 157                               knots                          speed
## 158                   kilometersPerHour                          speed
## 159              metersPerSecondSquared                   acceleration
## 160                          waveNumber               lengthReciprocal
## 161               cubicMeterPerKilogram                 specificVolume
## 162             cubicMicrometersPerGram                 specificVolume
## 163                amperePerSquareMeter                 currentDensity
## 164                      amperePerMeter          magneticFieldStrength
## 165                   molePerCubicMeter amountOfSubstanceConcentration
## 166                            molarity amountOfSubstanceConcentration
## 167                            molality        amountOfSubstanceWeight
## 168               candelaPerSquareMeter                      luminance
## 169              metersSquaredPerSecond                 transmissivity
## 170                 metersSquaredPerDay                 transmissivity
## 171                   feetSquaredPerDay                 transmissivity
## 172   kilogramsPerMeterSquaredPerSecond           arealMassDensityRate
## 173  gramsPerCentimeterSquaredPerSecond           arealMassDensityRate
## 174         gramsPerMeterSquaredPerYear           arealMassDensityRate
## 175               gramsPerHectarePerDay           arealMassDensityRate
## 176          kilogramsPerHectarePerYear           arealMassDensityRate
## 177     kilogramsPerMeterSquaredPerYear           arealMassDensityRate
## 178                    molesPerKilogram        amountOfSubstanceWeight
## 179                        molesPerGram        amountOfSubstanceWeight
## 180                   millimolesPerGram        amountOfSubstanceWeight
## 181           molesPerKilogramPerSecond    amountOfSubstanceWeightFlux
## 182           nanomolesPerGramPerSecond    amountOfSubstanceWeightFlux
## 183                  kilogramsPerSecond                       massFlux
## 184                       tonnesPerYear                       massFlux
## 185                        gramsPerYear                       massFlux
## 186               numberPerMeterSquared                   arealDensity
## 187           numberPerKilometerSquared                   arealDensity
## 188                 numberPerMeterCubed              volumetricDensity
## 189                      numberPerLiter              volumetricDensity
## 190                 numberPerMilliliter              volumetricDensity
## 191                       metersPerGram             massSpecificLength
## 192                       numberPerGram              massSpecificCount
## 193                        gramsPerGram                    massPerMass
## 194                   microgramsPerGram                    massPerMass
## 195 cubicCentimetersPerCubicCentimeters                volumePerVolume
##                              parentSI       multiplierToSI constantToSI
## 1                                <NA>                 <NA>         <NA>
## 2                                <NA>                    1         <NA>
## 3                                <NA>                    1         <NA>
## 4                                <NA>                    1         <NA>
## 5                                <NA>                    1         <NA>
## 6                                <NA>                    1         <NA>
## 7                                <NA>                    1         <NA>
## 8                                <NA>                    1         <NA>
## 9                                <NA>                    1         <NA>
## 10                               <NA>                 <NA>         <NA>
## 11                               <NA>                    1         <NA>
## 12                             second                   60         <NA>
## 13                             second                 3600         <NA>
## 14                             second                86400         <NA>
## 15                             second               604800         <NA>
## 16                             second             31536000         <NA>
## 17                             second             31622400         <NA>
## 18                           kilogram       0.000000000001         <NA>
## 19                           kilogram          0.000000001         <NA>
## 20                           kilogram             0.000001         <NA>
## 21                           kilogram              0.00001         <NA>
## 22                           kilogram               0.0001         <NA>
## 23                           kilogram                0.001         <NA>
## 24                           kilogram                 0.01         <NA>
## 25                           kilogram                  0.1         <NA>
## 26                           kilogram                 1000         <NA>
## 27                           kilogram                 1000         <NA>
## 28                           kilogram               0.4536         <NA>
## 29                           kilogram             907.1999         <NA>
## 30                             kelvin                    1       273.18
## 31                             kelvin                0.556      255.402
## 32                              meter          0.000000001         <NA>
## 33                              meter             0.000001         <NA>
## 34                              meter             0.000001         <NA>
## 35                              meter                0.001         <NA>
## 36                              meter                 0.01         <NA>
## 37                              meter                  0.1         <NA>
## 38                              meter                   10         <NA>
## 39                              meter                  100         <NA>
## 40                              meter                 1000         <NA>
## 41                              meter              1000000         <NA>
## 42                              meter         0.0000000001         <NA>
## 43                              meter               0.0254         <NA>
## 44                              meter               0.3048         <NA>
## 45                              meter               0.3048         <NA>
## 46                              meter            0.3047997         <NA>
## 47                              meter               1.8288         <NA>
## 48                              meter                 1852         <NA>
## 49                              meter               0.9144         <NA>
## 50                              meter 0.914398530744440774         <NA>
## 51                              meter         0.2011661949         <NA>
## 52                              meter  0.91439841461602867         <NA>
## 53                              meter             1609.344         <NA>
## 54                             second          0.000000001         <NA>
## 55                             second             0.000001         <NA>
## 56                             second                0.001         <NA>
## 57                             second                 0.01         <NA>
## 58                             second                  0.1         <NA>
## 59                             second                   10         <NA>
## 60                             second                  100         <NA>
## 61                             second                 1000         <NA>
## 62                             second              1000000         <NA>
## 63                             second                   60         <NA>
## 64                             second                 3600         <NA>
## 65                         cubicMeter                    1         <NA>
## 66                         cubicMeter          0.000000001         <NA>
## 67                         cubicMeter             0.000001         <NA>
## 68                         cubicMeter                0.001         <NA>
## 69                              liter             3.785412         <NA>
## 70                              liter             0.946353         <NA>
## 71                              liter             0.035239         <NA>
## 72                              liter       0.000016387064         <NA>
## 73                              liter             0.473176         <NA>
## 74                               <NA>                    1         <NA>
## 75                             radian         0.0174532924         <NA>
## 76                             radian             0.015707         <NA>
## 77                              hertz              1000000         <NA>
## 78                              hertz                 1000         <NA>
## 79                               <NA>                    1         <NA>
## 80                              hertz             0.000001         <NA>
## 81                               <NA>                    1         <NA>
## 82                               <NA>                    1         <NA>
## 83                              joule               4.1868         <NA>
## 84                              joule            1055.0559         <NA>
## 85                              joule             1.355818         <NA>
## 86                               <NA>                    1         <NA>
## 87                               <NA>                    1         <NA>
## 88                               <NA>                    1         <NA>
## 89                               <NA>                    1         <NA>
## 90                               <NA>                    1         <NA>
## 91                               <NA>                    1         <NA>
## 92                               <NA>                    1         <NA>
## 93                               watt              1000000         <NA>
## 94                               watt                 1000         <NA>
## 95                               <NA>                    1         <NA>
## 96                               watt                0.001         <NA>
## 97                               volt              1000000         <NA>
## 98                               volt                 1000         <NA>
## 99                               <NA>                    1         <NA>
## 100                              volt                0.001         <NA>
## 101                              <NA>                    1         <NA>
## 102                              <NA>                    1         <NA>
## 103                              <NA>                    1         <NA>
## 104                              <NA>                    1         <NA>
## 105                              <NA>                    1         <NA>
## 106                              <NA>                    1         <NA>
## 107                              <NA>                    1         <NA>
## 108                            pascal              1000000         <NA>
## 109                            pascal                 1000         <NA>
## 110                            pascal               101325         <NA>
## 111                            pascal               100000         <NA>
## 112                            pascal                  100         <NA>
## 113                              <NA>                    1         <NA>
## 114           kilogramsPerSquareMeter                0.001         <NA>
## 115           kilogramsPerSquareMeter             0.000001         <NA>
## 116           kilogramsPerSquareMeter               0.0001         <NA>
## 117           kilogramsPerSquareMeter                  0.1         <NA>
## 118           kilogramsPerSquareMeter                17.85         <NA>
## 119                              <NA>                    1         <NA>
## 120            kilogramsPerCubicMeter                    1         <NA>
## 121            kilogramsPerCubicMeter                    1         <NA>
## 122            kilogramsPerCubicMeter             0.000001         <NA>
## 123            kilogramsPerCubicMeter             0.000001         <NA>
## 124            kilogramsPerCubicMeter                0.001         <NA>
## 125            kilogramsPerCubicMeter                 1000         <NA>
## 126            kilogramsPerCubicMeter                 1000         <NA>
## 127                              <NA>                    1         <NA>
## 128                              <NA>                    1         <NA>
## 129                   litersPerSecond                    1         <NA>
## 130                   litersPerSecond            28.316874         <NA>
## 131                              <NA>                    1         <NA>
## 132                       squareMeter                  100         <NA>
## 133                       squareMeter                10000         <NA>
## 134                       squareMeter              1000000         <NA>
## 135                       squareMeter             0.000001         <NA>
## 136                       squareMeter               0.0001         <NA>
## 137                       squareMeter            4046.8564         <NA>
## 138                       squareMeter             0.092903         <NA>
## 139                       squareMeter             0.836131         <NA>
## 140                       squareMeter        2589998.49806         <NA>
## 141                              <NA>                    1         <NA>
## 142              litersPerSquareMeter              0.00870         <NA>
## 143              litersPerSquareMeter               0.0001         <NA>
## 144                              <NA>                    1         <NA>
## 145                   metersPerSecond                    1         <NA>
## 146                              <NA>          .0000115741         <NA>
## 147                   metersPerSecond        0.00000352778         <NA>
## 148                   metersPerSecond               0.3048         <NA>
## 149                   metersPerSecond          0.000084667         <NA>
## 150                   metersPerSecond               0.9144         <NA>
## 151                   metersPerSecond              0.44704         <NA>
## 152                   metersPerSecond             1609.344         <NA>
## 153                   metersPerSecond              26.8224         <NA>
## 154                   metersPerSecond                 0.01         <NA>
## 155                   metersPerSecond                0.001         <NA>
## 156                   metersPerSecond    0.000000000317098         <NA>
## 157                   metersPerSecond             0.514444         <NA>
## 158                   metersPerSecond               0.2778         <NA>
## 159                              <NA>                    1         <NA>
## 160                              <NA>                    1         <NA>
## 161                              <NA>                    1         <NA>
## 162             cubicMeterPerKilogram    0.000000000000001         <NA>
## 163                              <NA>                    1         <NA>
## 164                              <NA>                    1         <NA>
## 165                              <NA>                    1         <NA>
## 166                molesPerCubicMeter                 1000         <NA>
## 167                              <NA>                    1         <NA>
## 168                              <NA>                    1         <NA>
## 169                              <NA>                    1         <NA>
## 170            metersSquaredPerSecond                86400         <NA>
## 171            metersSquaredPerSecond          0.000124586         <NA>
## 172                              <NA>                    1         <NA>
## 173 kilogramsPerMeterSquaredPerSecond                  0.1         <NA>
## 174 kilogramsPerMeterSquaredPerSecond   0.0000000000317098         <NA>
## 175 kilogramsPerMeterSquaredPerSecond   0.0000000000011574         <NA>
## 176 kilogramsPerMeterSquaredPerSecond             0.000317         <NA>
## 177 kilogramsPerMeterSquaredPerSecond           0000000317         <NA>
## 178                              <NA>                    1         <NA>
## 179                  molesPerKilogram                 1000         <NA>
## 180                  molesPerKilogram                    1         <NA>
## 181                              <NA>                    1         <NA>
## 182         molesPerKilogramPerSecond             0.000001         <NA>
## 183                              <NA>                    1         <NA>
## 184                kilogramsPerSecond            0.0000317         <NA>
## 185                kilogramsPerSecond      0.0000000000317         <NA>
## 186                              <NA>                    1         <NA>
## 187             numberPerMeterSquared             0.000001         <NA>
## 188                              <NA>                    1         <NA>
## 189               numberPerMeterCubed                0.001         <NA>
## 190               numberPerMeterCubed             0.000001         <NA>
## 191                              <NA>                    1         <NA>
## 192                              <NA>                    1         <NA>
## 193                              <NA>                    1         <NA>
## 194                      gramsPerGram             0.000001         <NA>
## 195                              <NA>                    1         <NA>
##     abbreviation
## 1           <NA>
## 2            sec
## 3              m
## 4             kg
## 5              K
## 6              C
## 7              A
## 8            mol
## 9             cd
## 10          <NA>
## 11            m³
## 12          <NA>
## 13          <NA>
## 14          <NA>
## 15          <NA>
## 16          <NA>
## 17          <NA>
## 18            ng
## 19            μg
## 20            mg
## 21            cg
## 22            dg
## 23             g
## 24           dag
## 25            hg
## 26            Mg
## 27             T
## 28           lbs
## 29           ton
## 30             C
## 31             F
## 32            nm
## 33            μm
## 34             μ
## 35            mm
## 36            cm
## 37            dm
## 38           dam
## 39            hm
## 40            km
## 41            Mm
## 42             Å
## 43            in
## 44          usft
## 45            ft
## 46          gcft
## 47          <NA>
## 48          <NA>
## 49          yard
## 50          <NA>
## 51          <NA>
## 52          <NA>
## 53          mile
## 54          nsec
## 55          μsec
## 56          msec
## 57          csec
## 58          dsec
## 59         dasec
## 60          hsec
## 61          ksec
## 62          Msec
## 63           min
## 64            hr
## 65            kL
## 66            μl
## 67            ml
## 68             L
## 69           gal
## 70            qt
## 71             b
## 72           in³
## 73          pint
## 74           rad
## 75             º
## 76          grad
## 77           MHz
## 78           KHz
## 79            Hz
## 80           mHz
## 81             N
## 82             J
## 83           cal
## 84           btu
## 85          <NA>
## 86            lm
## 87            lx
## 88            Bq
## 89            Gy
## 90            Sv
## 91           kat
## 92             H
## 93            MW
## 94            kW
## 95             W
## 96            mW
## 97            MV
## 98            kV
## 99             V
## 100           mV
## 101            F
## 102            Ω
## 103           Ωm
## 104            S
## 105           Wb
## 106            T
## 107           Pa
## 108          MPa
## 109          kPa
## 110          atm
## 111          bar
## 112         mbar
## 113        kg/m²
## 114         g/m²
## 115        mg/m²
## 116         <NA>
## 117         <NA>
## 118      lbs/in²
## 119         <NA>
## 120        kg/m³
## 121          g/l
## 122        mg/m³
## 123         μg/l
## 124         mg/l
## 125        g/cm³
## 126         g/ml
## 127         <NA>
## 128          l/s
## 129         m³/s
## 130      ft³/sec
## 131           m²
## 132            a
## 133           ha
## 134         <NA>
## 135         <NA>
## 136         <NA>
## 137            a
## 138          ft²
## 139          yd²
## 140        mile²
## 141         l/m²
## 142         <NA>
## 143         <NA>
## 144        m²/kg
## 145          m/s
## 146        m/day
## 147       ft/day
## 148         ft/s
## 149        ft/hr
## 150         yd/s
## 151          mph
## 152          mps
## 153          mpm
## 154         cm/s
## 155         mm/s
## 156      cm/year
## 157         <NA>
## 158        km/hr
## 159         m/s²
## 160         <NA>
## 161        m³/kg
## 162       μm³/kg
## 163         A/m²
## 164          A/m
## 165         <NA>
## 166            M
## 167            m
## 168        cd/m²
## 169         m²/s
## 170       m²/day
## 171      ft²/day
## 172         <NA>
## 173         <NA>
## 174         <NA>
## 175         <NA>
## 176         <NA>
## 177         <NA>
## 178         <NA>
## 179         <NA>
## 180         <NA>
## 181         <NA>
## 182         <NA>
## 183         kg/s
## 184         <NA>
## 185         g/yr
## 186         <NA>
## 187         <NA>
## 188         <NA>
## 189         <NA>
## 190         <NA>
## 191          m/g
## 192         <NA>
## 193         <NA>
## 194         <NA>
## 195         <NA>
##                                                                                description
## 1                                a designation asserting the absence of an associated unit
## 2                                                                          SI unit of time
## 3                                                                        SI unit of length
## 4                                                                          SI unit of mass
## 5                                                                   SI unit of temperature
## 6                                                                        SI unit of charge
## 7                                                            SI unit of electrical current
## 8                                                              SI unit of substance amount
## 9                                                                    SI unit of luminosity
## 10                                                                                a number
## 11                                                                             cubic meter
## 12                                           one minute excluding leap seconds, 60 seconds
## 13                                           one hour excluding leap seconds, 3600 seconds
## 14                                           one day excluding leap seconds, 86400 seconds
## 15                                          one day excluding leap seconds, 604800 seconds
## 16                         one year excluding leap seconds and leap days, 31536000 seconds
## 17                               one 366 day year excluding leap seconds, 31622400 seconds
## 18                                                                       0.000000000001 kg
## 19                                                                          0.000000001 kg
## 20                                                                             0.000001 kg
## 21                                                                              0.00001 kg
## 22                                                                               0.0001 kg
## 23                                                                                0.001 kg
## 24                                                                                  .01 kg
## 25                                                                                   .1 kg
## 26                                                                                 1000 kg
## 27                                                                     metric ton or tonne
## 28                                             1 pound in the Avoirdupois (commerce) scale
## 29                                                      standard US (short) ton = 2000 lbs
## 30                                                            A common unit of temperature
## 31                    An obsolescent unit of temperature still used in popular meteorology
## 32                                                                       .000000001 meters
## 33                                                                          .000001 meters
## 34                                                                          .000001 meters
## 35                                                                             .001 meters
## 36                                                                              .01 meters
## 37                                                                               .1 meters
## 38                                                                               10 meters
## 39                                                                              100 meters
## 40                                                                             1000 meters
## 41                                                                          1000000 meters
## 42                                                                     1/10000000000 meter
## 43                                                           An imperial measure of length
## 44                                                                               12 inches
## 45                                                                               12 inches
## 46                                                                               12 inches
## 47                                                                                  6 feet
## 48                                                                           nautical mile
## 49                                                                                  3 feet
## 50  This is an ESRI unit and the multiplier comes from ESRI.  It\n    may not be accurate.
## 51  This is an ESRI unit and the multiplier comes from ESRI.  It\n    may not be accurate.
## 52  This is an ESRI unit and the multiplier comes from ESRI.  It\n    may not be accurate.
## 53                                                              5280 ft or 1609.344 meters
## 54                                                                   1/1000000 of a second
## 55                                                                    1/100000 of a second
## 56                                                                      1/1000 of a second
## 57                                                                       1/100 of a second
## 58                                                                        1/10 of a second
## 59                                                                              10 seconds
## 60                                                                             100 seconds
## 61                                                                            1000 seconds
## 62                                                                         1000000 seconds
## 63                                                                              60 seconds
## 64                                                                            3600 seconds
## 65                                                                           1 cubic meter
## 66                                                                    1/1000000 of a liter
## 67                                                                       1/1000 of a liter
## 68                                                                               1000 cm^3
## 69                                                                        US liquid gallon
## 70                                                                         US liquid quart
## 71                                                              1 bushel = 35.23907 liters
## 72                                                                              cubic inch
## 73                                                                          US liquid pint
## 74                                                    2 pi radians comprise a unit circle.
## 75                                                      360 degrees comprise a unit circle
## 76                                      a plane angle equivalent to 1/400 of a full circle
## 77                                                                               megahertz
## 78                                                                               kilohertz
## 79                                                                                   hertz
## 80                                                                              millihertz
## 81                                                                                  newton
## 82                                                                             joule = N*m
## 83                                                                        1 cal = 4.1868 J
## 84                                                                     1 btu = 1055.0559 J
## 85                                                                   1 ft-lbs = 1.355818 J
## 86                                                                                   lumen
## 87                                                                                     lux
## 88                                                                               becquerel
## 89                                                                                    gray
## 90                                                                                 sievert
## 91                                                                                   katal
## 92                                                                                   henry
## 93                                                                                megawatt
## 94                                                                                kilowatt
## 95                                                                              watt = J/s
## 96                                                                               milliwatt
## 97                                                                                megavolt
## 98                                                                                kilovolt
## 99                                                                                    volt
## 100                                                                              millivolt
## 101                                                                                  farad
## 102                                                                                    ohm
## 103                                                                             ohm meters
## 104                                                                                 siemen
## 105                                                                                  weber
## 106                                                                                  tesla
## 107                                                                                 pascal
## 108                                                                             megapascal
## 109                                                                             kilopascal
## 110                                                         1 atmosphere = 101325 pascals 
## 111                                                                 1 bar = 100000 pascals
## 112                                                                               millibar
## 113                                                             kilograms per square meter
## 114                                                                 grams per square meter
## 115                                                            milligrams Per Square Meter
## 116                                                                  kilograms per hectare
## 117                                                        metric ton or tonne per hectare
## 118                                                                        lbs/square inch
## 119                                                               kilogram per cubic meter
## 120                                                              milligrams per milliliter
## 121                                                                        grams per liter
## 122                                                             milligrams Per Cubic Meter
## 123                                                                     micrograms / liter
## 124                                                                     milligrams / liter
## 125                                                             grams per cubic centimeter
## 126                                                                   grams per milliliter
## 127                                                              grams Per (Liter Per Day)
## 128                                                                      liters per second
## 129                                                                cubic meters per second
## 130                                                                  cubic feet per second
## 131                                                                          square meters
## 132                                                                      100 square meters
## 133                                                        1 hectare is 10^4 square meters
## 134                                                                      square kilometers
## 135                                                                      square millmeters
## 136                                                                     square centimeters
## 137                           1 acre = 4046.8564 square meters or 1 hectare = 2.4710 acres
## 138                                                                      12 inches squared
## 139                                                                      36 inches squared
## 140                                                                         1 mile squared
## 141                                                                liters per square meter
## 142         bushels per acre -- 1 bushel = 35.23907 liters/1 acre = 4046.8564 squareMeters
## 143                                                                     liters per hectare
## 144                                                             square meters per kilogram
## 145                                                                      meters per second
## 146                                                                         meters per day
## 147                                                                           feet per day
## 148                                                                        feet per second
## 149                                                                          feet per hour
## 150                                                                       yards per second
## 151                                                                         miles per hour
## 152                                                                       miles per second
## 153                                                                       miles per minute
## 154                                                                 centimeters per second
## 155                                                                 millimeters per second
## 156                                                                    centimeter Per Year
## 157                                                                                  knots
## 158                                                                                  km/hr
## 159                                                              meters per second squared
## 160                                                                               1/meters
## 161                                                              cubic meters per kilogram
## 162                                                             cubic micrometers per gram
## 163                                                               ampere per meter squared
## 164                                                                       ampere per meter
## 165                                                                   mole per cubic meter
## 166                                                                 molarity = moles/liter
## 167                                                                    molality = moles/kg
## 168                                                               candela Per Square Meter
## 169                                                              meters squared per second
## 170                                                                 meters squared per day
## 171                                                                   feet squared per day
## 172                                                  kilograms per meter sqared per second
## 173                                                grams Per Centimeter Squared Per Second
## 174                                                       grams Per Meter Squared Per Year
## 175                                                      grams Per Hectare Squared Per Day
## 176                                                         kilograms Per Hectare Per Year
## 177                                                   kilograms Per Meter Squared Per Year
## 178                                                                     moles per kilogram
## 179                                                                         moles per gram
## 180                                                                    millimoles per gram
## 181                                                          moles per kilogram per second
## 182                                                          nanomoles Per Gram Per Second
## 183                                                                   kilograms per second
## 184                                                                        tonnes Per Year
## 185                                                                         grams Per Year
## 186                                                               number per meter squared
## 187                                                           number per kilometer squared
## 188                                                                 number per meter cubed
## 189                                                           number of entities per liter
## 190                                                      number of entities per milliliter
## 191                                                                        meters per gram
## 192                                                            number of entities per gram
## 193                                                                         grams per gram
## 194                                                                    micrograms per gram
## 195                                                 cubic centimeters per cubic centimeter

Use View(standardUnits$units) for a prettier display locally.

The get_unitList() function returns two tables, units and unitType. We will see the importance of the latter in a moment. This table can be useful in identifying the appropriate unit id to use when creating an EML file using set_attributes().

For now, we would like to learn more about the custom unit that isn’t in the standard dictionary. A valid EML file must provide the definitions for any custom unit in the addtionalMetadata section. We can use get_unitList() to extract this information from the EML document:

customUnits <- get_unitList(eml@additionalMetadata[[1]]@metadata)
customUnits
## $units
##                      id                  name         unitType
## 1   gramsPerSquareMeter   gramsPerSquareMeter arealMassDensity
## 2 speciesPerSquareMeter speciesPerSquareMeter     arealDensity
##                  parentSI multiplierToSI constantToSI abbreviation
## 1 kilogramsPerSquareMeter           .001         <NA>         <NA>
## 2    numberPerSquareMeter              1         <NA>         <NA>
##                                        description
## 1 a description of the unit Grams per Square Meter
## 2                                             <NA>
## 
## $unitTypes
## NULL

We see that this EML file defines two custom units (though as we’ve seen gramsPerSquareMeter is actually in the standard unit list now, so that one isn’t needed.) We also see that the unitTypes table is empty, since the custom unit speciesPerSquareMeter uses the standard unitType arealDensity, which we can look up in the standards table:

which(standardUnits$unitTypes$id == "arealDensity")
## [1] 55 56
standardUnits$unitTypes[c(55,56),]
##              id         name     dimension power
## 55 arealDensity arealDensity dimensionless  <NA>
## 56 arealDensity arealDensity        length    -2

Which tells us that an arealDensity is a dimensionless unit times a length to -2 power.

Writing EML: Declaring unit types and custom units

When writing our own EML files, we must thus take care to define our units.

For tabular data (e.g. csv files), this information is provided in the attributeList element, such as we created using the set_attributes() function in the vignette, “creating EML”. When working with any numeric data, this function takes a data.frame with a column for unit that provides the name of the unit listed.

These units cannot be any free-form text, but should instead be one of the standard units recognized by EML. Since EML knows about lots of units already, this usually just means making sure we use the correct id for the desired unit in the attributes metadata. As we have seen above, the standardUnits list can help us with this. We can just skim the table by eye, or, for instance, we can look up the unit id for a some units by abbreviation:

i <- which(standardUnits$units$abbr == "btu")
j <- which(standardUnits$units$abbr == "μm³/kg")
standardUnits$units[c(i,j),]
##                          id                    name       unitType
## 84       britishThermalUnit      britishThermalUnit         energy
## 162 cubicMicrometersPerGram cubicMicrometersPerGram specificVolume
##                  parentSI    multiplierToSI constantToSI abbreviation
## 84                  joule         1055.0559         <NA>          btu
## 162 cubicMeterPerKilogram 0.000000000000001         <NA>       μm³/kg
##                    description
## 84         1 btu = 1055.0559 J
## 162 cubic micrometers per gram

note that EML names units in camelCase, with compound units spelled out. We will need to give the full unit id, not the abbreviation, to the units column when defining attribute metadata, e.g.:

df <- data.frame(attributeName = "energy", 
                   attributeDefinition = "energy absorbed by the surface", 
                   unit = "britishThermalUnit", 
                   numberType = "real",
                   stringsAsFactors = FALSE)
  attributeList <- set_attributes(df, col_classes = "numeric")

Sometimes we will want to use a unit that is not avaialble in the standardUnit list, such as the example of species per square meter seen above. To add this information to our EML file, we use set_unitList, using definitions that follow the same data.frame format we saw returned by the get_unitList() function. Here we provide the definition for species per square meter, following the camelCase convention of EML

custom_units <- data.frame(id = "speciesPerSquareMeter", unitType = "arealDensity", parentSI = "numberPerSquareMeter", multiplierToSI = 1, description = "number of species per square meter")
set_unitList(custom_units)
## <unitList>
##   <unit id="speciesPerSquareMeter" name="speciesPerSquareMeter" parentSI="numberPerSquareMeter" unitType="arealDensity" multiplierToSI="1">
##     <description>number of species per square meter</description>
##   </unit>
## </unitList>

Note that this definition refers to the unitType arealDensity, which, as we have already seen, is defined in the standard unit types. Users should consult the standardUnits$unitType table for the names and defintitions of standard types, e.g.

unique(standardUnits$unitTypes$id)
##  [1] "length"                         "time"                          
##  [3] "mass"                           "current"                       
##  [5] "temperature"                    "amount"                        
##  [7] "luminosity"                     "dimensionless"                 
##  [9] "angle"                          "acceleration"                  
## [11] "charge"                         "magneticFieldStrength"         
## [13] "currentDensity"                 "area"                          
## [15] "lengthReciprocal"               "frequency"                     
## [17] "volume"                         "volumetricArea"                
## [19] "speed"                          "massDensity"                   
## [21] "massPerMass"                    "volumePerVolume"               
## [23] "volumetricRate"                 "volumetricMassDensityRate"     
## [25] "arealMassDensityRate"           "specificVolume"                
## [27] "amountOfSubstanceConcentration" "amountOfSubstanceWeight"       
## [29] "amountOfSubstanceWeightFlux"    "massFlux"                      
## [31] "luminance"                      "volumetricDensity"             
## [33] "arealDensity"                   "arealMassDensity"              
## [35] "specificArea"                   "force"                         
## [37] "energy"                         "power"                         
## [39] "potentialDifference"            "capacitance"                   
## [41] "resistance"                     "resistivity"                   
## [43] "conductance"                    "magneticFlux"                  
## [45] "magneticFluxDensity"            "inductance"                    
## [47] "illuminance"                    "radionucleotideActivity"       
## [49] "specificEnergy"                 "doseEquivalent"                
## [51] "catalyticActivity"              "pressure"                      
## [53] "transmissivity"                 "massSpecificLength"            
## [55] "massSpecificCount"

Likewise, parentSI should refer to a unit already defined in the standard unit dictionary, or otherwise provided by similar custom definition. A multiplierToSI should be provided. If necessary an additive constantToSI can also be provided. An abbreviation and description of the unit is optional.

In even rarer cases, a unitType might not be available in the standard unit list. It is possible to convert between different units that share a common unitType such as length, but not units with different unitTypes. This may be particularly applicable for compound units: for instance, there is no unit type with dimensions of length per time cubed, (equivalently, acceleration per time, also known as a “jerk”). We can define a custom unit type by providing the appropriate data frame, with one row for each base type. Note we have to repeat the id for each row that is shared by the unit. The unit definition follows from the product of the each of the base dimensions raised to the power given (a missing value for power is equivalent to a power of 1), e.g. for our jerk:

unitType <- data.frame(id = c("jerk", "jerk"), dimension = c("length", "time"), power = c(1, -3) )

Of course we cannot use a unitType without a unit to measure it in, so we define the SI unit as well (note we do not need a parentSI or multiplier because this is already an SI unit):

unit <- data.frame(id = "meterPerSecondCubed", unitType = "jerk")

We can now generate the required unitList:

unitList <- set_unitList(unit, unitType)

Note that there are often many equivalent ways to express a unit (our jerk could have been acceleration per time instead). Before defining a new unitType, some dilegence may help you recognize a unitType that has already been defined in a different way.

Adding the unitList to the EML document

As we have seen above, the custom unit declearations must be found in the additionalMetadata section of an EML file. To do so, we can simply coerce the unitList into an additionalMetadata element when creating our eml object:

eml <- new("eml", additionalMetadata = as(unitList, "additionalMetadata"))