Introduction to fluorojip

Overview

fluorojip computes chlorophyll a fluorescence OJIP / JIP-test parameters from fluorescence summary data and supported exported trace tables.

The package supports workflows based on summary fluorescence inputs, Biolyzer-exported CSV trace tables, and FluorPen Excel exports. It also provides tools for validation, normalization, exploratory visualization, and an interactive Shiny interface for data analysis.

This vignette presents a basic workflow to:

1. Load fluorescence summary data
2. Compute JIP-test parameters
3. Visualize results using heatmaps and 3D plots
4. Process supported Biolyzer-exported trace tables
5. Work with FluorPen-oriented input files
6. Launch the Shiny interface

Typical workflow

A typical fluorojip analysis follows these steps:

1. Import a fluorescence summary table or a supported exported trace table
2. Convert trace data to an OJIP summary, when needed
3. Compute JIP-test parameters
4. Validate selected outputs against bundled example files
5. Visualize and export results

Example dataset

The package includes an example dataset containing typical fluorescence summary values recorded with a fluorometer.

data(example_fluorojip)
head(example_fluorojip)
#>   sample_id treatment  t_fm  area  fo   k   j   i  fm   o   p   s
#> 1        A1   control 0.345 15000 100 130 220 400 600 100 600 545
#> 2        A2   control 0.352 15350 102 132 225 405 610 102 610 552
#> 3        A3   control 0.348 14920  98 129 218 395 598  98 598 540
#> 4        A4    stress 0.390 13100 110 165 400 480 580 110 580 530
#> 5        A5    stress 0.385 12850 108 160 390 470 575 108 575 522

Computing OJIP parameters

Use calc_fluorojip() to compute the full suite of JIP-test indices. The function uses the measured K-step / 300 us fluorescence (k) to compute \(M_0\) and, from there, the RC-based fluxes and PI_abs.

res <- calc_fluorojip(example_fluorojip)
head(res)
#>   sample_id treatment  t_fm  area  fo   k   j   i  fm   o   p   s  Fv   phi_Po
#> 1        A1   control 0.345 15000 100 130 220 400 600 100 600 545 500 0.833333
#> 2        A2   control 0.352 15350 102 132 225 405 610 102 610 552 508 0.832787
#> 3        A3   control 0.348 14920  98 129 218 395 598  98 598 540 500 0.836120
#> 4        A4    stress 0.390 13100 110 165 400 480 580 110 580 530 470 0.810345
#> 5        A5    stress 0.385 12850 108 160 390 470 575 108 575 522 467 0.812174
#>      Fv_Fm       Vj       Vi       Mo       Sm        N   ABS_RC   TRo_RC
#> 1 0.833333 0.240000 0.600000 0.240000 30.00000 30.00000 1.200000 1.000000
#> 2 0.832787 0.242126 0.596457 0.236220 30.21654 29.47955 1.171500 0.975610
#> 3 0.836120 0.240000 0.594000 0.248000 29.84000 30.83467 1.235867 1.033333
#> 4 0.810345 0.617021 0.787234 0.468085 27.87234 21.14453 0.936170 0.758621
#> 5 0.812174 0.603854 0.775161 0.445396 27.51606 20.29553 0.908166 0.737589
#>     ETo_RC   DIo_RC   phi_Eo   psi_Eo ABS_CSm TRo_CSm ETo_CSm DIo_CSm    PI_abs
#> 1 0.760000 0.200000 0.633333 0.760000     600     500     380     100 13.194444
#> 2 0.739389 0.195890 0.631148 0.757874     610     508     385     102 13.306900
#> 3 0.785333 0.202533 0.635452 0.760000     598     500     380      98 13.072982
#> 4 0.290536 0.177550 0.310345 0.382979     580     470     180     110  2.832858
#> 5 0.292193 0.170577 0.321739 0.396146     575     467     185     108  3.123565
#>   Kn Kp
#> 1 NA NA
#> 2 NA NA
#> 3 NA NA
#> 4 NA NA
#> 5 NA NA

Multivariate visualization

When many parameters and treatments are involved, fluorojip provides multivariate alternatives to traditional univariate charts.

params <- c("phi_Po", "PI_abs", "ABS_RC", "DIo_RC", "ETo_CSm")

plot_param_heatmap(
  res,
  group_col = "treatment",
  params    = params,
  scale     = "zscore",
  main      = "JIP-Test Parameters Heatmap"
)

plot_3d_fluorojip(res, params = c("Fv_Fm", "PI_abs", "area"))

Biolyzer export workflow

If you have a supported Biolyzer-exported CSV trace table, you can process it and then compute JIP-test indices.

# raw  <- read_handypea_csv("path/to/biolyzer_export.csv")
# ojip <- handypea_to_ojip(raw)
# res_biolyzer <- calc_fluorojip(ojip)

Although some helper function names retain the historical handypea prefix for backward compatibility, the supported import workflow is based on Biolyzer-exported trace tables, not direct parsing of proprietary raw instrument files.

FluorPen workflow

fluorojip can also process FluorPen Excel exports after the relevant summary values are organized in the expected format.

A typical workflow is:

# fluorpen_data <- read_excel("path/to/fluorpen_export.xlsx")
# res_fluorpen  <- calc_fluorojip(fluorpen_data)

Bundled FluorPen-oriented examples can be used to check whether the computed outputs match expected JIP-test values.

Validation resources

The package includes bundled example files that can be used in validation-oriented workflows, including vendor-related examples from Biolyzer and FluorPen.

These resources are useful for checking whether calculated parameters such as PI_abs and related indices agree with expected reference outputs.

Shiny interface

For interactive analysis, fluorojip also provides a Shiny application for data import, parameter calculation, visualization, normalization, and export.

# run_fluorojip_app()

This interface is useful for exploratory analyses and for users who prefer not to work directly with scripts.

Summary

The fluorojip workflow provides a reproducible path from fluorescence summary data or supported exported trace tables to JIP-test calculation, validation, visualization, and interactive exploration.

The package is designed to support PSII performance analysis through a coherent workflow that combines parameter computation, supported import helpers, bundled validation files, and publication-oriented exploratory graphics.

References

The scientific background of the implemented OJIP / JIP-test parameters is primarily based on the following references:

Ripoll, J., Bertin, N., Bidel, L. P. R., & Urban, L. (2016). A user’s view of the parameters derived from the induction curves of maximal chlorophyll a fluorescence: Perspectives for analyzing stress. Frontiers in Plant Science, 7, Article 1679. https://doi.org/10.3389/fpls.2016.01679

Stirbet, A., & Govindjee. (2011). On the relation between the Kautsky effect (chlorophyll a fluorescence induction) and photosystem II: Basics and applications of the OJIP fluorescence transient. Journal of Photochemistry and Photobiology B: Biology, 104(1-2), 236-257. https://doi.org/10.1016/j.jphotobiol.2010.12.010

Strasser, R. J., Srivastava, A., & Govindjee. (1995). Polyphasic chlorophyll a fluorescence transient in plants and cyanobacteria. Photochemistry and Photobiology, 61(1), 32-42. https://doi.org/10.1111/j.1751-1097.1995.tb09240.x

Strasser, R. J., Tsimilli-Michael, M., & Srivastava, A. (2004). Analysis of the chlorophyll a fluorescence transient. In G. C. Papageorgiou & Govindjee (Eds.), Chlorophyll a fluorescence: A signature of photosynthesis (pp. 321-362). Springer. https://doi.org/10.1007/978-1-4020-3218-9_12

The package also builds on the R ecosystem and several supporting packages:

R Core Team. (2025). R: A language and environment for statistical computing [Computer software]. R Foundation for Statistical Computing. https://www.r-project.org/

Wickham, H., & Bryan, J. (2025). readxl: Read Excel files [Computer software]. CRAN. https://CRAN.R-project.org/package=readxl

Chang, W., Cheng, J., Allaire, J. J., Sievert, C., Schloerke, B., Aden-Buie, G., Xie, Y., Allen, J., McPherson, J., Dipert, A., & Borges, B. (2026). shiny: Web application framework for R [Computer software]. CRAN. https://CRAN.R-project.org/package=shiny

Ligges, U., Maechler, M., & Schnackenberg, S. (2026). scatterplot3d: 3D scatter plot [Computer software]. CRAN. https://CRAN.R-project.org/package=scatterplot3d

Allaire, J. J., Xie, Y., Dervieux, C., McPherson, J., Luraschi, J., Ushey, K., Atkins, A., Wickham, H., Cheng, J., Chang, W., & Iannone, R. (2025). rmarkdown: Dynamic documents for R [Computer software]. CRAN. https://CRAN.R-project.org/package=rmarkdown

Wickham, H. (2026). testthat: Unit testing for R [Computer software]. CRAN. https://CRAN.R-project.org/package=testthat

For broader perspectives on reproducibility in computational research, see:

Peng, R. D. (2011). Reproducible research in computational science. Science, 334(6060), 1226-1227. https://doi.org/10.1126/science.1213847

Sandve, G. K., Nekrutenko, A., Taylor, J., & Hovig, E. (2013). Ten simple rules for reproducible computational research. PLoS Computational Biology, 9(10), e1003285. https://doi.org/10.1371/journal.pcbi.1003285