# Metadata and Data units

#### Victor Granda (Sapfluxnet Team)

#### 2023-01-25

## Metadata

Metadata numeric variables come in different units depending on the variable. One easy way to check for a variable units is to use the `describe_md_variable` function:

    library(sapfluxnetr)
    describe_md_variable('si_elev')
    #> Description:
    #> Elevation above sea level
    #>
    #> Values:
    #> Contributor defined |
    #>
    #> Units:
    #> meters
    #>
    #> Type:
    #> Numeric
    describe_md_variable('st_age')
    #> Description:
    #> Mean stand age at the moment of sap flow measurements
    #>
    #> Values:
    #> Contributor defined |
    #>
    #> Units:
    #> years
    #>
    #> Type:
    #> Numeric

As it can be seen, site elevation is in meters and stand age is in years.

Nevertheless, and for the sake of completion, here you can find a complete list of the metadata variables and their units:

| variable | description | type | units
--- | --- | --- | --- | ---
1 | si_name | Site name given by contributors | Character | None
2 | si_country | Country code (ISO) | Character | Fixed values
3 | si_contact_firstname | Contributor first name | Character | None
4 | si_contact_lastname | Contributor last name | Character | None
5 | si_contact_email | Contributor email | Character | None
6 | si_contact_institution | Contributor affiliation | Character | None
7 | si_addcontr_firstname | Additional contributor first name | Character | None
8 | si_addcontr_lastname | Additional contributor last name | Character | None
9 | si_addcontr_email | Additional contributor email | Character | None
10 | si_addcontr_institution | Additional contributor affiliation | Character | None
11 | si_lat | Site latitude (i.e. 42.36) | Numeric | Latitude, decimal format (WGS84)
12 | si_long | Site longitude (i.e. -8.23) | Numeric | Longitude, decimal format (WGS84)
13 | si_elev | Elevation above sea level | Numeric | meters
14 | si_paper | Paper with relevant information to understand the site as DOI links or DOI codes | Character | DOI link
15 | si_dist_mgmt | Recent and historic disturbance and management events that affected the measurement years | Character | Fixed values
16 | si_igbp | Vegetation type based on IGBP classification | Character | Fixed values
17 | si_flux_network | Logical indicating if site is participating in the FLUXNET network | Logical | Fixed values
18 | si_dendro_network | Logical indicating if site is participating in the DENDROGLOBAL network | Logical | Fixed values
19 | si_remarks | Remarks and commentaries useful to grasp some site-specific peculiarities | Character | None
20 | si_code | sapfluxnet site code, unique for each site | Character | Fixed value
21 | si_mat | Site annual mean temperature, as obtained from WorldClim | Numeric | Celsius degrees
22 | si_map | Site annual mean precipitation, as obtained from WorldClim | Numeric | mm
23 | si_biome | Biome classification as per Whittaker diagram, based on mat and map obtained from WorldClim | Character | sapfluxnet calculated
24 | st_name | Stand name given by contributors | Character | None
25 | st_growth_condition | Growth condition with respect to stand origin and management | Character | Fixed values
26 | st_treatment | Treatment applied at stand level | Character | None
27 | st_age | Mean stand age at the moment of sap flow measurements | Numeric | years
28 | st_height | Canopy height | Numeric | meters
29 | st_density | Total stem density for stand | Numeric | stems/ha
30 | st_basal_area | Total stand basal area | Numeric | m2/ha
31 | st_lai | Total maximum stand leaf area (one-sided, projected) | Numeric | m2/m2
32 | st_aspect | Aspect the stand is facing (exposure) | Character | Fixed values
33 | st_terrain | Slope and/or relief of the stand | Character | Fixed values
34 | st_soil_depth | Soil total depth | Numeric | cm
35 | st_soil_texture | Soil texture class, based on simplified USDA classification | Character | Fixed values
36 | st_sand_perc | Soil sand content, % mass | Numeric | % percentage
37 | st_silt_perc | Soil silt content, % mass | Numeric | % percentage
38 | st_clay_perc | Soil clay content, % mass | Numeric | % percentage
39 | st_remarks | Remarks and commentaries useful to grasp some stand-specific peculiarities | Character | None
40 | st_USDA_soil_texture | USDA soil classification based on the percentages provided by the contributor | Character | sapfluxnet calculated
41 | sp_name | Identity of each measured species | Character | Scientific name without author abbreviation, as accepted by The Plant List
42 | sp_ntrees | Number of trees measured of each species | Numeric | number of trees
43 | sp_leaf_habit | Leaf habit of the measured species | Character | Fixed values
44 | sp_basal_area_perc | Basal area occupied by each measured species, in percentage over total stand basal area | Numeric | % percentage
45 | pl_name | Plant code assigned by contributors | Character | None
46 | pl_species | Species identity of the measured plant | Character | Scientific name without author abbreviation, as accepted by The Plant List
47 | pl_treatment | Experimental treatment (if any) | Character | None
48 | pl_dbh | Diameter at breast height of measured plants | Numeric | cm
49 | pl_height | Height of measured plants | Numeric | m
50 | pl_age | Plant age at the moment of measure | Numeric | years
51 | pl_social | Plant social status | Character | Fixed values
52 | pl_sapw_area | Cross-sectional sapwood area | Numeric | cm2
53 | pl_sapw_depth | Sapwood depth, measured at breast height | Numeric | cm
54 | pl_bark_thick | Plant bark thickness | Numeric | mm
55 | pl_leaf_area | Leaf area of eachvvmeasured plant | Numeric | m2
56 | pl_sens_meth | Sap flow measures method | Character | Fixed values
57 | pl_sens_man | Sap flow measures sensor manufacturer | Character | Fixed values
58 | pl_sens_cor_grad | Correction for natural temperature gradients method | Character | Fixed values
59 | pl_sens_cor_zero | Zero flow determination method | Character | Fixed values
60 | pl_sens_calib | Was species-specific calibration used? | Logical | Fixed values
61 | pl_sap_units | Uniformized sapfluxnet units for sapwood, leaf and plant level | Character | Fixed values
62 | pl_sap_units_orig | Original contribution units (at sapwood or plant level) | Character | Fixed values
63 | pl_sens_length | Length of the needles or electrodes forming the sensor | Numeric | mm
64 | pl_sens_hgt | Sensor installation height, measured from the ground | Numeric | m
65 | pl_sens_timestep | Subdaily time step of sensor measures | Numeric | minutes
66 | pl_radial_int |  | Character | Fixed values
67 | pl_azimut_int |  | Character | Fixed values
68 | pl_remarks | Remarks and commentaries useful to grasp some plant-specific peculiarities | Character | None
69 | pl_code | sapfluxnet plant code, unique for each plant | Character | Fixed value
70 | env_time_zone | Time zone of site used in the TIMESTAMPS | Character | Fixed values
71 | env_time_daylight | Is daylight saving time applied to the original timestamp? | Logical | Fixed values
72 | env_timestep | Subdaily timestep of environmental measures | Numeric | minutes
73 | env_ta | Location of air temperature sensor | Character | Fixed values
74 | env_rh | Location of relative humidity sensor | Character | Fixed values
75 | env_vpd | Location of relative vapour pressure decifit sensor | Character | Fixed values
76 | env_sw_in | Location of shortwave incoming radiation sensor | Character | Fixed values
77 | env_ppfd_in | Location of incoming photosynthetic photon flux density sensor | Character | Fixed values
78 | env_netrad | Location of net radiation sensor | Character | Fixed values
79 | env_ws | Location of wind speed sensor | Character | Fixed values
80 | env_precip | Location of precipitation sensor | Character | Fixed values
81 | env_swc_shallow_depth | Average depth for shallow soil water content measures | Numeric | cm
82 | env_swc_deep_depth | Average depth for deep soil water content measures | Numeric | cm
83 | env_plant_watpot | Availability of water potential values for the same measured plants during the sap flow measurements period | Character | Fixed values
84 | env_leafarea_seasonal | Availability of seasonal course leaf area data and level | Character | Fixed values
85 | env_remarks | Remarks and commentaries useful to grasp some environmental-specific peculiarities | Character | None

## Data

### Sap flow units

Sap flow units depends on the database level chosen:

\[Plant:~\frac{cm³}{h}\] \[Sapwood:~\frac{cm³}{cm²_{sa}·h}\] \[Leaf:~\frac{cm³}{cm²_{la}·h}\]

### Environmental variables

Environmental variables come in the following units:

| Variable | Description | Units
--- | --- | --- | ---
1 | env_ta | Air temperature | ºC
2 | env_rh | Air relative humidity | %
3 | env_vpd | Vapour pressure deficit | kPa
4 | env_sw_in | Shortwave incoming radiation | W m-2
5 | env_ppfd | Incoming photosynthetic photon flux density | micromols m-2 s-1
6 | env_netrad | Net radiation | W m-2
7 | env_ws | Wind speed | m s-1
8 | env_precip | Precipitation | mm timestep-1
9 | env_swc_shallow | Shallow soil water content | cm3 cm-3
10 | env_swc_deep | Deep soil water content | cm3 cm-3

## Timestamps

### TIMESTAMP

`TIMESTAMP` variable comes as provided by the contributors and timezone is applied per the site metadata description:

    library(dplyr)
    library(lubridate)
    #> Loading required package: timechange
    #>
    #> Attaching package: 'lubridate'
    #> The following objects are masked from 'package:base':
    #>
    #>     date, intersect, setdiff, union

    # timezone provided by contributor
    get_env_md(ARG_TRE) %>% pull(env_time_zone)
    #> [1] "13UTC-03:00, P"

    # timezone in the TIMESTAMP
    get_timestamp(ARG_TRE) %>% tz()
    #> [1] "Etc/GMT+3"

As you can see, the final timezone is in GMT format.

### Solar TIMESTAMP

When inspecting the solar `TIMESTAMP` variable, timezone declared is UTC:

    get_solar_timestamp(ARG_TRE) %>% tz()
    #> [1] "UTC"

This is so because solar timestamp is only referred to the sun position in the sky, rendering the timezone useless in this case. So UTC was chosen as timezone to be able to join and compare global data.