# 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

### Key parameters calculated

Yields - `phi_Po` (\(F_v/F_m\)) - `psi_Eo` - `phi_Eo`

Fluxes per reaction center (RC) - `ABS_RC` - `TRo_RC` - `ETo_RC` - `DIo_RC`

Fluxes per cross section (CS) - `ABS_CSm` - `TRo_CSm` - `ETo_CSm` - `DIo_CSm`

Performance - `PI_abs` (Performance Index, PI(Abs))

## Multivariate visualization

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

### Heatmaps

Heatmaps allow simultaneous visualization of patterns across parameters and treatments. Data can be scaled to make variables with different units comparable.

    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"
    )

### 3D plots

3D plots help visualize the overall multivariate structure of the data, highlighting treatments associated with stronger effects on PSII performance.

    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