FieldClim Package Update Documentation

Introduction

This document provides detailed documentation of the recent updates and improvements made to various functions within the fieldClim package. These updates primarily address issues related to radiation, sensible heat flux, and latent heat flux functions. Additionally, the standardization of energy flow signs (+/-) and enhanced documentation for each function are also included.

Overview of Changes:

R Studio help pages: Comprehensive documentation has been created for all functions in the package.
plot_weather_station(): New function added which plots all time series data of a weather_station object.
bound_thermal_avg(): Updated parameters for turb_ustar(v1, z1) to v and z to match required input.
latent_priestley_taylor(): Fixed an error in the formula that caused negative values where positive values were expected.
latent_penman(): Completely revised the formula to the correct version, and included soil flux for calculation.
latent_monin(): Added the possibility to set a cap for the stability parameter s1 (measurement height / Monin-Obukhov length) to handle cases where the Monin-Obukhov length approaches zero, which results in really high s1 values..
latent_bowen(): Added the possibility to set a cap parameter to prevent unrealistically high latent heat flux when (1 + B) approaches zero.
sensible_bowen(): Applied the same cap parameter as in latent_bowen() to avoid unrealistic values.
sensible_monin(): Applied the same cap as in latent_monin() to avoid unrealistic values.
sensible_priestley_taylor(): Corrected the sign direction for the calculation.
solar_azimuth(), sol_hour_angle(): Changed the timezone used from UTC to local time zone
soil_heat_flux(): Reversed the sign for the flux direction to ensure consistency.

1. Added proper Help Page Details

The biggest part of this update includes the improved R Studio Help pages. The help documentation for each function in RStudio now features a comprehensive “Details” section that provides an in-depth explanation of the function’s purpose and operation. For functions based on mathematical formulas, these formulas are now included and thoroughly explained within this section. This enhancement significantly improves user-friendliness, making the package accessible to users who were not involved in its development. Additionally, each help page now includes example code and specifies the unit of the output value, further aiding in the practical application of the functions.

Figure 1: Example R Studio help page of the sensible_monin() function

2. `plot_weather_station()`

The plot_weather_station() function is a new addition to the package that provides a simple and intuitive way to visualize time series data stored within a weather_station object. The function can either plot a single specified variable or generate a grid of plots for all time-series variables within the object. - Functionality: - Single Variable Plot: Users can specify a single variable by name to plot its time series. - Multiple Variable Plot: If no variable is specified, the function automatically detects all time-series variables (those with the same length as the datetime variable) and generates a grid of plots. - Automatic Labeling: The function includes a built-in mapping of variable names to descriptive labels with appropriate units, ensuring that plots are informative and easy to interpret. - Usage:

This will create a plot of the air temperature time series.

plot_weather_station(weather_station, variable_name = "temp")

This will create a grid of plots for all available time-series variables within the weather_station object.

plot_weather_station(weather_station)

3. `bound_thermal_avg()`

The function is calling the turb_ustar() function. However the arguments of the function are not called v1 and z1 but v and z. This is now fixed in the new Version.

bound_thermal_avg <- function(v, z, temp_change_dist, t_pot_upwind, t_pot, lapse_rate,
                              surface_type = NULL, obs_height = NULL) {
  # Calculate ustar
  if (!is.null(obs_height)) {
    ustar <- turb_ustar(v1 = v, z1 = z, obs_height = obs_height) # v1 -> v, z1 -> z 
  } else if (!is.null(surface_type)) {
    ustar <- turb_ustar(v1 = v, z1 = z, surface_type = surface_type) # v1 -> v, z1 -> z 
  } else {
    print("The input is not valid. Either obs_height or surface_type has to be defined.")
  }
  (ustar / v) * ((temp_change_dist * abs(t_pot_upwind - t_pot)) / abs(lapse_rate))**0.5
}

4. `latent_priestley_taylor()`

Here an error was fixed in the formula that caused negative values where positive values were expected.

# Old formula
out <- alpha_pt * sc * (-rad_bal - soil_flux) / (sc + gam)

# New formula
out <- alpha_pt * (delta / (delta + gamma)) * (rad_bal - soil_flux)

5. `latent_penman()`

For this function the formula was revised completely. Before the water package was used which is now deprecated. The function now includes soil flux, surface resistance and aerodynamic resistance for calculation. Values for surface resistance where taken from literature, same as the formula and other calculations needed: *- Monteith, John L., Mike H. Unsworth, and Ann Webb. “Principles of environmental physics.” Quarterly Journal of the Royal Meteorological Society 120.520 (1994): 1699. The parameters obs_height and surface_type to calculate the aerodynamic resistance and get the right value for surface resistance. The formula used looks like this:

\\[ Q_e = \\frac{\\Delta \\times (R_n - G) + \\gamma \\times \\left(\\frac{c_p \\times \\rho}{r_a}\\right) \\times (e_s - e_a)}{\\Delta + \\gamma \\times \\left(1 + \\frac{r_s}{r_a}\\right)} \\\]

where:

\(Q_e\) is the latent heat flux (W/m²).
\(\\Delta\) is the slope of the vapor pressure curve (kPa/°C).
\(R_n\) is the net radiation (W/m²).
\(G\) is the soil heat flux density (W/m²).
\(\\gamma\) is the psychrometric constant (kPa/°C).
\(c_p\) is the specific heat of air at constant pressure (J/kg/°C).
\(\\rho\) is the air density (kg/m³).
\(r_a\) is the aerodynamic resistance (s/m).
\(r_s\) is the surface resistance (s/m).
\(e_s\) is the saturation vapor pressure (kPa).
\(e_a\) is the actual vapor pressure (kPa). ]

Figure 2: Comparison of results of old and new latent_penman() function using ‘energie_bil_wiese.csv’

6. `latent_monin()`

The function latent_monin() includes the stability correction for humidity. The calculation of this correction is based on the stability parameter \(s_1\), which is defined as:

\\[ s_1 = \\frac{\\text{measurement height}}{\\text{Monin-Obukhov length}} \\\]

However when the Monin-Obukhov length approaches zero, \(s_1\) can become extremely large, leading to unrealistic values in further calculations. To address this, a possibility to set a cap for \(s_1\) was added. The cap is NULL by default and can be set with cap = x.

In the function the cap use looks like this:

if(!is.null(cap)){
    # Apply cap
    s1 <- pmax(pmin(s1, cap), -cap)
  }

Also an error was fixed in the formula that caused negative values where positive values were expected.

Figure 3: Comparison of results of old and new latent_monin() function using cap = 20 and ‘energie_bil_wiese.csv’

7. `latent_bowen()`

The latent heat flux \(Q_e\) in the Bowen ratio method is calculated using the formula:

\\[ Q_e = \\frac{Q_n - Q_g}{1 + B} \\\]

Where:

\(Q_e\) is the latent heat flux (W/m²).
\(Q_n\) is the net radiation (W/m²).
\(Q_g\) is the soil heat flux (W/m²).
\(B\) is the Bowen ratio, defined as the ratio of sensible heat flux to latent heat flux. Here there was a similar problem as for the latent_monin() function. When \((1 + B)\) approaches zero, \(Q_e\) can become extremely large, leading to unrealistic values. To prevent this, a cap \(C\) is introduced ensuring that \((1 + B)\) does not approach zero by maintaining a minimum value set by the cap. The cap is NULL by default and can be set with cap = x.

In the function the cap use looks like this:

denominator <- 1 + bowen_ratio
  if(!is.null(cap)){
    denominator[abs(denominator) < cap] <- cap * sign(denominator[abs(denominator) < cap])
  }

Also an error was fixed in the formula that caused negative values where positive values were expected.

Figure 4: Comparison of results of old and new latent_bowen() function using cap = 1 and ‘energie_bil_wiese.csv’

8. `sensible_monin()` `sensible_bowen()`

For these functions the same new cap parameter was added to the function as for latent_monin() and latent_bowen().

9. `solar_azimuth()` `sol_hour_angle()`

In the previous implementation of solar_azimuth() and sol_hour_angle(), the solar_medium_suntime() function, which converts time to UTC, was used. However, these calculations require local time. Therefore, the use of solar_medium_suntime() was removed, and local time is now directly utilized. This error caused time shifts in all radiation calculations, but with these changes this issue has now been resolved.

10. `soil_heat_flux()`

Here the sign for the flux direction was reversed to ensure consistency.

-thermal_cond * (soil_temp1 - soil_temp2) / (soil_depth1 - soil_depth2)

Konstantin Engelmayer

2024-08-10

Introduction

Overview of Changes:

1. Added proper Help Page Details

2. `plot_weather_station()`

3. `bound_thermal_avg()`

4. `latent_priestley_taylor()`

5. `latent_penman()`

6. `latent_monin()`

7. `latent_bowen()`

8. `sensible_monin()` `sensible_bowen()`

9. `solar_azimuth()` `sol_hour_angle()`

10. `soil_heat_flux()`

FieldClim Package Update Documentation

Konstantin Engelmayer

2024-08-10

Introduction

Overview of Changes:

1. Added proper Help Page Details

2. plot_weather_station()

3. bound_thermal_avg()

4. latent_priestley_taylor()

5. latent_penman()

6. latent_monin()

7. latent_bowen()

8. sensible_monin() sensible_bowen()

9. solar_azimuth() sol_hour_angle()

10. soil_heat_flux()

2. `plot_weather_station()`

3. `bound_thermal_avg()`

4. `latent_priestley_taylor()`

5. `latent_penman()`

6. `latent_monin()`

7. `latent_bowen()`

8. `sensible_monin()` `sensible_bowen()`

9. `solar_azimuth()` `sol_hour_angle()`

10. `soil_heat_flux()`