Ci

.github/workflows/CI.yml

@@ -3,6 +3,7 @@ on:
   push:
     branches:
       - main
+      - ci
     tags: '*'
   pull_request:
 jobs:
@@ -14,7 +15,7 @@ jobs:
       matrix:
         version:
           - '1'
-          - '1.6'
+          - '^1.7.0-0'
         os:
           - ubuntu-latest
         arch:

.gitignore

@@ -4,3 +4,5 @@
 /Manifest.toml
 /docs/build/
 /tmp
+docs/Manifest.toml
+test/Manifest.toml

Project.toml

@@ -7,19 +7,24 @@ version = "0.1.1-DEV"
 AstroLib = "c7932e45-9af1-51e7-9da9-f004cd3a462b"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
+FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 LabelledArrays = "2ee39098-c373-598a-b85f-a56591580800"
+Missings = "e1d29d7a-bbdc-5cf2-9ac0-f12de2c33e28"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"
+Pipe = "b98c9c47-44ae-5843-9183-064241ee97a0"
 RecursiveArrayTools = "731186ca-8d62-57ce-b412-fbd966d074cd"
 StaticArrays = "90137ffa-7385-5640-81b9-e52037218182"
+Suppressor = "fd094767-a336-5f1f-9728-57cf17d0bbfb"
+TimeZones = "f269a46b-ccf7-5d73-abea-4c690281aa53"
 
 [compat]
-julia = "1"
 AstroLib = "0.4"
 DataFrames = "1"
 LabelledArrays = "1"
 Optim = "1"
 RecursiveArrayTools = "2"
 StaticArrays = "1"
+julia = "1.6, 1.7"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

docs/make.jl

@@ -13,6 +13,7 @@ makedocs(;
     authors="Thomas Wutzler <twutz@bgc-jena.mpg.de>. Jürgen Knauer <Juergen.Knauer@csiro.au> and contributors",
     repo="https://github.com/bgctw/Bigleaf.jl/blob/{commit}{path}#{line}",
     sitename="Bigleaf.jl",
+    doctestfilters=[r".*Info.*"],
     format=Documenter.HTML(;
         prettyurls=get(ENV, "CI", "false") == "true",
         canonical="https://bgctw.github.io/Bigleaf.jl",
@@ -24,6 +25,7 @@ makedocs(;
         #"Unit conversions" => "unit_conversions.md",
         "Walkthrough" => "walkthrough.md",
         hide("metorological_variables.md"),
+        hide("evapotranspiration.md"),
         hide("global_radiation.md"),
         hide("unit_conversions.md"),
         hide("bigleaf_constants.md"),

docs/src/evapotranspiration.md

@@ -0,0 +1,9 @@
+## Evapotranspiration
+```@index
+Pages = ["evapotranspiration.md",]
+```
+
+```@docs
+potential_ET
+equilibrium_imposed_ET
+```

docs/src/global_radiation.md

@@ -4,6 +4,8 @@ Pages = ["global_radiation.md",]
 ```
 
 ```@docs
+potential_radiation
+extraterrestrial_radiation
 calc_sun_position_hor
 calc_sun_position_MOD
-```
+```

docs/src/index.md

@@ -13,6 +13,11 @@ Pages = ["index.md",]
 Pages = ["metorological_variables.md",]
 ```
 
+## Evapotranspiration
+```@index
+Pages = ["evapotranspiration.md",]
+```
+
 ## Global radiation
 ```@index
 Pages = ["global_radiation.md",]

docs/src/walkthrough.md

@@ -28,7 +28,8 @@ using Latexify
 using DataDeps, Suppressor
 using RData
 import CodecBzip2, CodecXz
-@suppress_err register(DataDep(
+#@suppress_err # error in github-actions: GitHubActionsLogger has no field stream
+register(DataDep(
     "DE_Tha_Jun_2014.rda",
     "downloading exampple dataset DE_Tha_Jun_2014 from bitbucket.org/juergenknauer/bigleaf",
     "https://bitbucket.org/juergenknauer/bigleaf/raw/0ebe11626b4409305951e8add9f6436703c82584/data/DE_Tha_Jun_2014.rda",
@@ -70,9 +71,60 @@ There are a few general guidelines that are important to consider when using the
 
 ## Units
 
-It is imperative that variables are provided in the right units, as the plausibility of the input units is not checked in most cases. The required units of the input arguments can be found in the respective help file of the function. The good news is that units do not change across functions. For example, pressure is always required in kPa, and temperature always in °c.
+It is imperative that variables are provided in the right units, as the plausibility of 
+the input units is not checked in most cases. The required units of the input arguments 
+can be found in the respective help file of the function. The good news is that units 
+do not change across functions. For example, pressure is always required in kPa, 
+and temperature always in °c.
 
-## TODO ##
+## Function arguments
+
+Most functions of `Bigleaf.jl` require a DataFrame, from which the required
+variables are extracted. This is usually the first argument of a function. 
+Most functions further provide default values for their arguments, 
+such that in many cases it is not necessary to provide them explicitly.
+
+The column names in the DataFrame should correspond to the argument names
+of the corresponding method that accespts each input individually.
+
+We can demonstrate the usage with a simple example:
+
+```@example doc
+# explicit inputs
+Tair, pressure, Rn, =  14.81, 97.71, 778.17 
+potential_ET(Tair, pressure, Rn, Val(:PriestleyTaylor))
+# DataFrame
+potential_ET(tha, Val(:PriestleyTaylor))
+# DataFrame with a few columns overwritten by user values
+potential_ET(transform(tha, :Tair => x -> 25.0; renamecols=false), Val(:PriestleyTaylor))
+# varying one input only
+Tair_vec =  10.0:1.0:20.0
+DataFrame(potential_ET.(Tair_vec, pressure, Rn, Val(:PriestleyTaylor)))
+nothing # hide
+```
+
+## Ground heat flux and storage fluxes
+
+Many functions require the available energy ($A$), which is defined as ($A = R_n - G - S$, 
+all in $\text{W m}^{-2}$), where $R_n$ is the net radiation, $G$ is the ground heat flux, 
+and $S$ is the sum of all storage fluxes of the ecosystem 
+(see e.g. Leuning et al. 2012 for an overview). For some sites, $G$ is not available, 
+and for most sites, only a few components of $S$ are measured. 
+
+In `Bigleaf.jl` it is not a problem if $G$ and/or $S$ are missing (other than the results might be (slightly) biased), but special options exist for the treatment of missing $S$ and $G$ values. 
+
+Note that the default for G and S in the dataframe variant is missing (and assumed zero), 
+even if those columns are
+present in the DataFrame. You need to explictly pass those columns with the optional
+arguments: e.g. `potential_ET(df, Val(:PriestleyTaylor); G = df.G)`
+
+Note that in difference to the bigleaf R package missing entries in a provide
+vector are not relaced by zero by default. 
+You need to explitly use coalesce when specifying a ground heat flux
+for which missings should be replaced by zero: `;G = coalesce(df.G, zero(df.G))`
+
+
+# Function walkthrough #
 
 ## Meteorological variables
 
@@ -142,28 +194,32 @@ The following figure compares them at absole scale and as difference to the
 
 ## Global radiation
 
-Computing solar position in horizontal coordinates
+Potential radiation for given time and latitude:
+```@example doc
+doy, hour = 160, 10.5
+lat, long = 51.0, 11.5
+potrad = potential_radiation(doy, hour, lat, long)
+```
+
+Calculation is based on sun's altitude, one of the horizontal coordinates of its position.
 ```@example doc
 using Plots, StatsPlots, DataFrames, Dates, Pipe, Suppressor
 hours = 0:24
 lat,long = 51.0, 13.6 # Dresden Germany
 #deg2second = 24*3600/360
 doy = 160
 datetimes = DateTime(2021) .+Day(doy-1) .+ Hour.(hours) #.- Second(round(long*deg2second))
-res3 = @suppress_err @pipe calc_sun_position_hor.(datetimes, lat, long) |> toDataFrame(_)
+res3 = @pipe calc_sun_position_hor.(datetimes, lat, long) |> DataFrame(_)
 @df res3 scatter(datetimes, cols([:altitude,:azimuth]), legend = :topleft, xlab="Date and Time", ylab = "rad")
-savefig("fig/globrad.svg")
 ```
 
-![](fig/globrad.svg)
-
 The hour-angle at noon represents the difference to
 local time. In the following example solar time is
 about 55min ahead of local winter time.
 
 ```@example doc
 summernoon = DateTime(2021) +Day(doy-1) + Hour(12) 
-sunpos = @suppress_err calc_sun_position_hor(summernoon, lat, long) 
+sunpos = calc_sun_position_hor(summernoon, lat, long) 
 sunpos.hourangle * 24*60/(2*π) # convert angle to minutes
 ```
 

inst/fromR/WUE_metrics.jl

@@ -12,56 +12,59 @@
 #' - LE        Latent heat flux (W m-2)
 #' - VPD       Vapor pressure deficit (kPa)
 #' - Tair      Air temperature (deg C)
-#' - constants Cmol - molar mass of carbon (kg mol-1) \cr
-#'                  umol2mol - conversion micromole (umol) to mole (mol) \cr
+#' - constants Cmol - molar mass of carbon (kg mol-1) 
+#'                  umol2mol - conversion micromole (umol) to mole (mol) 
 #'                  kg2g - conversion kilogram (kg) to gram (g)
 #'
 #' # Details
  the following metrics are calculated:
 #' 
 #'          Water-use efficiency (WUE):
 #'          
-#'            \deqn{WUE = GPP / ET}
+#'            ``WUE = GPP / ET``
 #'          
 #'          Water-use efficiency based on NEE (WUE_NEE):
 #'          
-#'            \deqn{WUE_NEE = NEE / ET}
+#'            ``WUE_NEE = NEE / ET``
 #'          
 #'          Inherent water-use efficiency (IWUE; Beer et al. 2009):
 #'          
-#'            \deqn{IWUE = (GPP * VPD) / ET}
+#'            ``IWUE = (GPP * VPD) / ET``
 #'          
 #'          Underlying water-use efficiency (uWUE; Zhou et al. 2014):
 #'          
-#'            \deqn{uWUE= (GPP * sqrt(VPD)) / ET}
+#'            ``uWUE= (GPP * sqrt(VPD)) / ET``
 #'          
 #'          All metrics are calculated based on the median of all values. E_g.
 #'          WUE = median(GPP/ET,na_rm=TRUE)
 #' 
 #' # Value
  a named vector with the following elements:
-#'         \item{WUE}{Water-use efficiency (gC (kg H20)-1)}
-#'         \item{WUE_NEE}{Water-use efficiency based on NEE (gC (kg H20)-1)}
-#'         \item{IWUE}{Inherent water-use efficiency (gC kPa (kg H20)-1)}
-#'         \item{uWUE}{Underlying water-use efficiency (gC kPa^0.5 (kg H20)-1)}
+#'         - WUE: Water-use efficiency (gC (kg H20)-1)
+#'         - WUE_NEE: Water-use efficiency based on NEE (gC (kg H20)-1)
+#'         - IWUE: Inherent water-use efficiency (gC kPa (kg H20)-1)
+#'         - uWUE: Underlying water-use efficiency (gC kPa^0.5 (kg H20)-1)
 #' 
-#' @note Units for VPD can also be hPa. Units change accordingly.
+#' # Note
+#' Units for VPD can also be hPa. Units change accordingly.
 #'       WUE_NEE is calculated based on the absolute value of NEE (the sign convention does not matter here).
 #' 
-#' @references Beer, C., et al., 2009: Temporal and among-site variability of inherent
+#' #References
+#' Beer, C., et al., 2009: Temporal and among-site variability of inherent
 #'             water use efficiency at the ecosystem level. Global Biogeochemical Cycles 23, GB2018.
 #'             
 #'             Zhou, S., et al., 2014: The effect of vapor pressure deficit on water
 #'             use efficiency at the sub-daily time scale. Geophysical Research Letters 41.
 #'     
-#' @seealso \code{\link{stomatal_slope}} for a measure of intrinsic WUE          
+#' #See also
+#' [`stomatal_slope`](@ref) for a measure of intrinsic WUE          
 #'                             
 #' ```@example; output = false
 #' ``` 
 #' ## filter data for dry periods and daytime at DE-Tha in June 2014
-#' DE_Tha_Jun_2014_2 = filter_data(DE_Tha_Jun_2014,quality_control=FALSE,
+#' DE_Tha_Jun_2014_2 = filter_data(DE_Tha_Jun_2014,quality_control=false,
 #'                                  vars_qc=c("Tair","precip","VPD","H","LE"),
-#'                                  filter_growseas=FALSE,filter_precip=TRUE,
+#'                                  filter_growseas=false,filter_precip=TRUE,
 #'                                  filter_vars=c("Tair","PPFD","ustar"),
 #'                                  filter_vals_min=c(5,200,0.2),
 #'                                  filter_vals_max=c(NA,NA,NA),NA_as_invalid=TRUE,
@@ -82,8 +85,8 @@ function WUE_metrics(data,GPP="GPP",NEE="NEE",LE="LE",VPD="VPD",Tair="Tair",
   check_input(data,list(GPP,NEE,LE,VPD,Tair))
 
   ET  = LE_to_ET(LE,Tair)                 # kg H2O m-2 s-1
-  GPP = (GPP * constants$umol2mol * constants$Cmol) * constants$kg2g  # gC m-2 s-1
-  NEE = (NEE * constants$umol2mol * constants$Cmol) * constants$kg2g  # gC m-2 s-1
+  GPP = (GPP * constants[:umol2mol] * constants[:Cmol]) * constants[:kg2g]  # gC m-2 s-1
+  NEE = (NEE * constants[:umol2mol] * constants[:Cmol]) * constants[:kg2g]  # gC m-2 s-1
 
   WUE     = median(GPP/ET,na_rm=TRUE)
   WUE_NEE = median(abs(NEE)/ET,na_rm=TRUE)