| Title: | Analysis of Chlorophyll a Fluorescence Transient Parameters |
|---|---|
| Description: | Computes chlorophyll a fluorescence transient parameters from fluorescence summary data, including minimum and maximum fluorescence, selected transient steps, and area. Provides standard photosynthetic performance indices and fluxes per reaction center and per cross section. Includes helpers to read exported trace tables in supported 'csv' formats and validation workflows based on bundled example files, as well as visualization tools and an interactive 'shiny' interface. The implemented calculations are based on Strasser et al. (2004) <doi:10.1007/978-1-4020-3218-9_12> and Stirbet and Govindjee (2011) <doi:10.1016/j.jphotobiol.2010.12.010>. |
| Authors: | Joao Everthon da Silva Ribeiro [aut, cre], Toshik Iarley da Silva [aut], Ronald Maldonado Rodriguez [aut] |
| Maintainer: | Joao Everthon da Silva Ribeiro <[email protected]> |
| License: | GPL-3 |
| Version: | 0.1.1 |
| Built: | 2026-05-09 08:25:47 UTC |
| Source: | https://github.com/cran/fluorojip |
Computes chlorophyll a fluorescence OJIP / JIP-test parameters from fluorescence summary data.
calc_fluorojip(df)calc_fluorojip(df)
df |
A data frame containing fluorescence summary columns. At minimum,
provide Fo ( |
The current implementation follows a summary-input workflow. Primary terms
such as phi_Po, Vj, Vi, psi_Eo, phi_Eo, Mo, and PI_abs are
computed explicitly from the supplied fluorescence summary values.
Mo is derived from the K-step / F300 region using the standard relation
4 * (F300 - Fo) / (Fm - Fo). If a K-step / 300 us-equivalent value is not
available, the function does not attempt to guess Mo; instead, Mo, N,
RC-based fluxes, and PI_abs are returned as NA with a warning.
The cross-section outputs ABS_CSm, TRo_CSm, ETo_CSm, and DIo_CSm
are returned as operational package outputs for internal comparison. They are
computed consistently from the supplied summary data, but they should be
described carefully if compared against instrument-specific phenomenological
flux conventions.
A data frame containing the original input columns plus calculated FluorOJIP / JIP-test parameters.
df <- data.frame( sample_id = c("S1", "S2"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) res <- calc_fluorojip(df) res[, c("sample_id", "Fv_Fm", "PI_abs")]df <- data.frame( sample_id = c("S1", "S2"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) res <- calc_fluorojip(df) res[, c("sample_id", "Fv_Fm", "PI_abs")]
Read a summary table and compute FluorOJIP parameters
calc_fluorojip_file(file, sep = ";", dec = ".", ...)calc_fluorojip_file(file, sep = ";", dec = ".", ...)
file |
Path to the input summary table. |
sep |
Field separator used in the input file. Defaults to |
dec |
Decimal mark used in the input file. Defaults to |
... |
Additional arguments passed to |
This is a convenience wrapper for summary-input workflows:
read.csv(file, ...) -> calc_fluorojip(df).
A data frame containing the original input columns plus calculated FluorOJIP / JIP-test parameters.
df <- data.frame( sample_id = c("S1", "S2"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) f <- tempfile(fileext = ".csv") utils::write.csv(df, f, row.names = FALSE) res <- calc_fluorojip_file(f, sep = ",") res[, c("sample_id", "Fv_Fm", "PI_abs")]df <- data.frame( sample_id = c("S1", "S2"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) f <- tempfile(fileext = ".csv") utils::write.csv(df, f, row.names = FALSE) res <- calc_fluorojip_file(f, sep = ",") res[, c("sample_id", "Fv_Fm", "PI_abs")]
Calculate FluorOJIP parameters from a FluorPen workbook
calc_fluorojip_fluorpen(file, sheet = 1)calc_fluorojip_fluorpen(file, sheet = 1)
file |
Path to the FluorPen |
sheet |
Sheet name or numeric index. Defaults to the first sheet. |
This is a convenience wrapper for the typical FluorPen workflow:
read_fluorpen_xlsx(file) -> fluorpen_to_ojip(raw) -> calc_fluorojip(ojip).
Use this function when you want to import a supported FluorPen workbook and compute JIP-test parameters in one step.
A data frame with FluorOJIP / JIP-test parameters calculated from the imported workbook.
xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { res <- calc_fluorojip_fluorpen(xlsx) head(res[c("sample_id", "Fv_Fm")]) }xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { res <- calc_fluorojip_fluorpen(xlsx) head(res[c("sample_id", "Fv_Fm")]) }
Reads a supported exported trace table, derives an OJIP summary, and then computes FluorOJIP parameters.
calc_fluorojip_handypea(file)calc_fluorojip_handypea(file)
file |
Path to the supported Biolyzer-exported CSV trace table. |
Although the function name retains the historical handypea prefix for
backward compatibility, the supported import workflow is based on
Biolyzer-exported trace tables.
Typical workflow:read_handypea_csv() -> handypea_to_ojip() -> calc_fluorojip().
A data frame with FluorOJIP parameters returned by
calc_fluorojip().
txt <- c( '"Record No",0.00002,0.00027,0.002,0.03,0.10', '"S1",280,340,700,950,1200', '"S2",300,360,730,980,1250' ) f <- tempfile(fileext = ".csv") writeLines(txt, f) res <- calc_fluorojip_handypea(f) res[, c("sample_id", "Fv_Fm", "PI_abs")]txt <- c( '"Record No",0.00002,0.00027,0.002,0.03,0.10', '"S1",280,340,700,950,1200', '"S2",300,360,730,980,1250' ) f <- tempfile(fileext = ".csv") writeLines(txt, f) res <- calc_fluorojip_handypea(f) res[, c("sample_id", "Fv_Fm", "PI_abs")]
A dataset containing fluorescence summary values used to demonstrate the calculation of FluorOJIP / JIP-test parameters.
data(example_fluorojip)data(example_fluorojip)
A data frame with columns for sample identification, treatment groups, and fluorescence summary values used in JIP-test calculations.
The data are organized in the format expected by calc_fluorojip(),
including sample identifiers, treatment groups, and summary fluorescence
variables such as fo, fm, j, i, area,
and, when available, k.
data(example_fluorojip) head(example_fluorojip)data(example_fluorojip) head(example_fluorojip)
Returns the full path to the example Biolyzer workbook distributed with
the package in inst/extdata. This file can be used in
validation-oriented workflows that compare FluorOJIP outputs against
vendor-calculated JIP-test parameters.
fluorojip_example_biolyzer_file()fluorojip_example_biolyzer_file()
The bundled workbook is intended as a reproducible validation resource for supported Biolyzer-based workflows.
A length-1 character vector containing the normalized full file path.
x <- fluorojip_example_biolyzer_file() file.exists(x) basename(x)x <- fluorojip_example_biolyzer_file() file.exists(x) basename(x)
Convert FluorPen traces to an OJIP summary table
fluorpen_to_ojip(x)fluorpen_to_ojip(x)
x |
A list returned by |
This helper converts the FluorPen trace matrix into the fluorescence summary structure expected by the core calculation workflow, including the O, K, J, I, P, and area-related quantities extracted from the trace.
A typical workflow is:
read_fluorpen_xlsx(file) -> fluorpen_to_ojip(raw) -> calc_fluorojip(ojip).
A data frame containing one row per sample with OJIP summary values
ready for calc_fluorojip().
xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { raw <- read_fluorpen_xlsx(xlsx) ojip <- fluorpen_to_ojip(raw) head(ojip) }xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { raw <- read_fluorpen_xlsx(xlsx) ojip <- fluorpen_to_ojip(raw) head(ojip) }
Converts a supported exported trace table into an OJIP summary table ready for downstream FluorOJIP parameter calculation.
handypea_to_ojip(x)handypea_to_ojip(x)
x |
A list object returned by |
Although the function name retains the historical handypea prefix for
backward compatibility, the supported import workflow is based on
Biolyzer-exported trace tables.
Time values are normalized internally to milliseconds so the function can target the standard OJIP steps even when exported trace times are recorded in seconds, milliseconds, or microseconds.
A data frame containing sample_id, t_fm, fo, k, fm, j,
i, p, and area.
raw <- list( times_s = c(0.00002, 0.00027, 0.002, 0.03, 0.10), mat = matrix( c( 280, 340, 700, 950, 1200, 300, 360, 730, 980, 1250 ), nrow = 2, byrow = TRUE, dimnames = list(c("S1", "S2"), NULL) ) ) ojip <- handypea_to_ojip(raw) ojipraw <- list( times_s = c(0.00002, 0.00027, 0.002, 0.03, 0.10), mat = matrix( c( 280, 340, 700, 950, 1200, 300, 360, 730, 980, 1250 ), nrow = 2, byrow = TRUE, dimnames = list(c("S1", "S2"), NULL) ) ) ojip <- handypea_to_ojip(raw) ojip
Creates a wide or long table of FluorOJIP / JIP-test parameters for each sample, with optional normalization for exploratory analysis, comparison across treatments, and export.
normalized_jiptable( df, params = NULL, sample_col = "sample_id", group_col = "treatment", normalize = c("none", "zscore", "minmax", "control_ratio", "control_then_zscore"), control_level = NULL, output = c("wide", "long"), digits = 6 )normalized_jiptable( df, params = NULL, sample_col = "sample_id", group_col = "treatment", normalize = c("none", "zscore", "minmax", "control_ratio", "control_then_zscore"), control_level = NULL, output = c("wide", "long"), digits = 6 )
df |
A data frame, typically the output of |
params |
Character vector of parameter names to include. If |
sample_col |
Name of the sample identifier column. |
group_col |
Name of the grouping column, typically a treatment column. |
normalize |
Normalization method. One of |
control_level |
Level of |
output |
Output format: |
digits |
Number of decimal places used to round normalized parameter columns. |
This function is intended for exploratory analysis and reporting workflows in which selected FluorOJIP / JIP-test parameters need to be compared across samples or treatments on a common scale.
Parameters such as PI_abs, Mo, and RC-based fluxes depend on
the availability of a K-step / 300 us-equivalent input (for example,
k or f300us) in the original summary data used by
calc_fluorojip().
Cross-section outputs such as ABS_CSm, TRo_CSm,
ETo_CSm, and DIo_CSm are package outputs intended for
operational comparison workflows and may not fully match every
instrument-specific convention.
A data frame in wide or long format containing the selected JIP-test parameters after the requested normalization step.
df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) tab_wide <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), normalize = "zscore", output = "wide" ) tab_wide tab_long <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs"), normalize = "control_ratio", control_level = "control", output = "long" ) head(tab_long)df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) tab_wide <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), normalize = "zscore", output = "wide" ) tab_wide tab_long <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs"), normalize = "control_ratio", control_level = "control", output = "long" ) head(tab_long)
Creates an exploratory 3D scatter plot for exactly three selected FluorOJIP / JIP-test parameters.
plot_3d_fluorojip( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE ) plot_param_3d( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE ) plot_param_surface3d( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE )plot_3d_fluorojip( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE ) plot_param_3d( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE ) plot_param_surface3d( res, params = c("Fv_Fm", "PI_abs", "area"), group_col = "treatment", normalize = TRUE )
res |
Data frame with OJIP / JIP-test results. |
params |
Character vector of exactly 3 parameters to plot. |
group_col |
Name of the column with treatment or grouping labels. |
normalize |
Logical indicating whether selected parameters should be z-score normalized before plotting. |
plot_param_3d() and plot_param_surface3d() are aliases of
plot_3d_fluorojip(). The name plot_param_surface3d() is retained for
backward compatibility, although the function produces a 3D scatter plot
rather than an interpolated surface.
Invisibly returns the object produced by
scatterplot3d::scatterplot3d().
if (requireNamespace("scatterplot3d", quietly = TRUE)) { df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) plot_3d_fluorojip( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), group_col = "treatment", normalize = TRUE ) }if (requireNamespace("scatterplot3d", quietly = TRUE)) { df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) plot_3d_fluorojip( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), group_col = "treatment", normalize = TRUE ) }
Creates a heatmap for selected FluorOJIP / JIP-test parameters across samples, with optional normalization.
plot_heatmap_fluorojip( res, params, sample_col = "sample_id", group_col = "treatment", scale = "zscore", main = "Normalized JIP-test parameter heatmap" ) plot_param_heatmap( res, params, sample_col = "sample_id", group_col = "treatment", scale = "zscore", main = "Normalized JIP-test parameter heatmap" )plot_heatmap_fluorojip( res, params, sample_col = "sample_id", group_col = "treatment", scale = "zscore", main = "Normalized JIP-test parameter heatmap" ) plot_param_heatmap( res, params, sample_col = "sample_id", group_col = "treatment", scale = "zscore", main = "Normalized JIP-test parameter heatmap" )
res |
Data frame with OJIP / JIP-test results. |
params |
Character vector of parameters to plot. |
sample_col |
Name of the column with sample IDs. |
group_col |
Name of the column with treatment or grouping labels. |
scale |
Normalization method. Supported values are |
main |
Title of the plot. |
Invisibly returns the object produced by stats::heatmap().
df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) plot_heatmap_fluorojip( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), group_col = "treatment", scale = "zscore" )df <- data.frame( sample_id = c("S1", "S2", "S3"), treatment = c("control", "stress", "stress"), fo = c(280, 300, 295), fm = c(1200, 1250, 1230), j = c(700, 730, 720), i = c(950, 980, 970), k = c(340, 360, 350), area = c(32000, 35000, 34000) ) res <- calc_fluorojip(df) plot_heatmap_fluorojip( res, params = c("Fv_Fm", "PI_abs", "ABS_RC"), group_col = "treatment", scale = "zscore" )
Reads a FluorPen .xlsx workbook exported in a wide vendor layout, where
columns represent measurements, the first column stores the OJIP time grid,
and footer rows contain vendor-calculated JIP-test parameters.
read_fluorpen_xlsx(file, sheet = 1)read_fluorpen_xlsx(file, sheet = 1)
file |
Path to the FluorPen |
sheet |
Sheet name or numeric index. Defaults to the first sheet. |
This function reads a supported FluorPen workbook and prepares its trace and footer summary data for downstream OJIP conversion, validation, and comparison workflows.
A typical workflow is:
read_fluorpen_xlsx(file) -> fluorpen_to_ojip(raw) -> calc_fluorojip(ojip).
A list with metadata, the raw trace matrix, and the vendor summary:
sample_id measurement identifiers taken from the header row
measurement_time acquisition timestamps
protocol_id protocol labels such as OJIP
times_us raw time grid in microseconds
times_ms raw time grid converted to milliseconds
mat numeric matrix with one row per sample and one column per time
summary_raw footer summary as imported from the workbook
summary_numeric footer summary converted to numeric values where possible
xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { raw <- read_fluorpen_xlsx(xlsx) names(raw) dim(raw$mat) }xlsx <- system.file("extdata", "FluorPen_test.xlsx", package = "fluorojip") if (nzchar(xlsx)) { raw <- read_fluorpen_xlsx(xlsx) names(raw) dim(raw$mat) }
Reads a CSV trace table exported by Biolyzer and prepares it for downstream OJIP summary extraction.
read_handypea_csv(file)read_handypea_csv(file)
file |
Path to the supported Biolyzer-exported CSV trace table. |
Although the function name retains the historical handypea prefix for
backward compatibility, this workflow is based on supported exported trace
tables rather than direct parsing of proprietary raw instrument files.
The function locates the trace header, extracts the time values,
reads the numeric trace block, removes trailing non-data rows, and returns
the result in a format suitable for handypea_to_ojip().
A list with three elements: times_s, the extracted time points;
ids, the trace identifiers; and mat, a numeric matrix containing the
fluorescence traces.
txt <- c( '"Record No",0.00002,0.00027,0.002,0.03,0.10', '"S1",280,340,700,950,1200', '"S2",300,360,730,980,1250' ) f <- tempfile(fileext = ".csv") writeLines(txt, f) raw <- read_handypea_csv(f) raw$times_s dim(raw$mat)txt <- c( '"Record No",0.00002,0.00027,0.002,0.03,0.10', '"S1",280,340,700,950,1200', '"S2",300,360,730,980,1250' ) f <- tempfile(fileext = ".csv") writeLines(txt, f) raw <- read_handypea_csv(f) raw$times_s dim(raw$mat)
Launches the bundled Shiny interface for interactive FluorOJIP / JIP-test workflows, including data import, parameter calculation, validation, visualization, normalization, and export.
run_fluorojip_app(...)run_fluorojip_app(...)
... |
Additional arguments passed to |
The bundled Shiny application provides an interactive environment for working with fluorescence summary inputs and supported import workflows. Depending on the installed app version, available features may include OJIP curve inspection, parameter selection, normalized 2D plots, heatmaps, 3D plots, validation tabs, export tools, and built-in help content.
This function starts the application distributed with the package and passes
any additional arguments directly to shiny::runApp().
This function is called for its side effect of launching the bundled Shiny application.
app_dir <- system.file("shiny", "fluorojip-app", package = "fluorojip") dir.exists(app_dir) if (interactive()) { run_fluorojip_app() }app_dir <- system.file("shiny", "fluorojip-app", package = "fluorojip") dir.exists(app_dir) if (interactive()) { run_fluorojip_app() }
Exports a normalized FluorOJIP / JIP-test parameter table to disk for use in spreadsheet software or downstream statistical workflows.
write_normalized_jiptable(df, file, ...)write_normalized_jiptable(df, file, ...)
df |
A data frame to export, typically generated by
|
file |
Path to the output file. |
... |
Additional arguments passed to |
The table is written with a semicolon field separator (sep = ";")
and decimal point (dec = "."). This behavior is intentional and may
be convenient for spreadsheet workflows, but it differs from the default
behavior of write.csv().
This function is called for its side effect of writing a file to disk. It invisibly returns the output path.
df <- data.frame( sample_id = c("S1", "S2"), treatment = c("control", "stress"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) res <- calc_fluorojip(df) tab <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs"), output = "wide" ) f <- tempfile(fileext = ".csv") write_normalized_jiptable(tab, f) file.exists(f)df <- data.frame( sample_id = c("S1", "S2"), treatment = c("control", "stress"), fo = c(280, 300), fm = c(1200, 1250), j = c(700, 730), i = c(950, 980), k = c(340, 360), area = c(32000, 35000) ) res <- calc_fluorojip(df) tab <- normalized_jiptable( res, params = c("Fv_Fm", "PI_abs"), output = "wide" ) f <- tempfile(fileext = ".csv") write_normalized_jiptable(tab, f) file.exists(f)