metrics: End-user functions that calculate a specific 'metric'

In DrylandEcology/rSW2metrics: Calculate Ecohydrological Metrics from SOILWAT2 Simulations

End-user functions that calculate a specific metric

Description

These functions have a name that starts with metric_. They have at least the following arguments: path, name_sw2_run, zipped_runs, id_scen_used, list_years_scen_used, out, and ....

Arguments

path	A character string. The path to the simulation project folder that contains the individual folder of each simulated site.
name_sw2_run	A character string. The name of the folder (or zip archive, see zipped_runs) of the simulated site for which metrics are to be calculated. rSOILWAT2 input and output is organized following conventions of rSFSW2, i.e., inputs for each scenario are stored in a list object named “swRunScenariosData” which is stored on disk as a file “sw_input.RData”; and output data is stored for each scenario separately in an object named “runDataSC” in a file “sw_output_scX.RData” where X is the number of the scenario.
zipped_runs	A logical value. Describes whether name_sw2_run is a zip archive or a regular folder.
id_scen_used	An integer vector. The numbers of scenarios for which metrics are to be calculated.
list_years_scen_used	A list of integer vectors. Each scenario in id_scen_used must have a corresponding vector of calendar years (for which the metrics) will be calculated.
out	A character string. Signaling whether the functions returns a time series of yearly values or an aggregate (e.g., mean) across years. One of “ts_years” or “across_years”.
soils	A named list of numeric vectors. The presence of the argument soils indicates that the function in question requires soil information as inputs. The named elements include “depth_cm”, “sand_frac”, and “clay_frac” and contain the respective values for each soil layer at the site.
...	Additional arguments

Value

• A data.frame with a least two columns "site" (identifying sites) and "group" (identifying different variables, soil layers, or sub-annual time steps)

• If do_collect_inputs, then a data.frame where rows represent sites (identified by column "site") and columns represent soil layers (columns varname_LX where X is the soil layer number).

• Otherwise (i.e., for regular metrics), a data.frame:

  • rows represent combinations of sites (identified by column "site") and "groups" (identified by column "group" for different variables, soil layers, or sub-annual time steps: seasonal “season”, quarterly “Q”, monthly “mon”, daily “doy”);

  • values of annual time series for different scenarios are present, if is_out_ts, in columns with names: scX_YYYY (where X is the scenario number and YYYY is the calendar year);

  • values of across-year aggregations are present if the metric itself calculates them or if they were added by the option add_aggs_across_yrs, in columns with names fun_scX_YYYY-ZZZZ (where "fun" is the aggregation function, X is the scenario, YYYY the start year and ZZZZ the end year of the period across which the aggregation was calculated)

Details

Each metric function produces a set of variables (one to many) at a time step that is specified in the name of the metric function. The default time step is annual (which may be omitted from the name of the function); sub-annual time steps include (case-insensitive): Seasonal (1 to 12 seasons per year); quarterly; monthly; and daily.

Notes

The metric metric_SW2toTable_daily() is an exception and produces a different type of output, i.e., spreadsheets of the most important daily SOILWAT2 variables, see SW2toTable.

List of currently available metrics:

• metric_AI

• metric_CWD

• metric_Climate_annual

• metric_Climate_monthly

• metric_Climate_quarterly

• metric_CorTP_Annual

• metric_CorTempPPT

• metric_DDDat5C0to020cm30bar_quarterly

• metric_DDDat5C0to030cm30bar

• metric_DDDat5C0to100cm30bar

• metric_DDDat5C0to100cm30bar_quarterly

• metric_DR_JJA

• metric_DR_annual

• metric_DR_daily

• metric_DR_monthly

• metric_DSIat0to100cm15bar

• metric_DSIat0to100cm30bar

• metric_DrySoilDays_Seasonal_top50cm

• metric_DrySoilDays_Seasonal_wholeprofile

• metric_ET_annual

• metric_ET_monthly

• metric_Evaporation_Seasonal

• metric_ExtremeShortTermDryStress_Seasonal_top50cm

• metric_ExtremeShortTermDryStress_Seasonal_wholeprofile

• metric_FrostDaysAtNeg5C

• metric_FrostDays_Seasonal

• metric_NonDrySWA_Seasonal_top50cm

• metric_NonDrySWA_Seasonal_wholeprofile

• metric_PET_Seasonal

• metric_PPT_JJA

• metric_PPT_Seasonal

• metric_PPT_daily

• metric_PPT_dailyClim

• metric_PPT_monthlyClim

• metric_RR2022predictors_annual

• metric_RR2022predictors_annualClim

• metric_Radiation_annual

• metric_Radiation_monthly

• metric_RecruitmentIndex_v4

• metric_RecruitmentIndex_v5

• metric_SMTRs

• metric_SW2toTable_daily

• metric_SWA_Seasonal_top50cm

• metric_SWA_Seasonal_wholeprofile

• metric_SWAat0to020cm39bar_JJA

• metric_SWAat0to020cm39bar_daily

• metric_SWAat0to020cm39bar_dailyClim

• metric_SWAat0to020to100cm39bar_quarterly

• metric_SWAat0to100cm30bar

• metric_SWAat0to100cm39bar

• metric_SWAat0to100cm39bar_JJA

• metric_SWAat0to100cm39bar_daily

• metric_SWAat20to040cm39bar_JJA

• metric_SWAat20to040cm39bar_daily

• metric_SWAat20to100cm39bar_JJA

• metric_SWAat20to100cm39bar_daily

• metric_SWAat20to100cm39bar_dailyClim

• metric_SWAat40to060cm39bar_JJA

• metric_SWAat40to060cm39bar_daily

• metric_SWAat60to080cm39bar_JJA

• metric_SWAat60to080cm39bar_daily

• metric_SWAat80to100cm39bar_JJA

• metric_SWAat80to100cm39bar_daily

• metric_SWP_SoilLayers_MeanMonthly

• metric_SWPat0to020cm_dailyClim

• metric_SWPat20to100cm_dailyClim

• metric_SemiDryDuration_Annual_top50cm

• metric_SemiDryDuration_Annual_wholeprofile

• metric_TDDat5C

• metric_TDDat5C_quarterly

• metric_TEPET_daily

• metric_TemperatureMax_Seasonal

• metric_TemperatureMean_Seasonal

• metric_TemperatureMin_Seasonal

• metric_Tmean_JJA

• metric_Tmean_daily

• metric_Tmean_dailyClim

• metric_Tmean_monthly

• metric_Tmean_monthlyClim

• metric_TranspirationPeaks_v6

• metric_TranspirationSeasonality_v1

• metric_TranspirationSeasonality_v2

• metric_TranspirationSeasonality_v3

• metric_TranspirationSeasonality_v4

• metric_TranspirationSeasonality_v5

• metric_TranspirationSeasonality_v6

• metric_Transpiration_Seasonal

• metric_VWC_Seasonal_top50cm

• metric_VWC_Seasonal_wholeprofile

• metric_WDDat5C0to020cm15bar_quarterly

• metric_WDDat5C0to100cm15bar

• metric_WDDat5C0to100cm15bar_quarterly

• metric_WetSoilDays_Seasonal_top50cm

• metric_WetSoilDays_Seasonal_wholeprofile

• metric_land_cover_v1

• metric_land_cover_v2

• metric_veg_biomass_annual_v1

• metric_veg_biomass_annual_v2

• metric_veg_biomass_monthly_v1

• metric_veg_biomass_monthly_v2

DrylandEcology/rSW2metrics documentation built on May 25, 2023, 10:38 a.m.