diff --git a/README.md b/README.md index d1835fa..b838b71 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,7 @@ [![CRAN downloads](https://cranlogs.r-pkg.org/badges/last-month/pam)](https://cran.r-project.org/package=pam) [![CRAN total downloads](https://cranlogs.r-pkg.org/badges/grand-total/pam)](https://cran.r-project.org/package=pam) + ## Introduction Rapid light curves recorded via the pulse‐amplitude modulation (PAM) technique are widely used to characterize photosynthesis, enabling the determination of key photosynthetic parameters. However, deriving these kinetic parameters from raw data requires fitting to regression models, a process traditionally involving laborious and error‐prone manual steps. Our R package pam streamlines this process by automating regression analysis, enabling fast and reproducible processing of large datasets. It provides the models of Vollenweider (1965), Platt et al. (1980), Eilers and Peeters (1988) and Walsby (1997). @@ -34,1071 +35,32 @@ install.packages("remotes") remotes::install_github("biotoolbox/pam", subdir = "src", ref = "dev") ``` -## Usage +## Examples -Examples of usage can be found in the `examples` directory. +Examples of usage can be found in the [examples](examples/) directory: ---- +- [Single CSV](examples/example_single_data.R) → Reads a single CSV, generates regression data using Eilers and Peeters model, modifies the model result, generates control plot and exports the plot as jpg and the result as csv files. +- [Multiple CSV's](examples/example_multiple_data.R) → Reads multiple CSV files, generates regression data using Eilers and Peeters model, modifies the model result, generates control plot and exports the plots as pdf and the result as csv files. +- [Combo control plot](examples/example_combo_plot_control.R) → Generates one control plot containing all models from a single csv file and exports the plot as jpg. +- [Compare models](examples/example_compare_models.R) → Compares all models against each other based on one data set and prints the score. ## Functions -### read_universal_data() - -#### Description - -This function reads a universal CSV file, computes $$ETR$$ values, and returns a processed intermediate table. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ - -#### Details - -ETR values are calculated using the following formula: - -$$ \textit{ETR (I or II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (I or II)} \cdot \textit{Yield (I or II)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV data using `read.csv()`. -- Converting the data into a `data.table`. -- Validating the raw data structure with `validate_raw_intermediate_csv()`. -- Iterating through each row to calculate ETR values for both `yield_1` and `yield_2` using `calc_etr()`. - -#### Return - -Returning a new table containing the original `par`, `yield_1`, `yield_2`, and the calculated `etr_1` and `etr_2` columns. - -#### Example - -```r -data <- read_dual_pam_data("path/to/data.csv", -etr_factor = 0.84, -fraction_photosystem_I = 0.5, -fraction_photosystem_II = 0.5) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) - ---- - -### read_dual_pam_data() - -#### Description - -This function reads the original CSV file as created by the [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) software, processes it by calculating $$ETR$$ values, and returns a cleaned dataset. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ - -#### Details - -ETR values are calculated using the following formula: - -$$ \textit{ETR (I or II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (I or II)} \cdot \textit{Yield (I or II)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV data using `read.csv()` and converting it to a `data.table`. -- Validating the raw Dual-PAM data with `validate_dual_pam_data()`. -- Filtering rows where the column `ID` equals `SP` -- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. -- Calculating initial ETR values from `Pm.-Det.` and `Fm-Det.` rows using `calc_etr()`. -- Iterating through all rows with `Action == "P.+F. SP"` to calculate ETR values for both `Y.I.` and `Y.II.` -- Stopping at the recovery period if `remove_recovery = TRUE`. - - -#### Return - -- Returning a table containing `par`, `yield_1`, `yield_2`, and the calculated `etr_1` and `etr_2` columns. - -#### Example - -```r -data <- read_dual_pam_data("path/to/data.csv", -remove_recovery = TRUE, -etr_factor = 0.84, -fraction_photosystem_I = 0.5, -fraction_photosystem_II = 0.5) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) - ---- - -### read_dual_pam_single_channel_p700_data() - -#### Description - -This function reads the original CSV file as created by the [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) software in single channel mode (P700), processes it by calculating $$ETR$$ values for Photosystem I, and returns a cleaned dataset. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to Photosystem I used in the ETR calculation formula. Default is `0.5`. - Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to Photosystem II. Default is `0.5`. - (Must sum with Photosystem I fraction to 1.) - -#### Details - -ETR values for Photosystem I are calculated using the following formula: - -$$ \textit{ETR (I)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem I} \cdot \textit{Yield (I)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV data using `read.csv()` and converting it to a `data.table`. -- Validating the raw Dual-PAM data with `validate_dual_pam_single_channel_p700_data()`. -- Filtering rows where the column `ID` equals `SP`. -- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. -- Extracting the initial Pm.-Det. measurement at `PAR = 0` to calculate the first ETR value. -- Iterating through all rows with `Action == "P700 SP"` to calculate ETR values for Photosystem I (`Y.I.`). -- Stopping at the recovery period if `remove_recovery = TRUE`. - -#### Return - -- Returning a table containing: - - `par`: Photosynthetically active radiation. - - `yield_1`: Yield of Photosystem I. - - `yield_2`: `NA` (not available in single channel PS I mode). - - `etr_1`: Calculated ETR for Photosystem I. - - `etr_2`: `NA` (not available in single channel PS I mode). - -#### Example - -```r -data <- read_dual_pam_single_channel_p700_data( - "path/to/data.csv", - remove_recovery = TRUE, - etr_factor = 0.84, - fraction_photosystem_I = 0.5, - fraction_photosystem_II = 0.5 -) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) ---- - -### read_dual_pam_single_channel_fluo_data() - -#### Description - -This function reads the original CSV file as created by the [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) software in single channel mode (Fluo), processes it by calculating $$ETR$$ values for Photosystem II, and returns a cleaned dataset. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to Photosystem I. Default is `0.5`. -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to Photosystem II used in the ETR calculation formula. Default is `0.5`. - Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ - -#### Details - -ETR values for Photosystem II are calculated using the following formula: - -$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem II} \cdot \textit{Yield (II)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV data using `read.csv()` and converting it to a `data.table`. -- Validating the raw Dual-PAM data with `validate_dual_pam_single_channel_fluo_data()`. -- Filtering rows where the column `ID` equals `SP`. -- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. -- Extracting the initial **Fm-Det.** measurement at `PAR = 0` to calculate the first ETR value. -- Iterating through all rows with `Action == "Fluo. SP"` to calculate ETR values for Photosystem II (`Y.II.`). -- Stopping at the recovery period if `remove_recovery = TRUE`. - -#### Return - -- Returning a table containing: - - `par`: Photosynthetically active radiation. - - `yield_1`: `NA` (not available in single channel Photosystem II mode). - - `yield_2`: Yield of Photosystem II. - - `etr_1`: `NA` (not available in single channel Photosystem II mode). - - `etr_2`: Calculated ETR for Photosystem II. - -#### Example - -```r -data <- read_dual_pam_single_channel_fluo_data( - "path/to/data.csv", - remove_recovery = TRUE, - etr_factor = 0.84, - fraction_photosystem_I = 0.5, - fraction_photosystem_II = 0.5 -) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) ---- - -### read_junior_pam_data() - -#### Description - -This function reads the original CSV file from [JUNIOR-PAM](https://www.walz.com/products/junior-pam/) as created by the WinControl software, processes it by calculating $$ETR$$ values, and returns a cleaned dataset. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. -Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ - -#### Details - -ETR values are calculated using the following formula: - -$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (II)} \cdot \textit{Yield (II)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV data using `read.csv()` and converting it to a `data.table`. -- Validating the raw Junior-PAM data with `validate_junior_pam_data()`. -- Renaming columns to standard names (`PAR`, `Y.II`.) if necessary. -- Filtering rows where Type equals `"FO"` or `"F"`. -- Ordering by `Time (rel/ms)` column. -- Iterating through all rows to calculate ETR values for `Y.II.` using `calc_etr()`. -- Stopping at the recovery period if `remove_recovery = TRUE`. - -To ensure the file is imported correctly, please export the CSV file using the default settings: -![Plot](img/export_junior_pam.png) - -#### Return - -Returning a table containing `par`, `yield_1` (NA), `yield_2`, `etr_1` (NA), and `etr_2`. - -#### Example - -```r -data <- read_junior_pam_data("path/to/data.csv", -remove_recovery = TRUE, -etr_factor = 0.84, -fraction_photosystem_I = 0.5, -fraction_photosystem_II = 0.5) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) - ---- - -### read_pam_2500_data() - -#### Description - -This function reads the original CSV file generated by the [PAM-2500](https://www.walz.com/products/pam-2500/) software, processes it by calculating $$ETR$$ values for Photosystem II, and returns a cleaned dataset. - -#### Parameters - -- **csv_path**: A string representing the file path to the CSV file. -- **remove_recovery**: Logical value indicating whether recovery measurements after the actual Pi curve should be removed. Default is `TRUE`. -- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. -- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I. Default is `0.5`. - Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ -- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II. Default is `0.5`. - Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ - - -#### Details - -ETR values are calculated using the following formula: - -$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem II} \cdot \textit{Yield (II)} $$ - -The function processes the provided CSV file by: - -- Reading the CSV file using `read.csv()` with `;` as separator and converting it to a `data.table`. -- Validating the dataset using `validate_pam_2500_data()`. -- Filtering rows where the column `No.` contains numeric entries only. -- Combining the `Date` and `Time` columns into a `DateTime` column and sorting the dataset chronologically. -- Iterating through all rows to: - - Extract `PAR` and `Y.II.` values. - - Calculate ETR for Photosystem II using `calc_etr()`. -- Optionally stopping at the recovery phase if `remove_recovery = TRUE`, defined as a decrease in PAR values. -- Constructing a result table with calculated values. - - -#### Return - -- A `data.table` containing the following columns: - - - `par`: Photosynthetically active radiation - - `yield_1`: Placeholder column (`NA`) - - `yield_2`: Effective quantum yield of Photosystem II - - `etr_1`: Placeholder column (`NA`) - - `etr_2`: Calculated electron transport rate for Photosystem II - - -#### Example - -```r -data <- read_pam_2500_data( - "path/to/data.csv", - remove_recovery = TRUE, - etr_factor = 0.84, - fraction_photosystem_I = 0.5, - fraction_photosystem_II = 0.5 -) -``` - -#### References - -- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) - ---- - -### vollenweider_generate_regression_ETR_I() and vollenweider_generate_regression_ETR_II() - -This function generates a regression model based on Vollenweider (1965). Original naming conventions from the publication are used. - -#### Parameters - -- **data**: A `data.table` containing the input data, processed according to the corresponding read function (e.g. `read_dual_pam_data`). -- **etr_type**: A character string specifying the column name of the response variable (ETR I or ETR II) to be used in the model. -- **pmax_start_value**: Numeric. The starting value for the parameter $$p_{max}$$ in the model. Defaults to `pmax_start_values_vollenweider_default`. -- **a_start_value**: Numeric. The starting value for the parameter $$a$$ in the model. Defaults to `a_start_values_vollenweider_default`. -- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_values_vollenweider_default`. -- **n_start_value**: Numeric. The starting value for the parameter $$n$$ in the model. Defaults to `n_start_values_vollenweider_default`. - -#### Return - -A list containing the following elements: - -- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **residual_sum_of_squares**: The deviation between the actual and predicted ETR values. -- **pmax**: The maximum electron transport rate without photoinhibition ($$p_{max}$$). -- **a**: The obtained parameter $$a$$. -- **alpha**: The obtained parameter $$\alpha$$. -- **n**: The obtained parameter $$n$$. -- **popt**: The maximum electron transport rate with photoinhibition ($$p_{opt}$$). A function computes predicted photosynthetic rates for each PAR value and tracks the maximum rate observed and is therefore modified from the original approach: - -```r - popt <- 0 - pars <- c() - predictions <- c() - for (p in min(data$PAR):max(data$PAR)) { - pars <- c(pars, p) - prediction <- pmax * (((a * p) / (sqrt(1 + (a * p)^2))) * (1 / (sqrt(1 + (alpha * p)^2)^n))) - predictions <- c( - predictions, - prediction - ) - - if (prediction > popt) { - popt <- prediction - } - } -``` - -- **ik**: PAR where the transition point from light limitation to light saturation is achieved without photoinhibition ($$I_k$$). Calculated as: - -$$I_k = \\frac{1}{a}$$ - -- **iik**: PAR where the transition point from light limitation to light saturation is achieved with photoinhibition ($$I_k^\prime$$). Calculated as: - -$$I_k^\prime = \frac{I_k \cdot p_{opt}}{p_{max}}$$ - -- **pmax_popt_and_ik_iik_ratio**: Ratio of $$p_{max}$$ to $$p_{opt}$$ and $$I_k$$ to $$I_k^\prime$$ ($$p_{max} / p_{opt}$$). Calculated as: - -$$\\p_max\\_popt\\_and\\_ik\\_iik\\_ratio = \frac{I_k}{I_k^\prime}$$ - -#### Details - -This function uses non-linear least squares fitting to estimate the parameters for the Vollenweider model, which describes the relationship between PAR and ETR. The model used is: - -$$p = p_{max} \cdot \frac{a \cdot i}{\sqrt{1 + (a \cdot i)^2}} \cdot \frac{1}{\left(\sqrt{1 + (\alpha \cdot i)^2}\right)^n}$$ - -It is valid: $$i = PAR; p = ETR$$ - -#### Example - -```r -result_vollenweider_ETR_II <- vollenweider_generate_regression_ETR_II(data, - pmax_start_value = 40, - a_start_value = 0.1, - alpha_start_value = -0.0001, - n_start_value = 350) -``` - -#### References - -Vollenweider, R. A. (1965). *Calculation models of photosynthesis-depth curves and some implications regarding day rate estimates in primary production measurements*, p. 427-457. In C. R. Goldman [ed.], *Primary Productivity in Aquatic Environments*. Mem. Ist. Ital. Idrobiol., 18 Suppl., University of California Press, Berkeley. - ---- - -### platt_generate_regression_ETR_I() and platt_generate_regression_ETR_II() - -This function generates a regression model based on Platt (1980). Original naming conventions from the publication are used. - -#### Parameters - -- **data**: A `data.table` containing the input data from `read_dual_pam_data`. -- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_value_platt_default`. -- **beta_start_value**: Numeric. The starting value for the parameter $$\beta$$ in the model. Defaults to `beta_start_value_platt_default`. -- **ps_start_value**: Numeric. The starting value for the parameter $$p_s$$ in the model. Defaults to `ps_start_value_platt_default`. - -#### Return - -A list containing the following elements: - -- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **ps**: The maximum electron transport rate without photoinhibition ($$P_s$$). -- **alpha**: The initial slope of the light curve ($$\alpha$$). -- **beta**: The photoinhibition of the light curve ($$\beta$$). -- **pm**: The maximum electron transport rate with photoinhibition ($$P_m$$). Calculated as: - -$$P_m = P_s \cdot \left(\frac{\alpha}{\alpha + \beta}\right) \cdot \left(\left(\frac{\beta}{\alpha + \beta}\right)^{\frac{\beta}{\alpha}}\right)$$ - -- **ik**: PAR where the transition point from light limitation to light saturation is achieved with photoinhibition ($$I_k$$). Calculated as: - -$$I_k = \frac{P_m}{\alpha}$$ - -- **is**: PAR where the transition point from light limitation to light saturation is achieved without photoinhibition ($$I_s$$). Calculated as: - -$$I_s = \frac{P_s}{\alpha}$$ - -- **im**: The PAR at which the maximum electron transport rate is achieved with photoinhibition ($$I_m$$). Calculated as: - -$$I_m = \left(\frac{P_s}{\alpha}\right) \cdot \log\left(\frac{\alpha + \beta}{\beta}\right)$$ - -- **ib**: ($$I_b$$) Calculated as: - -$$I_b = \frac{P_s}{\beta}$$ - -#### Details - -This function uses non-linear least squares fitting to estimate the parameters for the Platt model, which describes the relationship between PAR and ETR. The model used is: - -$$P = P_s \cdot \left(1 - e^\frac{{-\alpha \cdot I}}{P_s}\right) \cdot e^\left(\frac{{-\beta \cdot I}}{P_s}\right)$$ - -It is valid: $$I = PAR; p = ETR$$ - -#### Example - -```r -result_platt_ETR_II <- platt_generate_regression_ETR_II(data, - alpha_start_value = 0.3, - beta_start_value = 0.01, - ps_start_value = 30) -``` - -#### References - -Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). *Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton*. Journal of Marine Research, 38(4). Retrieved from . - ---- - -### eilers_peeters_generate_regression_ETR_I() and eilers_peeters_generate_regression_ETR_II() - -This function generates a regression model based on Eilers-Peeters (1988). Original naming conventions from the publication are used. All parameters are calculated taking photoinhibition into account. - -#### Parameters - -- **data**: A `data.table` containing the input data from `read_dual_pam_data`. -- **a_start_value**: Numeric. The starting value for the parameter $$a$$ in the model. Defaults to `a_start_values_eilers_peeters_default`. -- **b_start_value**: Numeric. The starting value for the parameter $$b$$ in the model. Defaults to `b_start_values_eilers_peeters_default`. -- **c_start_value**: Numeric. The starting value for the parameter $$c$$ in the model. Defaults to `c_start_values_eilers_peeters_default`. - -#### Return - -A list containing the following elements: - -- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **a**: The obtained parameter $$a$$. -- **b**: The obtained parameter $$b$$. -- **c**: The obtained parameter $$c$$. -- **pm**: The maximum electron transport rate ($$p_m$$). Calculated as: - -$$p_m = \frac{1}{b + 2 \sqrt{a \cdot c}}$$ - -- **s**: The initial slope of the light curve ($$s$$). Calculated as: - -$$s = \frac{1}{c}$$ - -- **ik**: PAR where the transition point from light limitation to light saturation is achieved ($$I_k$$). Calculated as: - -$$I_k = \frac{c}{b + 2 \sqrt{a \cdot c}}$$ - -- **im**: The PAR at which the maximum electron transport rate is achieved ($$I_m$$). Calculated as: - -$$I_m = \sqrt{\frac{c}{a}}$$ - -- **w**: The sharpness of the peak ($$w$$). Calculated as: - -$$w = \frac{b}{\sqrt{a \cdot c}}$$ - -#### Details - -This function uses non-linear least squares fitting to estimate the parameters for the Eilers-Peeters model, which describes the relationship between PAR and ETR. The model used is: - -$$ p = \frac{I}{a \cdot I^2 + b \cdot I + c} $$ - -It is valid: $$I = PAR$$; $$p = ETR$$ - -#### Example - -```r -result_eilers_peeters_ETR_II <- eilers_peeters_generate_regression_ETR_II(data, -a_start_value = 0.00004, -b_start_value = 0.004, -c_start_value = 5) -``` - -#### References - -Eilers, P. H. C., & Peeters, J. C. H. (1988). *A model for the relationship between light intensity and the rate of photosynthesis in phytoplankton.* Ecological Modelling, 42(3-4), 199-215. [doi:10.1016/0304-3800(88)90057-9](https://doi.org/10.1016/0304-3800(88)90057-9). - ---- - -### walsby_generate_regression_ETR_I() and walsby_generate_regression_ETR_II() - -This function generates a regression model based on Walsby (1997) in a modified version without the respiration term. Naming conventions from Romoth (2019) are used. ETRmax is calculated without taking photoinhibition into account. - -#### Parameters - -- **data**: A `data.table` containing the input data from `read_dual_pam_data`. -- **etr_max_start_value**: Numeric. The starting value for the parameter $$ETR_{max}$$ in the model. Defaults to `etr_max_start_value_walsby_default`. -- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_value_walsby_default`. -- **beta_start_value**: Numeric. The starting value for the parameter $$\beta$$ in the model. Defaults to `beta_start_value_walsby_default`. - -#### Return - -A list containing the following elements: - -- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **etr_max**: The maximum electron transport rate without photoinhibition ($$ETR_{max}$$). -- **alpha**: The initial slope of the light curve ($$\alpha$$). -- **beta**: The photoinhibition of the light curve ($$\beta$$). - -#### Details - -This function uses non-linear least squares fitting to estimate the parameters for the Walsby model, which describes the relationship between PAR and ETR I. The model used is: - -$$ETR = ETR_{max} \cdot \left(1 - e^{\left(-\frac{\alpha \cdot I}{ETR_{max}}\right)}\right) + \beta \cdot I$$ - -It is valid: $$I = PAR$$ - -#### References - -Walsby, A. E. (1997). Numerical integration of phytoplankton photosynthesis through time and depth in a water column. *New Phytologist*, 136(2), 189-209. - -Romoth, K., Nowak, P., Kempke, D., Dietrich, A., Porsche, C., & Schubert, H. (2019). Acclimation limits of *Fucus evanescens* along the salinity gradient of the southwestern Baltic Sea. *Botanica Marina*, 62(1), 1-12. - ---- - -### vollenweider_modified() - -This function adds parameters that were not originally included in the Vollenweider (1965) model, but were introduced by other models and renames the parameters to a standardised one for all models. See the table below. - -#### Parameters - -- **model_result**: A list containing the results of the model, including parameters such as `pmax`, `alpha`, and `ik`. - -#### Return - -Returns a modified model result as a list with the following elements: - -- **etr_type**: ETR Type based on the model result. -- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` -- **b**: obtained paramter `b`, transfered as `a` -- **c**: obtained paramter `c`, here transfered as `alpha` -- **d**: obtained paramter `c`, here transfered as `n` -- **alpha**: The initial slope of the light curve, calculated as: - -$${alpha} = \frac{{etrmax\\_with\\_photoinhibition}}{{ik\\_with\\_photoinhibition}}$$ - -- **beta**: Not available, here set to `NA_real_` -- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `popt` -- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `pmax` -- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as: `iik` -- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, transfered as: `ik` -- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account. Although $I_m$ was mentioned in the original publication, no general solution was presented. Therefore, we decided to include it only in the modified version. Determined as: - -```r - etr_regression_data <- get_etr_regression_data_from_model_result(model_result) - im_with_photoinhibition <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ][[PAR_name]] -``` - -- **w**: Not available, here set to `NA_real_` -- **ib**: Not available, here set to `NA_real_` -- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`, transfered as: `pmax_popt_and_ik_iik_ratio` - -#### Details - -This function validates the `model_result` input and processes relevant parameters for the Vollenweider model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different models. - -#### Examples - -```r -modified_result_vollenweider <- vollenweider_modified(model_result_vollenweider) -``` ---- - -### platt_modified() - -This function adds parameters that were not originally included in the Platt (1980) model, but were introduced by other models and renames the parameters to a standardised one for all models. See the table below. - -#### Parameters - -- **model_result**: A list containing the results of the model, including parameters such as `etr_max`, `alpha`, and `beta`. - -#### Return - -Returns a modified model result as a list with the following elements: - -- **etr_type**: ETR Type based on the model result. -- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` -- **b**: obtained paramter `b`, here equal to `alpha` -- **c**: obtained paramter `c`, here equal to `beta` -- **d**: not available, here set to `NA_real_` -- **alpha**: The initial slope of the light curve, transfered unchanged as `alpha` -- **beta**: The photoinhibition of the light curve, transfered unchanged as `beta` -- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `pm` -- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `ps` -- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as: `ik` -- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, transfered as: `is` -- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, transfered as: `im` -- **w**: Not available, here set to `NA_real_` -- **ib**: Transfered unchange as: `ib` -- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`. Calculated as: - -$${{etrmax\\_without\\_with\\_ratio}} = \frac{{etrmax\\_without\\_photoinhibition}}{{etrmax\\_with\\_photoinhibition}}$$ - -#### Details - -This function validates the `model_result` input and processes relevant parameters for the Platt model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different models. - -#### Examples - -```r -modified_result_platt <- platt_modified(model_result_platt) -``` - ---- - -### eilers_peeters_modified() - -This function adds parameters that were not originally included in the Eilers and Peeters (1988) model, but were introduced by other models and renames the parameters to a standardised one for all models. See the table below. - -#### Parameters - -- **model_result**: A list containing the results of the model, including parameters such as `a`, `b`, `c`, `s`, `pm`, `ik`, `im`, and `w`. - -#### Return - -Returns a modified model result as a list with the following elements: - -- **etr_type**: ETR Type based on the model result. -- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **a**: The obtained parameter $$a$$ -- **b**: The obtained parameter $$b$$ -- **c**: The obtained parameter $$c$$ -- **d**: Not available, here set to `NA_real_` -- **alpha**: The initial slope of the light curve, transfered unchanged as `s` -- **beta**: Not available, here set to `NA_real_` -- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `pm` -- **etrmax_without_photoinhibition**: Not available, here set to `NA_real_` -- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as `ik` -- **ik_without_photoinhibition**: Not available, here set to `NA_real_` -- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, transfered as`im` -- **w**: The sharpness of the peak, transfered as `w` -- **ib**: Not available, here set to `NA_real_` -- **etrmax_without_with_ratio**: Not available, here set to `NA_real_` - -#### Details - -This function validates the `model_result` input, extracts relevant parameters for the modified Eilers-Peeters model, and creates a structured list using `create_modified_model_result`. The list serves as a standardized output format for further analysis. - -#### Examples - -```r -# Example usage for eilers_peeters_modified -modified_result <- eilers_peeters_modified(model_result_eilers_peeters) -``` ---- - -### walsby_modified() - -This function adds parameters that were not originally included in the Walsby (1997) model, but were introduced by other models and renames the parameters to a standardised one for all models. See the table below. - -#### Parameters - -- **model_result**: A list containing the results of the model, including parameters such as `etr_max`, `alpha`, and `beta`. - -#### Return - -Returns a modified model result as a list with the following elements: - -- **etr_type**: ETR Type based on the model result. -- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. -- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. -- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. -- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. -- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` -- **b**: obtained paramter `b`, here equal to `alpha` -- **c**: obtained paramter `c`, here equal to `beta` -- **d**: not available, here set to `NA_real_` -- **alpha**: The initial slope of the light curve, transfered unchanged as `alpha` -- **beta**: The photoinhibition of the light curve, transfered unchanged as `beta` -- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, determined as: - -```r - etr_regression_data <- get_etr_regression_data_from_model_result(model_result) - etr_max_row <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ] - etrmax_with_photoinhibition <- etr_max_row[[prediction_name]] -``` - -- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `etr_max` -- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, calculated as: - -$$ik\\_with\\_photoinhibition = \frac{etrmax\\_with\\_photoinhibition}{alpha}$$ - -- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, calculated as: - -$$ik\\_without\\_photoinhibition = \frac{etrmax\\_without\\_photoinhibition}{alpha}$$ - -- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, calculated as: - -```r - etr_regression_data <- get_etr_regression_data_from_model_result(model_result) - etr_max_row <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ] - im_with_photoinhibition <- etr_max_row[[PAR_name]] -``` - -- **w**: Not available, here set to `NA_real_` -- **ib**: Not available, here set to `NA_real_` -- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`. Calculated as: - -$${{etrmax\\_without\\_with\\_ratio}} = \frac{{etrmax\\_without\\_photoinhibition}}{{etrmax\\_with\\_photoinhibition}}$$ - -#### Details - -This function validates the `model_result` input and processes relevant parameters for the Walsby model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different photosynthesis models. - -#### Examples - -```r -modified_result <- walsby_modified(model_result_walsby) -``` ---- - -### Naming overview - -#### Publication-accurate naming and the respective modified naming - -modified |Eilers and Peeters |Platt |Walsby |Vollenweider | -|-|-|-|-|-| -|residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares | -|root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error | -|relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error | -|a |a |ps |etr_max |pmax | -|b |b |alpha |alpha |a | -|c |c |beta |beta |alpha | -|d |NA |NA |NA |n | -|alpha |s |alpha |alpha |NA | -|beta |NA |beta |beta |NA | -|etrmax_with_photoinhibition |pm |pm |NA |popt | -|etrmax_without_photoinhibition |NA |ps |etr_max |pmax | -|ik_with_photoinhibition |ik |ik |NA |iik | -|ik_without_photoinhibition |NA |is |NA |ik | -|im_with_photoinhibition |im |im |NA |NA | -|w |w |NA |NA |NA | -|ib |NA |ib |NA |NA | -|etrmax_without_with_ratio |NA |NA |NA |pmax_popt_and_ik_iik_ratio | - ---- - -#### Publication-accurate naming and the respective modified naming with additional calculations not included in the original publication - -|modified |Eilers and Peeters |Platt |Walsby |Vollenweider | -|-|-|-|-|-| -|residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares | -|root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error | -|relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error | -|a |a |ps |etr_max |pmax | -|b |b |alpha |alpha |a | -|c |c |beta |beta |alpha | -|d |NA |NA |NA |n | -|alpha |s |alpha |alpha |real_alpha | -|beta |NA |beta |beta |NA | -|etrmax_with_photoinhibition |pm |pm |etrmax_with_photoinhibition |popt | -|etrmax_without_photoinhibition |NA |ps |etr_max |pmax | -|ik_with_photoinhibition |ik |ik |ik_with_photoinhibition |iik | -|ik_without_photoinhibition |NA |is |ik_without_photoinhibition |ik | -|im_with_photoinhibition |im |im |im_with_photoinhibition |im_with_photoinhibition | -|w |w |NA |NA |NA | -|ib |NA |ib |NA |NA | -|etrmax_without_with_ratio |NA |etrmax_without_with_ratio |etrmax_without_with_ratio |pmax_popt_and_ik_iik_ratio | - ---- - -### compare_regression_models_ETR_I() and compare_regression_models_ETR_II() - -This function compares different regression models. - -#### Parameters - -- **data_dir**: A character string specifying the directory where the input data files are located. -- **read_func**: Function used to read the CSV files (e.g., `read_dual_pam_data`) - -#### Return - -A vector containing the total points assigned to each regression model based on their performance. Models are ranked based on the calculated deviation of the difference between observed and predicted values. Rating: - -- 1st: 3 points -- 2nd: 2 points -- 3rd: 1 point -- 4th: 0 points - -#### Details - -This function allows a straightforward comparison of the models: Eilers-Peeters (1988), Platt (1980), Vollenweider (1965), and Walsby (1997). The results can guide users in selecting the most appropriate model for their data. If regression is not possible for a model, no points are awarded for the file for any of the models. Start values cannot be adjusted in this function. - -#### Example - -```r -#raw data file directory -data_dir_compare <- file.path(getwd(), "data") - -#compare regression models -compare_regression_models_ETR_II <- compare_regression_models_ETR_II(data_dir_compare, read_dual_pam_data) -print(compare_regression_models_ETR_II) -``` - -#### References - -Eilers, P. H. C., & Peeters, J. C. H. (1988). *A model for the relationship between light intensity and the rate of photosynthesis in phytoplankton.* Ecological Modelling, 42(3-4), 199-215. [doi:10.1016/0304-3800(88)90057-9](https://doi.org/10.1016/0304-3800(88)90057-9). - -Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). *Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton*. Journal of Marine Research, 38(4). Retrieved from . - -Romoth, K., Nowak, P., Kempke, D., Dietrich, A., Porsche, C., & Schubert, H. (2019). Acclimation limits of *Fucus evanescens* along the salinity gradient of the southwestern Baltic Sea. *Botanica Marina*, 62(1), 1-12. - -Vollenweider, R. A. (1965). *Calculation models of photosynthesis-depth curves and some implications regarding day rate estimates in primary production measurements*, p. 427-457. In C. R. Goldman [ed.], *Primary Productivity in Aquatic Environments*. Mem. Ist. Ital. Idrobiol., 18 Suppl., University of California Press, Berkeley. - -Walsby, A. E. (1997). Numerical integration of phytoplankton photosynthesis through time and depth in a water column. *New Phytologist*, 136(2), 189-209. - ---- - -### plot_control() - -This function creates a control plot for the used model based on the provided data and model results. - -#### Parameters - -- **data**: A `data.table` containing the original ETR and yield data for the plot. -- **model_result**: A list containing the fitting results of the used model and the calculated parameters (alpha, ik, etc.). -- **title**: A character string that specifies the title of the plot. -- **color**: A color specification for the regression line in the plot. - -#### Return - -A plot displaying the original ETR and Yield values and the regression data. A table below the plot shows the calculated data (alpha, ik, etc.). - -#### Example - -```r -plot_control_eilers_peeters_ETR_II <- plot_control( - data = pam_data, - model_result = modified_model_result_eilers_peeters_ETR_II, - title = "eilers_peeters ETR II modified 20240925.csv", - color = "purple" -) -print(plot_control_eilers_peeters_ETR_II) -``` - -![Plot](img/test-eilers_peeters_etr_II_modified_control_plot_20240925.jpg) - ---- - -### combo_plot_control() - -The `combo_plot_control()` function generates a combined plot of electron transport rate (ETR) data and regression model predictions, along with a customized table summarizing the parameters for each model. - -#### Parameters - -- **title**: A character string specifying the title for the plot. -- **data**: A data frame containing the raw input data for ETR and Photosynthetically Active Radiation (PAR). -- **model_results**: A list of model results, where each model result is a list containing regression data and parameters for ETR. -- **name_list**: A list of names corresponding to each model result. These names will be used in the legend and table. -- **color_list**: A list of color values for each model result. Colors are used to differentiate lines on the plot. - -#### Return - -A plot displaying the original ETR and Yield values and the regression data from different models. A table below the plot shows the calculated data (alpha, ik, etc.). - -#### Examples - -```r -test_data_file <- file.path(getwd(), "data", "dual_pam_data", "20240925.csv") - data <- read_dual_pam_data(test_data_file) - - eilers_peeters <- eilers_peeters_modified(eilers_peeters_generate_regression_ETR_II(data)) - platt <- platt_modified(platt_generate_regression_ETR_II(data)) - walsby <- walsby_modified(walsby_generate_regression_ETR_II(data)) - vollenweider <- vollenweider_modified(vollenweider_generate_regression_ETR_II(data)) - - plot <- combo_plot_control( - "etr II test-combo_plot_control_20240925.csv", - data, - list(eilers_peeters, platt, walsby, vollenweider), - list("eilers_peeters", "platt", "walsby", "vollenweider"), - list("purple", "blue", "green", "red") - ) -``` - -![combo Plot](img/test_combo_plot_control_etr_II.jpg) - ---- - -### write_model_result_csv() - -This function exports the raw input data, regression data, and model parameters into separate CSV files for easy access and further analysis. - -#### Parameters - -- **dest_dir**: A character string specifying the directory where the CSV files will be saved. -- **name**: A character string specifying the base name for the output files. -- **data**: A data frame containing the raw input data used in the model. -- **model_result**: A list containing the model results, including parameter values and regression data. - -#### Details - -This function creates three CSV files: - -1. **`name_raw_data.csv`**: Contains the original raw data used in the model. -2. **`name_regression_data.csv`**: Contains the regression data with predictions for electron transport rate (ETR). -3. **`name_model_result.csv`**: Contains the parameter values from the model results (excluding regression data), including parameters like `alpha`, `beta`, and `etr_max`. - -Each file will be named using the `name` parameter as a prefix, followed by a specific suffix for clarity. - -#### Examples - -```r -write_model_result_csv( - dest_dir = "output", - name = "eilers_peeters_experiment_001", - data = raw_data, - model_result = model_result_eilers_peeters -) -``` ---- -## Test coverage - -```r -cov <- covr::package_coverage() -covr::percent_coverage(cov) -``` -90.05935 % - ---- - -## known issues - -#### subscript out of bounds - -``` -Skipped file: 20231214_14_W6_T5_ML.csv because of error: Error in eilers_peeters[["residual_sum_of_squares"]]: subscript out of bounds -``` - -This could indicate that Pm lable in the Action column is at the wrong position in the csv raw data file. Error could be caused by WALZ-Software. - -#### Removed rows in combo_plot_control - -``` -Warnings: -1: Removed 1 row containing missing values or values outside the scale range (`geom_point()`). -2: Removed 1 row containing missing values or values outside the scale range (`geom_point()`). -3: Removed 1 row containing missing values or values outside the scale range (`geom_line()`). -``` - -All points and lines present. Reason for warning messages unknown. Possibly a problem in the library ggplot2. - -### test all - -```r -library(devtools); -devtools::test(); -``` - -### test specific file - -```R -library(devtools); -devtools::load_all(); -library(testthat); -test_file('$$path')" -``` - -## Linux dependencies for devtools - -Ubuntu: -libxml2-dev libssl-dev libcurl4-openssl-dev libfontconfig1-dev libharfbuzz-dev libfribidi-dev libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev +For detailed information about these functions, visit the respective documentation: -Debian: -libxml2-dev libssl-dev libcurl4-openssl-dev libfontconfig1-dev libharfbuzz-dev libfribidi-dev libfreetype6-dev libpng-dev libjpeg-dev libfreetype6-dev libpng-dev libtiff5-dev libjpeg-dev +- [Read CSV Data](docs/functions/read_data.md) → Reads the raw data CSV files and returns the intermediate table. +- [Generate Regressions](docs/functions/generate_regressions.md) → Generates ETR regression data from the chosen model. +- [Modify Model Results](docs/functions/modify_model_results.md) → Modifies parameter naming to a standard approach and adds parameters from other models. +- [Plot Control](docs/functions/plot_control.md) → Generates control plots for visual fit validation. +- [Write Model Results](docs/functions/write_model_results.md) → Exports the regression results as CSV files. +- [Compare Regression Models](docs/functions/compare_regression_models.md) → Scores models against each other for one data set. -R Packages: -install.packages("data.table") -install.packages("dplyr") -install.packages("ggplot2") -install.packages("minpack.lm") -install.packages("SciViews") -install.packages("ggthemes") -install.packages("gridExtra") -install.packages("cowplot") +

+ Processing pipeline overview +

-packages <- readLines("packages.txt") -install.packages(packages) +## Help +- The current version and patch notes can be found under [Releases](https://github.com/biotoolbox/pam/releases). +- Bug reports can be posted under [Issues](https://github.com/biotoolbox/pam/issues). +- Deeper insights can be found under [developer documentation](docs/dev.md). +- A good source for general help can be the [rstats Reddit Community](https://www.reddit.com/r/rstats/). \ No newline at end of file diff --git a/docs/dev.md b/docs/dev.md new file mode 100644 index 0000000..d344cf4 --- /dev/null +++ b/docs/dev.md @@ -0,0 +1,22 @@ +# Developer documentation + +## Branches +- The [main](https://github.com/biotoolbox/pam/tree/main) branch is always up to date with the version published on [cran](https://cran.r-project.org/web/packages/pam/index.html). +- The [dev](https://github.com/biotoolbox/pam/tree/dev) branch is stable but under active development and will eventually merged into the [main](https://github.com/biotoolbox/pam/tree/main) branch. + +## Makefile +- In the [Makefile](../Makefile) are some shortcuts for commonly used commands (install, test, build). + +## Required R packages +- To install all required R package dependencies for development you can use those commands: +``` +packages <- readLines("packages.txt") +install.packages(packages) +``` + +## Custom helper functions +If additionally helper functions are needed (e.g. removing certain data points), it is possible to intercept the intermediate_table between the read and the generate_regression function. + +

+ Processing pipeline overview +

\ No newline at end of file diff --git a/docs/functions/compare_regression_models.md b/docs/functions/compare_regression_models.md new file mode 100644 index 0000000..4a8043d --- /dev/null +++ b/docs/functions/compare_regression_models.md @@ -0,0 +1,46 @@ +# compare regression models + +This function compares different regression models. + +## compare_regression_models_ETR_I() and compare_regression_models_ETR_II() + +### Parameters + +- **data_dir**: A character string specifying the directory where the input data files are located. +- **read_func**: Function used to read the CSV files (e.g., `read_dual_pam_data`) + +### Return + +A vector containing the total points assigned to each regression model based on their performance. Models are ranked based on the calculated deviation of the difference between observed and predicted values. Rating: + +- 1st: 3 points +- 2nd: 2 points +- 3rd: 1 point +- 4th: 0 points + +### Details + +This function allows a straightforward comparison of the models: Eilers-Peeters (1988), Platt (1980), Vollenweider (1965), and Walsby (1997). The results can guide users in selecting the most appropriate model for their data. If regression is not possible for a model, no points are awarded for the file for any of the models. Start values cannot be adjusted in this function. + +### Example + +```r +#raw data file directory +data_dir_compare <- file.path(getwd(), "data") + +#compare regression models +compare_regression_models_ETR_II <- compare_regression_models_ETR_II(data_dir_compare, read_dual_pam_data) +print(compare_regression_models_ETR_II) +``` + +### References + +Eilers, P. H. C., & Peeters, J. C. H. (1988). *A model for the relationship between light intensity and the rate of photosynthesis in phytoplankton.* Ecological Modelling, 42(3-4), 199-215. [doi:10.1016/0304-3800(88)90057-9](https://doi.org/10.1016/0304-3800(88)90057-9). + +Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). *Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton*. Journal of Marine Research, 38(4). Retrieved from . + +Romoth, K., Nowak, P., Kempke, D., Dietrich, A., Porsche, C., & Schubert, H. (2019). Acclimation limits of *Fucus evanescens* along the salinity gradient of the southwestern Baltic Sea. *Botanica Marina*, 62(1), 1-12. + +Vollenweider, R. A. (1965). *Calculation models of photosynthesis-depth curves and some implications regarding day rate estimates in primary production measurements*, p. 427-457. In C. R. Goldman [ed.], *Primary Productivity in Aquatic Environments*. Mem. Ist. Ital. Idrobiol., 18 Suppl., University of California Press, Berkeley. + +Walsby, A. E. (1997). Numerical integration of phytoplankton photosynthesis through time and depth in a water column. *New Phytologist*, 136(2), 189-209. diff --git a/docs/functions/generate_regressions.md b/docs/functions/generate_regressions.md new file mode 100644 index 0000000..4d622f0 --- /dev/null +++ b/docs/functions/generate_regressions.md @@ -0,0 +1,251 @@ +# Generate regression model data + +Those functions will generate regression data with the chosen model and ETR type (e.g. platt_generate_regression_ETR_II). +Original naming conventions from the publication are used. + + +## vollenweider_generate_regression_ETR_I() and vollenweider_generate_regression_ETR_II() + +### Parameters + +- **data**: A `data.table` containing the input data, processed according to the corresponding read function (e.g. `read_dual_pam_data`). +- **etr_type**: A character string specifying the column name of the response variable (ETR I or ETR II) to be used in the model. +- **pmax_start_value**: Numeric. The starting value for the parameter $$p_{max}$$ in the model. Defaults to `pmax_start_values_vollenweider_default`. +- **a_start_value**: Numeric. The starting value for the parameter $$a$$ in the model. Defaults to `a_start_values_vollenweider_default`. +- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_values_vollenweider_default`. +- **n_start_value**: Numeric. The starting value for the parameter $$n$$ in the model. Defaults to `n_start_values_vollenweider_default`. + +### Return + +A list containing the following elements: + +- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **residual_sum_of_squares**: The deviation between the actual and predicted ETR values. +- **pmax**: The maximum electron transport rate without photoinhibition ($$p_{max}$$). +- **a**: The obtained parameter $$a$$. +- **alpha**: The obtained parameter $$\alpha$$. +- **n**: The obtained parameter $$n$$. +- **popt**: The maximum electron transport rate with photoinhibition ($$p_{opt}$$). A function computes predicted photosynthetic rates for each PAR value and tracks the maximum rate observed and is therefore modified from the original approach: + +```r + popt <- 0 + pars <- c() + predictions <- c() + for (p in min(data$PAR):max(data$PAR)) { + pars <- c(pars, p) + prediction <- pmax * (((a * p) / (sqrt(1 + (a * p)^2))) * (1 / (sqrt(1 + (alpha * p)^2)^n))) + predictions <- c( + predictions, + prediction + ) + + if (prediction > popt) { + popt <- prediction + } + } +``` + +- **ik**: PAR where the transition point from light limitation to light saturation is achieved without photoinhibition ($$I_k$$). Calculated as: + +$$I_k = \\frac{1}{a}$$ + +- **iik**: PAR where the transition point from light limitation to light saturation is achieved with photoinhibition ($$I_k^\prime$$). Calculated as: + +$$I_k^\prime = \frac{I_k \cdot p_{opt}}{p_{max}}$$ + +- **pmax_popt_and_ik_iik_ratio**: Ratio of $$p_{max}$$ to $$p_{opt}$$ and $$I_k$$ to $$I_k^\prime$$ ($$p_{max} / p_{opt}$$). Calculated as: + +$$\\p_max\\_popt\\_and\\_ik\\_iik\\_ratio = \frac{I_k}{I_k^\prime}$$ + +### Details + +This function uses non-linear least squares fitting to estimate the parameters for the Vollenweider model, which describes the relationship between PAR and ETR. The model used is: + +$$p = p_{max} \cdot \frac{a \cdot i}{\sqrt{1 + (a \cdot i)^2}} \cdot \frac{1}{\left(\sqrt{1 + (\alpha \cdot i)^2}\right)^n}$$ + +It is valid: $$i = PAR; p = ETR$$ + +### Example + +```r +result_vollenweider_ETR_II <- vollenweider_generate_regression_ETR_II(data, + pmax_start_value = 40, + a_start_value = 0.1, + alpha_start_value = -0.0001, + n_start_value = 350) +``` + +### References + +Vollenweider, R. A. (1965). *Calculation models of photosynthesis-depth curves and some implications regarding day rate estimates in primary production measurements*, p. 427-457. In C. R. Goldman [ed.], *Primary Productivity in Aquatic Environments*. Mem. Ist. Ital. Idrobiol., 18 Suppl., University of California Press, Berkeley. + + + +## platt_generate_regression_ETR_I() and platt_generate_regression_ETR_II() + +### Parameters + +- **data**: A `data.table` containing the input data from `read_dual_pam_data`. +- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_value_platt_default`. +- **beta_start_value**: Numeric. The starting value for the parameter $$\beta$$ in the model. Defaults to `beta_start_value_platt_default`. +- **ps_start_value**: Numeric. The starting value for the parameter $$p_s$$ in the model. Defaults to `ps_start_value_platt_default`. + +### Return + +A list containing the following elements: + +- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **ps**: The maximum electron transport rate without photoinhibition ($$P_s$$). +- **alpha**: The initial slope of the light curve ($$\alpha$$). +- **beta**: The photoinhibition of the light curve ($$\beta$$). +- **pm**: The maximum electron transport rate with photoinhibition ($$P_m$$). Calculated as: + +$$P_m = P_s \cdot \left(\frac{\alpha}{\alpha + \beta}\right) \cdot \left(\left(\frac{\beta}{\alpha + \beta}\right)^{\frac{\beta}{\alpha}}\right)$$ + +- **ik**: PAR where the transition point from light limitation to light saturation is achieved with photoinhibition ($$I_k$$). Calculated as: + +$$I_k = \frac{P_m}{\alpha}$$ + +- **is**: PAR where the transition point from light limitation to light saturation is achieved without photoinhibition ($$I_s$$). Calculated as: + +$$I_s = \frac{P_s}{\alpha}$$ + +- **im**: The PAR at which the maximum electron transport rate is achieved with photoinhibition ($$I_m$$). Calculated as: + +$$I_m = \left(\frac{P_s}{\alpha}\right) \cdot \log\left(\frac{\alpha + \beta}{\beta}\right)$$ + +- **ib**: ($$I_b$$) Calculated as: + +$$I_b = \frac{P_s}{\beta}$$ + +### Details + +This function uses non-linear least squares fitting to estimate the parameters for the Platt model, which describes the relationship between PAR and ETR. The model used is: + +$$P = P_s \cdot \left(1 - e^\frac{{-\alpha \cdot I}}{P_s}\right) \cdot e^\left(\frac{{-\beta \cdot I}}{P_s}\right)$$ + +It is valid: $$I = PAR; p = ETR$$ + +### Example + +```r +result_platt_ETR_II <- platt_generate_regression_ETR_II(data, + alpha_start_value = 0.3, + beta_start_value = 0.01, + ps_start_value = 30) +``` + +### References + +Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). *Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton*. Journal of Marine Research, 38(4). Retrieved from . + + + +## eilers_peeters_generate_regression_ETR_I() and eilers_peeters_generate_regression_ETR_II() + +### Parameters + +- **data**: A `data.table` containing the input data from `read_dual_pam_data`. +- **a_start_value**: Numeric. The starting value for the parameter $$a$$ in the model. Defaults to `a_start_values_eilers_peeters_default`. +- **b_start_value**: Numeric. The starting value for the parameter $$b$$ in the model. Defaults to `b_start_values_eilers_peeters_default`. +- **c_start_value**: Numeric. The starting value for the parameter $$c$$ in the model. Defaults to `c_start_values_eilers_peeters_default`. + +### Return + +A list containing the following elements: + +- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **a**: The obtained parameter $$a$$. +- **b**: The obtained parameter $$b$$. +- **c**: The obtained parameter $$c$$. +- **pm**: The maximum electron transport rate ($$p_m$$). Calculated as: + +$$p_m = \frac{1}{b + 2 \sqrt{a \cdot c}}$$ + +- **s**: The initial slope of the light curve ($$s$$). Calculated as: + +$$s = \frac{1}{c}$$ + +- **ik**: PAR where the transition point from light limitation to light saturation is achieved ($$I_k$$). Calculated as: + +$$I_k = \frac{c}{b + 2 \sqrt{a \cdot c}}$$ + +- **im**: The PAR at which the maximum electron transport rate is achieved ($$I_m$$). Calculated as: + +$$I_m = \sqrt{\frac{c}{a}}$$ + +- **w**: The sharpness of the peak ($$w$$). Calculated as: + +$$w = \frac{b}{\sqrt{a \cdot c}}$$ + +### Details + +This function uses non-linear least squares fitting to estimate the parameters for the Eilers-Peeters model, which describes the relationship between PAR and ETR. The model used is: + +$$ p = \frac{I}{a \cdot I^2 + b \cdot I + c} $$ + +It is valid: $$I = PAR$$; $$p = ETR$$ + +### Example + +```r +result_eilers_peeters_ETR_II <- eilers_peeters_generate_regression_ETR_II(data, +a_start_value = 0.00004, +b_start_value = 0.004, +c_start_value = 5) +``` + +### References + +Eilers, P. H. C., & Peeters, J. C. H. (1988). *A model for the relationship between light intensity and the rate of photosynthesis in phytoplankton.* Ecological Modelling, 42(3-4), 199-215. [doi:10.1016/0304-3800(88)90057-9](https://doi.org/10.1016/0304-3800(88)90057-9). + + + +### walsby_generate_regression_ETR_I() and walsby_generate_regression_ETR_II() + +### Parameters + +- **data**: A `data.table` containing the input data from `read_dual_pam_data`. +- **etr_max_start_value**: Numeric. The starting value for the parameter $$ETR_{max}$$ in the model. Defaults to `etr_max_start_value_walsby_default`. +- **alpha_start_value**: Numeric. The starting value for the parameter $$\alpha$$ in the model. Defaults to `alpha_start_value_walsby_default`. +- **beta_start_value**: Numeric. The starting value for the parameter $$\beta$$ in the model. Defaults to `beta_start_value_walsby_default`. + +### Return + +A list containing the following elements: + +- **etr_regression_data**: A `data.table` with the predicted values of ETR I or ETR II to each PAR based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **etr_max**: The maximum electron transport rate without photoinhibition ($$ETR_{max}$$). +- **alpha**: The initial slope of the light curve ($$\alpha$$). +- **beta**: The photoinhibition of the light curve ($$\beta$$). + +### Details + +This function uses non-linear least squares fitting to estimate the parameters for the Walsby model, which describes the relationship between PAR and ETR I. The model used is: + +$$ETR = ETR_{max} \cdot \left(1 - e^{\left(-\frac{\alpha \cdot I}{ETR_{max}}\right)}\right) + \beta \cdot I$$ + +It is valid: $$I = PAR$$ + +This function generates a regression model based on Walsby (1997) in a modified version without the respiration term. +Naming conventions from Romoth (2019) are used. +ETRmax is calculated without taking photoinhibition into account. + + +### References + +Walsby, A. E. (1997). Numerical integration of phytoplankton photosynthesis through time and depth in a water column. *New Phytologist*, 136(2), 189-209. + +Romoth, K., Nowak, P., Kempke, D., Dietrich, A., Porsche, C., & Schubert, H. (2019). Acclimation limits of *Fucus evanescens* along the salinity gradient of the southwestern Baltic Sea. *Botanica Marina*, 62(1), 1-12. \ No newline at end of file diff --git a/docs/functions/modify_model_results.md b/docs/functions/modify_model_results.md new file mode 100644 index 0000000..ca1ff9b --- /dev/null +++ b/docs/functions/modify_model_results.md @@ -0,0 +1,251 @@ +# Modify model results + +Those function standardize the naming of the model results depending on the model chosen. + +## vollenweider_modified() + +### Parameters + +- **model_result**: A list containing the results of the model, including parameters such as `pmax`, `alpha`, and `ik`. + +### Return + +Returns a modified model result as a list with the following elements: + +- **etr_type**: ETR Type based on the model result. +- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` +- **b**: obtained paramter `b`, transfered as `a` +- **c**: obtained paramter `c`, here transfered as `alpha` +- **d**: obtained paramter `c`, here transfered as `n` +- **alpha**: The initial slope of the light curve, calculated as: + +$${alpha} = \frac{{etrmax\\_with\\_photoinhibition}}{{ik\\_with\\_photoinhibition}}$$ + +- **beta**: Not available, here set to `NA_real_` +- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `popt` +- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `pmax` +- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as: `iik` +- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, transfered as: `ik` +- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account. Although $I_m$ was mentioned in the original publication, no general solution was presented. Therefore, we decided to include it only in the modified version. Determined as: + +```r + etr_regression_data <- get_etr_regression_data_from_model_result(model_result) + im_with_photoinhibition <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ][[PAR_name]] +``` + +- **w**: Not available, here set to `NA_real_` +- **ib**: Not available, here set to `NA_real_` +- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`, transfered as: `pmax_popt_and_ik_iik_ratio` + +### Details + +This function validates the `model_result` input and processes relevant parameters for the Vollenweider model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different models. + +### Examples + +```r +modified_result_vollenweider <- vollenweider_modified(model_result_vollenweider) +``` + + +## platt_modified() + +### Parameters + +- **model_result**: A list containing the results of the model, including parameters such as `etr_max`, `alpha`, and `beta`. + +### Return + +Returns a modified model result as a list with the following elements: + +- **etr_type**: ETR Type based on the model result. +- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` +- **b**: obtained paramter `b`, here equal to `alpha` +- **c**: obtained paramter `c`, here equal to `beta` +- **d**: not available, here set to `NA_real_` +- **alpha**: The initial slope of the light curve, transfered unchanged as `alpha` +- **beta**: The photoinhibition of the light curve, transfered unchanged as `beta` +- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `pm` +- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `ps` +- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as: `ik` +- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, transfered as: `is` +- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, transfered as: `im` +- **w**: Not available, here set to `NA_real_` +- **ib**: Transfered unchange as: `ib` +- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`. Calculated as: + +$${{etrmax\\_without\\_with\\_ratio}} = \frac{{etrmax\\_without\\_photoinhibition}}{{etrmax\\_with\\_photoinhibition}}$$ + +### Details + +This function validates the `model_result` input and processes relevant parameters for the Platt model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different models. + +### Examples + +```r +modified_result_platt <- platt_modified(model_result_platt) +``` + + + +## eilers_peeters_modified() + +This function adds parameters that were not originally included in the Eilers and Peeters (1988) model, but were introduced by other models and renames the parameters to a standardised one for all models. See the table below. + +### Parameters + +- **model_result**: A list containing the results of the model, including parameters such as `a`, `b`, `c`, `s`, `pm`, `ik`, `im`, and `w`. + +### Return + +Returns a modified model result as a list with the following elements: + +- **etr_type**: ETR Type based on the model result. +- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **a**: The obtained parameter $$a$$ +- **b**: The obtained parameter $$b$$ +- **c**: The obtained parameter $$c$$ +- **d**: Not available, here set to `NA_real_` +- **alpha**: The initial slope of the light curve, transfered unchanged as `s` +- **beta**: Not available, here set to `NA_real_` +- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, transfered as `pm` +- **etrmax_without_photoinhibition**: Not available, here set to `NA_real_` +- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, transfered as `ik` +- **ik_without_photoinhibition**: Not available, here set to `NA_real_` +- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, transfered as`im` +- **w**: The sharpness of the peak, transfered as `w` +- **ib**: Not available, here set to `NA_real_` +- **etrmax_without_with_ratio**: Not available, here set to `NA_real_` + +### Details + +This function validates the `model_result` input, extracts relevant parameters for the modified Eilers-Peeters model, and creates a structured list using `create_modified_model_result`. The list serves as a standardized output format for further analysis. + +### Examples + +```r +# Example usage for eilers_peeters_modified +modified_result <- eilers_peeters_modified(model_result_eilers_peeters) +``` + +## walsby_modified() + +### Parameters + +- **model_result**: A list containing the results of the model, including parameters such as `etr_max`, `alpha`, and `beta`. + +### Return + +Returns a modified model result as a list with the following elements: + +- **etr_type**: ETR Type based on the model result. +- **etr_regression_data**: Regression data with ETR predictions based on the fitted model. +- **residual_sum_of_squares**: Difference between observed and predicted ETR values, expressed as the sum of squared residuals. +- **root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the root mean squared error. +- **relative_root_mean_squared_error**: Difference between observed and predicted ETR values, expressed as the relative root mean squared error, normalized by the mean. +- **a**: obtained paramter `a`, here equal to `etrmax_without_photoinhibition` +- **b**: obtained paramter `b`, here equal to `alpha` +- **c**: obtained paramter `c`, here equal to `beta` +- **d**: not available, here set to `NA_real_` +- **alpha**: The initial slope of the light curve, transfered unchanged as `alpha` +- **beta**: The photoinhibition of the light curve, transfered unchanged as `beta` +- **etrmax_with_photoinhibition**: The maximum electron transport rate with photoinhibition, determined as: + +```r + etr_regression_data <- get_etr_regression_data_from_model_result(model_result) + etr_max_row <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ] + etrmax_with_photoinhibition <- etr_max_row[[prediction_name]] +``` + +- **etrmax_without_photoinhibition**: The maximum electron transport rate without photoinhibition, transfered as: `etr_max` +- **ik_with_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved taking photoinhibition into account, calculated as: + +$$ik\\_with\\_photoinhibition = \frac{etrmax\\_with\\_photoinhibition}{alpha}$$ + +- **ik_without_photoinhibition**: PAR where the transition point from light limitation to light saturation is achieved not taking photoinhibition into account, calculated as: + +$$ik\\_without\\_photoinhibition = \frac{etrmax\\_without\\_photoinhibition}{alpha}$$ + +- **im_with_photoinhibition**: The PAR at which the maximum electron transport rate is achieved by taking photoinhibition into account, calculated as: + +```r + etr_regression_data <- get_etr_regression_data_from_model_result(model_result) + etr_max_row <- etr_regression_data[etr_regression_data[[prediction_name]] == max(etr_regression_data[[prediction_name]]), ] + im_with_photoinhibition <- etr_max_row[[PAR_name]] +``` + +- **w**: Not available, here set to `NA_real_` +- **ib**: Not available, here set to `NA_real_` +- **etrmax_without_with_ratio**: Ratio of `etrmax_without_photoinhibition` / `etrmax_with_photoinhibition` and `ik_without_photoinhibition` / `ik_with_photoinhibition`. Calculated as: + +$${{etrmax\\_without\\_with\\_ratio}} = \frac{{etrmax\\_without\\_photoinhibition}}{{etrmax\\_with\\_photoinhibition}}$$ + +### Details + +This function validates the `model_result` input and processes relevant parameters for the Walsby model, creating a structured list using `create_modified_model_result`. This standardized output allows for consistent analysis and comparison across different photosynthesis models. + +### Examples + +```r +modified_result <- walsby_modified(model_result_walsby) +``` + + +## Naming overview + +### Publication-accurate naming and the respective modified naming + +modified |Eilers and Peeters |Platt |Walsby |Vollenweider | +|-|-|-|-|-| +|residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares | +|root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error | +|relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error | +|a |a |ps |etr_max |pmax | +|b |b |alpha |alpha |a | +|c |c |beta |beta |alpha | +|d |NA |NA |NA |n | +|alpha |s |alpha |alpha |NA | +|beta |NA |beta |beta |NA | +|etrmax_with_photoinhibition |pm |pm |NA |popt | +|etrmax_without_photoinhibition |NA |ps |etr_max |pmax | +|ik_with_photoinhibition |ik |ik |NA |iik | +|ik_without_photoinhibition |NA |is |NA |ik | +|im_with_photoinhibition |im |im |NA |NA | +|w |w |NA |NA |NA | +|ib |NA |ib |NA |NA | +|etrmax_without_with_ratio |NA |NA |NA |pmax_popt_and_ik_iik_ratio | + + + +### Publication-accurate naming and the respective modified naming with additional calculations not included in the original publication + +|modified |Eilers and Peeters |Platt |Walsby |Vollenweider | +|-|-|-|-|-| +|residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares |residual_sum_of_squares | +|root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error |root_mean_squared_error | +|relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error |relative_root_mean_squared_error | +|a |a |ps |etr_max |pmax | +|b |b |alpha |alpha |a | +|c |c |beta |beta |alpha | +|d |NA |NA |NA |n | +|alpha |s |alpha |alpha |real_alpha | +|beta |NA |beta |beta |NA | +|etrmax_with_photoinhibition |pm |pm |etrmax_with_photoinhibition |popt | +|etrmax_without_photoinhibition |NA |ps |etr_max |pmax | +|ik_with_photoinhibition |ik |ik |ik_with_photoinhibition |iik | +|ik_without_photoinhibition |NA |is |ik_without_photoinhibition |ik | +|im_with_photoinhibition |im |im |im_with_photoinhibition |im_with_photoinhibition | +|w |w |NA |NA |NA | +|ib |NA |ib |NA |NA | +|etrmax_without_with_ratio |NA |etrmax_without_with_ratio |etrmax_without_with_ratio |pmax_popt_and_ik_iik_ratio | diff --git a/docs/functions/plot_control.md b/docs/functions/plot_control.md new file mode 100644 index 0000000..b6b9f6a --- /dev/null +++ b/docs/functions/plot_control.md @@ -0,0 +1,68 @@ +# Control plots + +## plot_control() + +This function creates a control plot for the used model based on the provided data and model results. + +### Parameters + +- **data**: A `data.table` containing the original ETR and yield data for the plot. +- **model_result**: A list containing the fitting results of the used model and the calculated parameters (alpha, ik, etc.). +- **title**: A character string that specifies the title of the plot. +- **color**: A color specification for the regression line in the plot. + +### Return + +A plot displaying the original ETR and Yield values and the regression data. A table below the plot shows the calculated data (alpha, ik, etc.). + +### Example + +```r +plot_control_eilers_peeters_ETR_II <- plot_control( + data = pam_data, + model_result = modified_model_result_eilers_peeters_ETR_II, + title = "eilers_peeters ETR II modified 20240925.csv", + color = "purple" +) +print(plot_control_eilers_peeters_ETR_II) +``` + +![Plot](../../img/test-eilers_peeters_etr_II_modified_control_plot_20240925.jpg) + +## combo_plot_control() + +The `combo_plot_control()` function generates a combined plot of electron transport rate (ETR) data and regression model predictions, along with a customized table summarizing the parameters for each model. + +### Parameters + +- **title**: A character string specifying the title for the plot. +- **data**: A data frame containing the raw input data for ETR and Photosynthetically Active Radiation (PAR). +- **model_results**: A list of model results, where each model result is a list containing regression data and parameters for ETR. +- **name_list**: A list of names corresponding to each model result. These names will be used in the legend and table. +- **color_list**: A list of color values for each model result. Colors are used to differentiate lines on the plot. + +### Return + +A plot displaying the original ETR and Yield values and the regression data from different models. A table below the plot shows the calculated data (alpha, ik, etc.). + +### Examples + +```r +test_data_file <- file.path(getwd(), "data", "dual_pam_data", "20240925.csv") + data <- read_dual_pam_data(test_data_file) + + eilers_peeters <- eilers_peeters_modified(eilers_peeters_generate_regression_ETR_II(data)) + platt <- platt_modified(platt_generate_regression_ETR_II(data)) + walsby <- walsby_modified(walsby_generate_regression_ETR_II(data)) + vollenweider <- vollenweider_modified(vollenweider_generate_regression_ETR_II(data)) + + plot <- combo_plot_control( + "etr II test-combo_plot_control_20240925.csv", + data, + list(eilers_peeters, platt, walsby, vollenweider), + list("eilers_peeters", "platt", "walsby", "vollenweider"), + list("purple", "blue", "green", "red") + ) +``` + +![combo Plot](../../img/test_combo_plot_control_etr_II.jpg) \ No newline at end of file diff --git a/docs/functions/read_data.md b/docs/functions/read_data.md new file mode 100644 index 0000000..3adb7f1 --- /dev/null +++ b/docs/functions/read_data.md @@ -0,0 +1,326 @@ +# Read data + +Those functions read raw data CSV files, compute the $$ETR$$ values, and are returning an intermediate table. + +## read_universal_data() + +### Description + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ + +### Details + +ETR values are calculated using the following formula: + +$$ \textit{ETR (I or II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (I or II)} \cdot \textit{Yield (I or II)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV data using `read.csv()`. +- Converting the data into a `data.table`. +- Validating the raw data structure with `validate_raw_intermediate_csv()`. +- Iterating through each row to calculate ETR values for both `yield_1` and `yield_2` using `calc_etr()`. + +### Return + +Returning a new table containing the original `par`, `yield_1`, `yield_2`, and the calculated `etr_1` and `etr_2` columns. + +### Example + +```r +data <- read_dual_pam_data("path/to/data.csv", +etr_factor = 0.84, +fraction_photosystem_I = 0.5, +fraction_photosystem_II = 0.5) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) + + + +## read_dual_pam_data() + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ + +### Details + +Device: [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) + +Mode: Dual channel mode (P700 + Fluo) + +ETR values are calculated using the following formula: + +$$ \textit{ETR (I or II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (I or II)} \cdot \textit{Yield (I or II)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV data using `read.csv()` and converting it to a `data.table`. +- Validating the raw Dual-PAM data with `validate_dual_pam_data()`. +- Filtering rows where the column `ID` equals `SP` +- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. +- Calculating initial ETR values from `Pm.-Det.` and `Fm-Det.` rows using `calc_etr()`. +- Iterating through all rows with `Action == "P.+F. SP"` to calculate ETR values for both `Y.I.` and `Y.II.` +- Stopping at the recovery period if `remove_recovery = TRUE`. + +### Return + +- Returning a table containing `par`, `yield_1`, `yield_2`, and the calculated `etr_1` and `etr_2` columns. + +### Example + +```r +data <- read_dual_pam_data("path/to/data.csv", +remove_recovery = TRUE, +etr_factor = 0.84, +fraction_photosystem_I = 0.5, +fraction_photosystem_II = 0.5) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) + + + +## read_dual_pam_single_channel_p700_data() + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to Photosystem I used in the ETR calculation formula. Default is `0.5`. + Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to Photosystem II. Default is `0.5`. + (Must sum with Photosystem I fraction to 1.) + +### Details + +Device: [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) + +Mode: Single channel mode (P700) + +ETR values for Photosystem I are calculated using the following formula: + +$$ \textit{ETR (I)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem I} \cdot \textit{Yield (I)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV data using `read.csv()` and converting it to a `data.table`. +- Validating the raw Dual-PAM data with `validate_dual_pam_single_channel_p700_data()`. +- Filtering rows where the column `ID` equals `SP`. +- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. +- Extracting the initial Pm.-Det. measurement at `PAR = 0` to calculate the first ETR value. +- Iterating through all rows with `Action == "P700 SP"` to calculate ETR values for Photosystem I (`Y.I.`). +- Stopping at the recovery period if `remove_recovery = TRUE`. + +### Return + +- Returning a table containing: + - `par`: Photosynthetically active radiation. + - `yield_1`: Yield of Photosystem I. + - `yield_2`: `NA` (not available in single channel mode (P700)). + - `etr_1`: Calculated ETR for Photosystem I. + - `etr_2`: `NA` (not available in single channel mode (P700)). + +### Example + +```r +data <- read_dual_pam_single_channel_p700_data( + "path/to/data.csv", + remove_recovery = TRUE, + etr_factor = 0.84, + fraction_photosystem_I = 0.5, + fraction_photosystem_II = 0.5 +) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) + + +## read_dual_pam_single_channel_fluo_data() + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to Photosystem I. Default is `0.5`. +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to Photosystem II used in the ETR calculation formula. Default is `0.5`. + Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ + +### Details + +Device: [DUAL-PAM-100](https://www.walz.com/products/dual-pam-100/) + +Mode: Single channel mode (Fluo) + +ETR values for Photosystem II are calculated using the following formula: + +$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem II} \cdot \textit{Yield (II)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV data using `read.csv()` and converting it to a `data.table`. +- Validating the raw Dual-PAM data with `validate_dual_pam_single_channel_fluo_data()`. +- Filtering rows where the column `ID` equals `SP`. +- Combining the `Date` and `Time` columns to create a `DateTime` column and ordering the data chronologically. +- Extracting the initial **Fm-Det.** measurement at `PAR = 0` to calculate the first ETR value. +- Iterating through all rows with `Action == "Fluo. SP"` to calculate ETR values for Photosystem II (`Y.II.`). +- Stopping at the recovery period if `remove_recovery = TRUE`. + +### Return + +- Returning a table containing: + - `par`: Photosynthetically active radiation. + - `yield_1`: `NA` (not available in single channel Photosystem II mode). + - `yield_2`: Yield of Photosystem II. + - `etr_1`: `NA` (not available in single channel Photosystem II mode). + - `etr_2`: Calculated ETR for Photosystem II. + +### Example + +```r +data <- read_dual_pam_single_channel_fluo_data( + "path/to/data.csv", + remove_recovery = TRUE, + etr_factor = 0.84, + fraction_photosystem_I = 0.5, + fraction_photosystem_II = 0.5 +) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) + + +## read_junior_pam_data() + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **remove_recovery**: Automatic removal of recovery measurements after the actual Pi curve for an accurate regression. Default is `TRUE`. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II used in the ETR calculation formula. Default is `0.5`. +Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ + +### Details + +Device: [JUNIOR-PAM](https://www.walz.com/products/junior-pam/) + +ETR values are calculated using the following formula: + +$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem (II)} \cdot \textit{Yield (II)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV data using `read.csv()` and converting it to a `data.table`. +- Validating the raw Junior-PAM data with `validate_junior_pam_data()`. +- Renaming columns to standard names (`PAR`, `Y.II`.) if necessary. +- Filtering rows where Type equals `"FO"` or `"F"`. +- Ordering by `Time (rel/ms)` column. +- Iterating through all rows to calculate ETR values for `Y.II.` using `calc_etr()`. +- Stopping at the recovery period if `remove_recovery = TRUE`. + +To ensure the file is imported correctly, please export the CSV file using the default settings: +![Plot](../../img/export_junior_pam.png) + +### Return + +Returning a table containing `par`, `yield_1` (NA), `yield_2`, `etr_1` (NA), and `etr_2`. + +### Example + +```r +data <- read_junior_pam_data("path/to/data.csv", +remove_recovery = TRUE, +etr_factor = 0.84, +fraction_photosystem_I = 0.5, +fraction_photosystem_II = 0.5) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) + + + +## read_pam_2500_data() + +### Parameters + +- **csv_path**: A string representing the file path to the CSV file. +- **remove_recovery**: Logical value indicating whether recovery measurements after the actual Pi curve should be removed. Default is `TRUE`. +- **etr_factor**: A numeric value used as a factor for calculating ETR. Default is `0.84`. +- **fraction_photosystem_I**: A numeric value representing the relative distribution of absorbed PAR to photosystem I. Default is `0.5`. + Calculated as: $$\textit{Fraction of Photosystem I} = \frac{PPS 1}{PPS 1+2}$$ +- **fraction_photosystem_II**: A numeric value representing the relative distribution of absorbed PAR to photosystem II. Default is `0.5`. + Calculated as: $$\textit{Fraction of Photosystem II} = \frac{PPS 2}{PPS 1+2}$$ + +### Details + +Device: [PAM-2500](https://www.walz.com/products/pam-2500/) + +ETR values are calculated using the following formula: + +$$ \textit{ETR (II)} = PAR \cdot \textit{ETR–Factor} \cdot \textit{Fraction of Photosystem II} \cdot \textit{Yield (II)} $$ + +The function processes the provided CSV file by: + +- Reading the CSV file using `read.csv()` with `;` as separator and converting it to a `data.table`. +- Validating the dataset using `validate_pam_2500_data()`. +- Filtering rows where the column `No.` contains numeric entries only. +- Combining the `Date` and `Time` columns into a `DateTime` column and sorting the dataset chronologically. +- Iterating through all rows to: + - Extract `PAR` and `Y.II.` values. + - Calculate ETR for Photosystem II using `calc_etr()`. +- Optionally stopping at the recovery phase if `remove_recovery = TRUE`, defined as a decrease in PAR values. +- Constructing a result table with calculated values. + +### Return + +- A `data.table` containing the following columns: + + - `par`: Photosynthetically active radiation + - `yield_1`: Placeholder column (`NA`) + - `yield_2`: Effective quantum yield of Photosystem II + - `etr_1`: Placeholder column (`NA`) + - `etr_2`: Calculated electron transport rate for Photosystem II + +### Example + +```r +data <- read_pam_2500_data( + "path/to/data.csv", + remove_recovery = TRUE, + etr_factor = 0.84, + fraction_photosystem_I = 0.5, + fraction_photosystem_II = 0.5 +) +``` + +### References + +- Heinz Walz GmbH. (2024). *DUAL-PAM-100 DUAL-PAM/F MANUAL, 5th Edition, April 2024, Chapter 7 (pp. 162-172).* Heinz Walz GmbH, Effeltrich, Germany. Available at: [DUAL-PAM-100 Manual](https://www.walz.com/files/downloads/dualpamed05.pdf) diff --git a/docs/functions/write_model_results.md b/docs/functions/write_model_results.md new file mode 100644 index 0000000..007ea36 --- /dev/null +++ b/docs/functions/write_model_results.md @@ -0,0 +1,33 @@ +# Write model result + +This function exports the raw input data, regression data, and model parameters into separate CSV files for easy access and further analysis. + +## write_model_result_csv() + +### Parameters + +- **dest_dir**: A character string specifying the directory where the CSV files will be saved. +- **name**: A character string specifying the base name for the output files. +- **data**: A data frame containing the raw input data used in the model. +- **model_result**: A list containing the model results, including parameter values and regression data. + +### Details + +This function creates three CSV files: + +1. **`name_raw_data.csv`**: Contains the original raw data used in the model. +2. **`name_regression_data.csv`**: Contains the regression data with predictions for electron transport rate (ETR). +3. **`name_model_result.csv`**: Contains the parameter values from the model results (excluding regression data), including parameters like `alpha`, `beta`, and `etr_max`. + +Each file will be named using the `name` parameter as a prefix, followed by a specific suffix for clarity. + +### Examples + +```r +write_model_result_csv( + dest_dir = "output", + name = "001", + data = intermediate_table, + model_result = model_result +) +``` \ No newline at end of file diff --git a/examples/Example_combo_plot_control.R b/examples/Example_combo_plot_control.R deleted file mode 100644 index e862800..0000000 --- a/examples/Example_combo_plot_control.R +++ /dev/null @@ -1,28 +0,0 @@ -##### example for combo plot control#### -install.packages("remotes") -remotes::install_github("biotoolbox/pam", subdir = "src") -library("pam") -library("ggplot2") - -#### raw data file directory#### -script_dir <- dirname(sys.frame(1)$ofile) -data_path <- file.path(script_dir, "data", "20231122_01.csv") -data <- read_dual_pam_data(data_path) -output_dir <- file.path(script_dir, "output") -dir.create(output_dir, showWarnings = FALSE) - -#### getting model results#### -model_result_eilers_peeters_ETR_II_modified <- eilers_peeters_modified(eilers_peeters_generate_regression_ETR_II(data)) -model_result_platt_ETR_II_modified <- platt_modified(platt_generate_regression_ETR_II(data)) -model_result_vollenweider_ETR_II_modified <- vollenweider_modified(vollenweider_generate_regression_ETR_II(data)) -model_result_walsby_ETR_II_modified <- walsby_modified(walsby_generate_regression_ETR_II(data)) - -#### combo_plot_control#### -model_results <- list(model_result_eilers_peeters_ETR_II_modified, model_result_platt_ETR_II_modified, model_result_vollenweider_ETR_II_modified, model_result_walsby_ETR_II_modified) -name_list <- list("Eilers & Peeters", "Platt", "Vollenweider", "Walsby") -color_list <- list("blue", "red", "green", "orange") - -combo_plot_control <- combo_plot_control("combo_plot_control_20231122_01.csv", data, model_results, name_list, color_list) -print(combo_plot_control) -ggsave("combo_plot_control_20231122_01.jpg", plot = combo_plot_control, width = 10, height = 22, path = output_dir) -#### diff --git a/examples/Example_compare_models.R b/examples/Example_compare_models.R deleted file mode 100644 index 04a6a54..0000000 --- a/examples/Example_compare_models.R +++ /dev/null @@ -1,20 +0,0 @@ -##### example for compare regression models#### -# install library pam -install.packages("remotes") -remotes::install_github("biotoolbox/pam", subdir = "src") -library("pam") - -#### read_dual_pam_data()#### -# raw data file directory -script_dir <- dirname(sys.frame(1)$ofile) -data_dir <- file.path(script_dir, "data", "dual_pam_data", "bulk") - -#### compare_regression_models_ETR_II#### -compare_regression_models_ETR_II_result <- compare_regression_models_ETR_II(data_dir, read_dual_pam_data) -print(compare_regression_models_ETR_II_result) -#### - -#### This warning is expected#### -# file: 20231214_10.csv processed with warning: simpleWarning in value[[3L]](cond): warning while -# calculating platt model: simpleWarning in value[[3L]](cond): failed to calculate im: warning: simpleWarning in -# log((alpha + beta)/beta): NaNs wurden erzeugt diff --git a/examples/Example_multiple_data.R b/examples/Example_multiple_data.R deleted file mode 100644 index e3d8c41..0000000 --- a/examples/Example_multiple_data.R +++ /dev/null @@ -1,74 +0,0 @@ -##### example for multiple files with eilers and peeters model#### -install.packages("remotes") -remotes::install_github("biotoolbox/pam", subdir = "src") -library("pam") - - -#### raw data file directory#### -script_dir <- dirname(sys.frame(1)$ofile) -data_dir <- file.path(script_dir, "data", "dual_pam_data", "bulk") -output_dir <- file.path(script_dir, "output") -dir.create(output_dir, showWarnings = FALSE) -output_path_pdf <- file.path(output_dir, "eilers_peters_plot_control.pdf") -reload_data_dir <- output_dir - -#### read_dual_pam_data()#### -csv_files <- - list.files( - path = data_dir, - pattern = "\\.csv$", - full.names = TRUE - ) -data_list <- list() -for (file in csv_files) { - data_list <- append(data_list, list(list( - file_name = basename(file), - data = read_dual_pam_data(file) - ))) -} - -#### eilers_peeters_generate_regression_ETR_II()#### -results_list <- list() -for (data_entry in data_list) { - model_result <- - eilers_peeters_generate_regression_ETR_II(data_entry$data) - results_list <- append(results_list, list( - list( - file_name = data_entry$file_name, - data = data_entry$data, - model_result = model_result - ) - )) -} - -#### Function to create plots and save to PDF#### -pdf(output_path_pdf, onefile = TRUE) -for (result_entry in results_list) { - title <- result_entry$file_name - data <- result_entry$data - model_result <- result_entry$model_result - plot <- plot_control( - data = data, - model_result = model_result, - title = title, - color = "black" - ) - print(plot) - cat("Processed file:", title, "\n") -} -dev.off() - - -#### write_model_result_csv #### -for (result_entry in results_list) { - file_name <- result_entry$file_name - data <- result_entry$data - model_result_eilers_peeters_ETR_II <- result_entry$model_result - write_model_result_csv( - output_dir, - file_name, - data, - model_result_eilers_peeters_ETR_II - ) - cat("Processed file:", file_name, "\n") -} diff --git a/examples/Example_single_data.R b/examples/Example_single_data.R deleted file mode 100644 index 083fad0..0000000 --- a/examples/Example_single_data.R +++ /dev/null @@ -1,28 +0,0 @@ -##### simple example for one file with eilers and peeters model#### -# install library pam -install.packages("remotes") -remotes::install_github("biotoolbox/pam", subdir = "src") -library("pam") -library("ggplot2") - -#### read_dual_pam_data()#### -script_dir <- dirname(sys.frame(1)$ofile) -data_path <- file.path(script_dir, "data", "20231122_01.csv") -data <- read_dual_pam_data(data_path) -output_dir <- file.path(script_dir, "output") -dir.create(output_dir, showWarnings = FALSE) - -#### eilers_peeters_generate_regression_ETR_II()#### -model_result_eilers_peeters_ETR_II <- eilers_peeters_generate_regression_ETR_II(data) - -#### eilers_peeters_modified()#### -model_result_eilers_peeters_ETR_II_modified <- eilers_peeters_modified(model_result_eilers_peeters_ETR_II) - -#### plot_control()#### -plot_control_eilers_peeters_ETRII_modifed <- plot_control(data, model_result_eilers_peeters_ETR_II_modified, "plot_control_eilers_peeters_ETRII_modifed_20231122_01.jpg", color = "blue") -print(plot_control_eilers_peeters_ETRII_modifed) -ggsave("20231122_01.jpg", plot = plot_control_eilers_peeters_ETRII_modifed, path = output_dir, width = 10, height = 10) - -#### write_model_result_csv#### -write_model_result_csv(output_dir, "20231122_01.csv", data, model_result_eilers_peeters_ETR_II_modified) -#### diff --git a/examples/example_combo_plot_control.R b/examples/example_combo_plot_control.R new file mode 100644 index 0000000..33acd9e --- /dev/null +++ b/examples/example_combo_plot_control.R @@ -0,0 +1,48 @@ +# example for combo plot control +install.packages("pam") +library("pam") +library("ggplot2") + +script_dir <- file.path(getwd(), "examples") +data_path <- file.path(script_dir, "data", "20231122_01.csv") +data <- read_dual_pam_data(data_path) +output_dir <- file.path(script_dir, "output") +dir.create(output_dir, showWarnings = FALSE) + +# generating regression data +eilers_peeters <- eilers_peeters_generate_regression_ETR_II(data) +platt <- platt_generate_regression_ETR_II(data) +vollenweider <- vollenweider_generate_regression_ETR_II(data) +walsby <- walsby_generate_regression_ETR_II(data) + +# modifying model results +eilers_peeters_modified <- eilers_peeters_modified(eilers_peeters) +platt_modified <- platt_modified(platt) +vollenweider_modified <- vollenweider_modified(vollenweider) +walsby_modified <- walsby_modified(walsby) + +# creating combo control plot +model_results <- list( + eilers_peeters_modified, + platt_modified, + vollenweider_modified, + walsby_modified +) +name_list <- list("Eilers & Peeters", "Platt", "Vollenweider", "Walsby") +color_list <- list("blue", "red", "green", "orange") + +combo_plot_control <- combo_plot_control( + "combo_plot_control_20231122_01.csv", + data, + model_results, + name_list, + color_list +) +print(combo_plot_control) +ggsave( + "combo_plot_control_20231122_01.jpg", + plot = combo_plot_control, + width = 10, + height = 22, + path = output_dir +) diff --git a/examples/example_compare_models.R b/examples/example_compare_models.R new file mode 100644 index 0000000..b54e4f7 --- /dev/null +++ b/examples/example_compare_models.R @@ -0,0 +1,14 @@ +# example for comparing regression models +install.packages("pam") +library("pam") + +script_dir <- file.path(getwd(), "examples") +data_dir <- file.path(script_dir, "data", "bulk") + +result <- compare_regression_models_ETR_II(data_dir, read_dual_pam_data) +print(result) + +# Those warnings are expected +# platt: failed to calculate im: warning: simpleWarning in log((alpha + beta)/beta): NaNs produced +# skipped file: 20231214_12.csv because of error: Error in value[[3L]](cond): error while calculating vollenweider model: Error in nlsModel(formula, mf, start, wts): singular gradient matrix at initial parameter estimates +# skipped file: 20231214_15.csv because of error: Error in value[[3L]](cond): error while calculating vollenweider model: Error in nlsModel(formula, mf, start, wts): singular gradient matrix at initial parameter estimates diff --git a/examples/example_multiple_data.R b/examples/example_multiple_data.R new file mode 100644 index 0000000..60d0b4b --- /dev/null +++ b/examples/example_multiple_data.R @@ -0,0 +1,47 @@ +# example for processing multiple files with the eilers and peeters model +install.packages("pam") +library("pam") + +script_dir <- file.path(getwd(), "examples") +data_dir <- file.path(script_dir, "data", "bulk") +output_dir <- file.path(script_dir, "output") +dir.create(output_dir, showWarnings = FALSE) +output_path_pdf <- file.path(output_dir, "eilers_peters_plot_control.pdf") +reload_data_dir <- output_dir + +pdf(output_path_pdf, onefile = TRUE) +csv_files <- + list.files( + path = data_dir, + pattern = "\\.csv$", + full.names = TRUE + ) +for (file in csv_files) { + file_name <- basename(file) + cat("Processing file:", file_name, "\n") + + # reading raw data csv + intermediate_table <- read_dual_pam_data(file) + + # generating regression model result + model_result <- + eilers_peeters_generate_regression_ETR_II(intermediate_table) + + # generating control plot + plot <- plot_control( + data = intermediate_table, + model_result = model_result, + title = file_name, + color = "black" + ) + print(plot) + + # exporting intermediate table and model result + write_model_result_csv( + output_dir, + file_name, + intermediate_table, + model_result + ) +} +dev.off() diff --git a/examples/example_single_data.R b/examples/example_single_data.R new file mode 100644 index 0000000..e90061a --- /dev/null +++ b/examples/example_single_data.R @@ -0,0 +1,44 @@ +# simple example for one file with eilers and peeters model +install.packages("pam") +library("pam") +library("ggplot2") + +script_dir <- file.path(getwd(), "examples") +data_path <- file.path(script_dir, "data", "20231122_01.csv") +output_dir <- file.path(script_dir, "output") +dir.create(output_dir, showWarnings = FALSE) + +# reading raw data csv +data <- read_dual_pam_data(data_path) + +# generating model result +model_result <- eilers_peeters_generate_regression_ETR_II(data) + +# modifying model result +model_result_modified <- eilers_peeters_modified(model_result) + +# generating plot +plot <- plot_control( + data, + model_result_modified, + "plot_control_eilers_peeters_ETR_II_modifed_20231122_01.jpg", + color = "blue" +) +print(plot) + +# exporting plot +ggsave( + "20231122_01.jpg", + plot = plot, + path = output_dir, + width = 10, + height = 10 +) + +# exporting intermediate table and model result data +write_model_result_csv( + output_dir, + "20231122_01.csv", + data, + model_result_modified +) diff --git a/img/flow.drawio b/img/flow.drawio new file mode 100644 index 0000000..2338b6f --- /dev/null +++ b/img/flow.drawio @@ -0,0 +1,117 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/img/flow.png b/img/flow.png new file mode 100644 index 0000000..a4f5bfb Binary files /dev/null and b/img/flow.png differ diff --git a/src/R/compare_regression_models.R b/src/R/compare_regression_models.R index 59832d2..e7689af 100644 --- a/src/R/compare_regression_models.R +++ b/src/R/compare_regression_models.R @@ -22,7 +22,7 @@ #' \item Walsby (1997) #' } #' Models are ranked based on the deviation between observed and predicted values. The results guide users in selecting the most appropriate model for their dataset. Start values for parameters cannot be adjusted within this function. -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_modified} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' #' @references{ diff --git a/src/R/device_dual_pam.R b/src/R/device_dual_pam.R index 57d7677..fb8bc9e 100644 --- a/src/R/device_dual_pam.R +++ b/src/R/device_dual_pam.R @@ -12,7 +12,7 @@ #' Calculates ETR using: #' \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I or II)} \cdot \text{Yield (I or II)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/device_dual_pam_single_channel_fluo.R b/src/R/device_dual_pam_single_channel_fluo.R index 176c3e4..d3147aa 100644 --- a/src/R/device_dual_pam_single_channel_fluo.R +++ b/src/R/device_dual_pam_single_channel_fluo.R @@ -12,7 +12,7 @@ #' Calculates ETR using: #' \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/device_dual_pam_single_channel_p700.R b/src/R/device_dual_pam_single_channel_p700.R index 0f6ff75..cdfeb85 100644 --- a/src/R/device_dual_pam_single_channel_p700.R +++ b/src/R/device_dual_pam_single_channel_p700.R @@ -12,7 +12,7 @@ #' Calculates ETR using: #' \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I)} \cdot \text{Yield (I)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/device_junior_pam.R b/src/R/device_junior_pam.R index 92e8a5b..5183670 100644 --- a/src/R/device_junior_pam.R +++ b/src/R/device_junior_pam.R @@ -12,7 +12,7 @@ #' Calculates ETR II using: #' \deqn{\text{ETR II} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/device_pam_2500.R b/src/R/device_pam_2500.R index 0389338..af4a7e2 100644 --- a/src/R/device_pam_2500.R +++ b/src/R/device_pam_2500.R @@ -12,7 +12,7 @@ #' Calculates ETR II using: #' \deqn{\text{ETR II} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/device_universal_data.R b/src/R/device_universal_data.R index ddc6941..21d3ea2 100644 --- a/src/R/device_universal_data.R +++ b/src/R/device_universal_data.R @@ -13,7 +13,7 @@ #' Calculates ETR using: #' \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I or II)} \cdot \text{Yield (I or II)}} #' -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_universal_data} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A \code{data.table} containing: #' \itemize{ diff --git a/src/R/model_eilers_peeters.R b/src/R/model_eilers_peeters.R index db50ac0..e175898 100644 --- a/src/R/model_eilers_peeters.R +++ b/src/R/model_eilers_peeters.R @@ -20,7 +20,7 @@ eilers_peeters_default_start_value_c <- 7.012012 #' @param c_start_value Numeric. Starting value for \eqn{c}. Default: \code{c_start_values_eilers_peeters_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#eilers_peeters_generate_regression_etr_i-and-eilers_peeters_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ @@ -73,7 +73,7 @@ eilers_peeters_generate_regression_ETR_I <- function( #' @param c_start_value Numeric. Starting value for \eqn{c}. Default: \code{c_start_values_eilers_peeters_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#eilers_peeters_generate_regression_etr_i-and-eilers_peeters_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ diff --git a/src/R/model_platt.R b/src/R/model_platt.R index 9fab2ed..c0a5fe7 100644 --- a/src/R/model_platt.R +++ b/src/R/model_platt.R @@ -36,7 +36,7 @@ platt_default_start_value_ps <- 49.76112 #' } #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#platt_generate_regression_etr_i-and-platt_generate_regression_etr_ii} . +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} . #' #' @references{ #' Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). \emph{Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton.} @@ -91,7 +91,7 @@ platt_generate_regression_ETR_I <- function( #' } #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#platt_generate_regression_etr_i-and-platt_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @references{ #' Platt, T., Gallegos, C. L., & Harrison, W. G. (1980). \emph{Photoinhibition of photosynthesis in natural assemblages of marine phytoplankton.} diff --git a/src/R/model_vollenweider.R b/src/R/model_vollenweider.R index 485a3e8..6630a6e 100644 --- a/src/R/model_vollenweider.R +++ b/src/R/model_vollenweider.R @@ -25,7 +25,7 @@ vollenweider_default_start_value_n <- 100 #' @param n_start_value Numeric. Initial value for \eqn{n}. Default: \code{n_start_values_vollenweider_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#vollenweider_generate_regression_etr_i-and-vollenweider_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ @@ -83,7 +83,7 @@ vollenweider_generate_regression_ETR_I <- function( #' @param n_start_value Numeric. Initial value for \eqn{n}. Default: \code{n_start_values_vollenweider_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#vollenweider_generate_regression_etr_i-and-vollenweider_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ diff --git a/src/R/model_walsby.R b/src/R/model_walsby.R index b321458..99e44bc 100644 --- a/src/R/model_walsby.R +++ b/src/R/model_walsby.R @@ -21,7 +21,7 @@ walsby_default_start_value_beta <- -0.0008944076 #' @param beta_start_value Numeric. Initial value for \eqn{\beta}. Default: \code{beta_start_value_walsby_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_generate_regression_etr_i-and-walsby_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ @@ -77,7 +77,7 @@ walsby_generate_regression_ETR_I <- function( #' @param beta_start_value Numeric. Initial value for \eqn{\beta}. Default: \code{beta_start_value_walsby_default}. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_generate_regression_etr_i-and-walsby_generate_regression_etr_ii}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A list containing: #' \itemize{ diff --git a/src/R/plot.R b/src/R/plot.R index a3a88e3..b2a86a2 100644 --- a/src/R/plot.R +++ b/src/R/plot.R @@ -9,7 +9,7 @@ #' @param color_list List. Colors for model lines. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#combo_control_plot}. +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. #' #' @return A plot with ETR data, regression results, and a summary table. #' @@ -320,7 +320,7 @@ plot_table <- function(model_result, entries_per_row) { #' @param color A color specification for the regression line in the plot. #' #' @details -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#plot_control} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return A plot displaying the original ETR and Yield values and the regression data. A table below the plot shows the calculated data. #' diff --git a/src/R/write_model_result_csv.R b/src/R/write_model_result_csv.R index 9331646..f789d1a 100644 --- a/src/R/write_model_result_csv.R +++ b/src/R/write_model_result_csv.R @@ -15,7 +15,7 @@ #' \item \strong{model_result.csv:} Summarizes the parameter values derived from the model results (excluding regression data), such as \code{alpha} or \code{beta}. #' } #' The `name` parameter serves as a prefix for each file, ensuring clarity and organization in the output directory. -#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#write_model_result_csv} +#' A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} #' #' @return No return value, called for side effects #' diff --git a/src/man/combo_plot_control.Rd b/src/man/combo_plot_control.Rd index fba2468..2568c1d 100644 --- a/src/man/combo_plot_control.Rd +++ b/src/man/combo_plot_control.Rd @@ -24,7 +24,7 @@ A plot with ETR data, regression results, and a summary table. Generates a plot of ETR data with different regression model predictions and a summary table. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#combo_control_plot}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/compare_regression_models_ETR_I.Rd b/src/man/compare_regression_models_ETR_I.Rd index 579d0b6..6d64107 100644 --- a/src/man/compare_regression_models_ETR_I.Rd +++ b/src/man/compare_regression_models_ETR_I.Rd @@ -33,7 +33,7 @@ This function compares the performance of the following models: \item Walsby (1997) } Models are ranked based on the deviation between observed and predicted values. The results guide users in selecting the most appropriate model for their dataset. Start values for parameters cannot be adjusted within this function. -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_modified} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam")) diff --git a/src/man/eilers_peeters_generate_regression_ETR_I.Rd b/src/man/eilers_peeters_generate_regression_ETR_I.Rd index 3981037..000e9c7 100644 --- a/src/man/eilers_peeters_generate_regression_ETR_I.Rd +++ b/src/man/eilers_peeters_generate_regression_ETR_I.Rd @@ -39,7 +39,7 @@ A list containing: Fits a regression model for ETR I based on Eilers-Peeters (1988), considering photoinhibition. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#eilers_peeters_generate_regression_etr_i-and-eilers_peeters_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/eilers_peeters_generate_regression_ETR_II.Rd b/src/man/eilers_peeters_generate_regression_ETR_II.Rd index 7ebaca4..2ae78e4 100644 --- a/src/man/eilers_peeters_generate_regression_ETR_II.Rd +++ b/src/man/eilers_peeters_generate_regression_ETR_II.Rd @@ -39,7 +39,7 @@ A list containing: Fits a regression model for ETR II based on Eilers-Peeters (1988), considering photoinhibition. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#eilers_peeters_generate_regression_etr_i-and-eilers_peeters_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/platt_generate_regression_ETR_I.Rd b/src/man/platt_generate_regression_ETR_I.Rd index 8087ac7..78eacd3 100644 --- a/src/man/platt_generate_regression_ETR_I.Rd +++ b/src/man/platt_generate_regression_ETR_I.Rd @@ -41,7 +41,7 @@ A list containing: Fits the Platt (1980) regression model using original naming conventions. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#platt_generate_regression_etr_i-and-platt_generate_regression_etr_ii} . +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} . } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/platt_generate_regression_ETR_II.Rd b/src/man/platt_generate_regression_ETR_II.Rd index 32951e4..e3741be 100644 --- a/src/man/platt_generate_regression_ETR_II.Rd +++ b/src/man/platt_generate_regression_ETR_II.Rd @@ -41,7 +41,7 @@ A list containing: Fits the Platt (1980) regression model using original naming conventions. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#platt_generate_regression_etr_i-and-platt_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/plot_control.Rd b/src/man/plot_control.Rd index 6441fbe..e9bfa20 100644 --- a/src/man/plot_control.Rd +++ b/src/man/plot_control.Rd @@ -22,7 +22,7 @@ A plot displaying the original ETR and Yield values and the regression data. A t This function creates a control plot for the used model based on the provided data and model results. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#plot_control} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/read_dual_pam_data.Rd b/src/man/read_dual_pam_data.Rd index 70a36ef..03a8161 100644 --- a/src/man/read_dual_pam_data.Rd +++ b/src/man/read_dual_pam_data.Rd @@ -40,7 +40,7 @@ Reads raw CSV files generated by DualPAM software, calculates electron transport Calculates ETR using: \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I or II)} \cdot \text{Yield (I or II)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/read_dual_pam_single_channel_fluo_data.Rd b/src/man/read_dual_pam_single_channel_fluo_data.Rd index d9f6fe0..60835ab 100644 --- a/src/man/read_dual_pam_single_channel_fluo_data.Rd +++ b/src/man/read_dual_pam_single_channel_fluo_data.Rd @@ -40,7 +40,7 @@ Reads raw CSV files generated by DualPAM software, calculates electron transport Calculates ETR using: \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path( diff --git a/src/man/read_dual_pam_single_channel_p700_data.Rd b/src/man/read_dual_pam_single_channel_p700_data.Rd index be58956..bdd11cb 100644 --- a/src/man/read_dual_pam_single_channel_p700_data.Rd +++ b/src/man/read_dual_pam_single_channel_p700_data.Rd @@ -40,7 +40,7 @@ Reads raw CSV files generated by DualPAM software, calculates electron transport Calculates ETR using: \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I)} \cdot \text{Yield (I)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_dual_pam_data} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path( diff --git a/src/man/read_junior_pam_data.Rd b/src/man/read_junior_pam_data.Rd index c4d1e3d..1036f01 100644 --- a/src/man/read_junior_pam_data.Rd +++ b/src/man/read_junior_pam_data.Rd @@ -40,7 +40,7 @@ Reads raw CSV files generated by Junior PAM software, calculates electron transp Calculates ETR II using: \deqn{\text{ETR II} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path( diff --git a/src/man/read_pam_2500_data.Rd b/src/man/read_pam_2500_data.Rd index ce8e5b6..2267a8e 100644 --- a/src/man/read_pam_2500_data.Rd +++ b/src/man/read_pam_2500_data.Rd @@ -40,7 +40,7 @@ Reads raw CSV files generated by PAM 2500 software, calculates electron transpor Calculates ETR II using: \deqn{\text{ETR II} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (II)} \cdot \text{Yield (II)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata/pam_2500_data", package = "pam"), "20260422_pam_2500.CSV") diff --git a/src/man/read_universal_data.Rd b/src/man/read_universal_data.Rd index f877222..ffed5cf 100644 --- a/src/man/read_universal_data.Rd +++ b/src/man/read_universal_data.Rd @@ -39,7 +39,7 @@ Reads a standardized CSV file containing PAR and yield data for photosystem I an Calculates ETR using: \deqn{\text{ETR} = \text{PAR} \cdot \text{ETR-Factor} \cdot \text{Fraction of Photosystem (I or II)} \cdot \text{Yield (I or II)}} -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#read_universal_data} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata", package = "pam"), "universal_data", "universal_data.csv") diff --git a/src/man/vollenweider_generate_regression_ETR_I.Rd b/src/man/vollenweider_generate_regression_ETR_I.Rd index 224e1d5..1ca172e 100644 --- a/src/man/vollenweider_generate_regression_ETR_I.Rd +++ b/src/man/vollenweider_generate_regression_ETR_I.Rd @@ -44,7 +44,7 @@ A list containing: Fits the Vollenweider (1965) regression model using original naming conventions from the publication. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#vollenweider_generate_regression_etr_i-and-vollenweider_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/vollenweider_generate_regression_ETR_II.Rd b/src/man/vollenweider_generate_regression_ETR_II.Rd index c1c0bde..3bef3fb 100644 --- a/src/man/vollenweider_generate_regression_ETR_II.Rd +++ b/src/man/vollenweider_generate_regression_ETR_II.Rd @@ -44,7 +44,7 @@ A list containing: Fits the Vollenweider (1965) regression model using original naming conventions from the publication. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#vollenweider_generate_regression_etr_i-and-vollenweider_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/walsby_generate_regression_ETR_I.Rd b/src/man/walsby_generate_regression_ETR_I.Rd index 560e7af..f3ac9d1 100644 --- a/src/man/walsby_generate_regression_ETR_I.Rd +++ b/src/man/walsby_generate_regression_ETR_I.Rd @@ -37,7 +37,7 @@ Fits a modified Walsby (1997) regression model without the respiration term, usi Calculates \eqn{ETR_{max}} without accounting for photoinhibition. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_generate_regression_etr_i-and-walsby_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/walsby_generate_regression_ETR_II.Rd b/src/man/walsby_generate_regression_ETR_II.Rd index 4549376..80e4afe 100644 --- a/src/man/walsby_generate_regression_ETR_II.Rd +++ b/src/man/walsby_generate_regression_ETR_II.Rd @@ -37,7 +37,7 @@ Fits a modified Walsby (1997) regression model without the respiration term, usi Calculates \eqn{ETR_{max}} without accounting for photoinhibition. } \details{ -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#walsby_generate_regression_etr_i-and-walsby_generate_regression_etr_ii}. +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions}. } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv") diff --git a/src/man/write_model_result_csv.Rd b/src/man/write_model_result_csv.Rd index bc6a2d2..832580a 100644 --- a/src/man/write_model_result_csv.Rd +++ b/src/man/write_model_result_csv.Rd @@ -29,7 +29,7 @@ This function generates three CSV files: \item \strong{model_result.csv:} Summarizes the parameter values derived from the model results (excluding regression data), such as \code{alpha} or \code{beta}. } The `name` parameter serves as a prefix for each file, ensuring clarity and organization in the output directory. -A detailed documentation can be found under \url{https://github.com/biotoolbox/pam?tab=readme-ov-file#write_model_result_csv} +A detailed documentation can be found under \url{https://github.com/biotoolbox/pam/tree/docs#functions} } \examples{ path <- file.path(system.file("extdata/dual_pam_data", package = "pam"), "20240925.csv")