SK-Ana: SpectroKinetic Analysis

This repository started as a fork of Pascal Pernot's ppernot/SK-Ana and is now maintained as a standalone SK-Ana repository. It was detached from the fork network because the codebase, runtime bootstrap, packaging, and deployment workflow have diverged substantially while preserving attribution to the original project.

Shiny interface for the analysis of spectrokinetic matrices:

• Singular Value Decomposition (SVD)

• Multi Curve Resolution by Alternated Least Squares (MCR-ALS)

• Hybrid hard-soft modeling (DAS, homogeneous chemistry...)

Running SK-Ana

Run locally with isolated R_skana runtime (recommended)

SK-Ana now uses a repo-local isolated runtime named R_skana. This is the safest setup on a new machine because it:

• installs its own pinned R runtime in a local environment
• keeps SK-Ana packages, cache, and sandbox isolated from any existing system or user R libraries
• avoids replacing or reconfiguring another R installation that may already exist
• leaves the machine-wide R installation untouched if one is already present

1. Get the project in one of these two ways:

   git clone workflow:

   git clone https://github.com/Saldenisov/SK-Ana.git
   cd SK-Ana

   ZIP workflow: Download the project ZIP from GitHub, unpack it, and open a terminal in the extracted SK-Ana folder.

2. Start the app directly:

   macOS / Linux:

   ./run_app.sh

   Windows:

   run_app.bat

   Windows PowerShell:

   .\run_app.ps1

   If PowerShell blocks local scripts on that machine, use:

   powershell -ExecutionPolicy Bypass -File .\run_app.ps1

   What happens automatically on first run:

   • if this is a normal git checkout, the launcher updates it from origin/master
   • if this came from a ZIP without .git, the launcher initializes git in that extracted folder and then updates it from origin/master
   • if Git is missing, the launcher tries to install or bootstrap Git first
   • the launcher then creates the isolated R_skana runtime and installs required R packages
   • finally, it starts the app

   This means a user can either clone the repo or download the ZIP, unpack it, and just run run_app.

3. If you want to preinstall or refresh the runtime without launching the app, run:

   macOS / Linux:

   ./scripts/setup_r_skana.sh

   Windows:

   scripts\setup_r_skana.bat

   On restricted Windows machines, this still runs fully in user space and does not need administrator rights. If outbound downloads are blocked by IT, place a pre-approved micromamba.exe at scripts\vendor\windows\micromamba.exe or set SK_ANA_MICROMAMBA_EXE to its path before running the script.

4. The app will open automatically in your browser, or go to:

   • http://localhost:3838 (default Shiny port)
   • http://localhost:3840 (default for run_app.sh / run_app.bat)
   • if port 3840 is already busy, SK-Ana will try to reuse it by stopping a previous R-based SK-Ana process, or fall back to 3841, 3842, and so on

The isolated runtime setup installs:

• local micromamba
• environment R_skana
• pinned base R 4.3.3 (R 4.2+ supported target)
• repo-local renv library, cache, and sandbox under .R_skana/
• core app and test packages from conda-forge where available
• any remaining SK-Ana packages from R package sources inside the isolated runtime

Windows without admin rights

For lab or enterprise Windows machines where users do not have administrator privileges:

• scripts\setup_r_skana.bat installs everything under the project folder
• it does not write into Program Files or require a system-wide R installation
• it can use a local pre-approved micromamba.exe instead of downloading one

Example with a pre-staged executable:

set SK_ANA_MICROMAMBA_EXE=Z:\approved-tools\micromamba.exe
scripts\setup_r_skana.bat
run_app.bat

This is the recommended non-Docker path for locked-down Windows environments.

Use R_skana directly

Open an R console inside the isolated runtime:

macOS / Linux:

./R_skana.sh

Windows:

R_skana.bat

Run one-off commands in the same isolated runtime:

macOS / Linux:

./R_skana.sh Rscript tests/testthat.R

Windows:

R_skana.bat Rscript tests\testthat.R

Optional host/port override for app launch:

macOS / Linux:

SK_ANA_HOST=127.0.0.1 PORT=3842 ./run_app.sh

Windows:

set SK_ANA_HOST=127.0.0.1
set PORT=3842
run_app.bat

Windows PowerShell:

$env:SK_ANA_HOST = "127.0.0.1"
$env:PORT = "3842"
.\run_app.ps1

Refresh the lockfile (maintainers)

After changing package requirements, refresh the lockfile from inside the isolated runtime so renv.lock matches R_skana:

macOS / Linux:

./R_skana.sh Rscript scripts/relock_r_skana.R

Windows:

R_skana.bat Rscript scripts\relock_r_skana.R

User's manual

New: online here

---

What is SK-Ana?

SK-Ana (Spectro-Kinetic Analysis) is an R + Shiny application for analyzing time-resolved spectroscopic datasets (e.g., pulse radiolysis, transient absorption, pump–probe). Such experiments produce 2D matrices where one axis is time (kinetics) and the other is wavelength (spectra). The goal is to recover the spectra of transient species and their kinetic profiles, and optionally fit a mechanistic reaction model.

Data model

A measured dataset D(t, λ) is modeled as a sum of species spectra and time-dependent concentrations plus noise:

D(t_i, λ_j) ≈ Σ_k C_k(t_i) · S_k(λ_j) + ε(t_i, λ_j)

where C_k(t) are kinetic profiles (concentrations vs time), S_k(λ) are species spectra, and ε is noise.

---

Core capabilities

1) Singular Value Decomposition (SVD)

• Estimates the number of significant components above noise.
• Denoises by reconstructing the dataset from significant singular values.

2) Non-Negative Matrix Factorization (NNMF)

• Factorizes D ≈ C · Sᵀ with non-negativity on spectra and concentrations.
• Optional constraints (smoothness, sparsity, unimodality) can be applied.
• Subject to rotational/scaling ambiguity (multiple valid solutions may exist).

3) MCR-ALS (Multi-Curve Resolution – Alternating Least Squares)

• Alternates between solving for C and S under chosen constraints:
  • positivity (spectra, concentrations)
  • mass/stoichiometry conservation
  • known spectral shapes or fixed regions
  • time masks or kinetic restrictions
• Provides uncertainty/interval estimates for spectra/kinetics.

4) Hybrid Hard–Soft Modeling (HH-SM)

• Couples empirical data fitting with mechanistic kinetic models (ODEs).
• Optimizes non-linear rate constants (k) and linear spectral coefficients jointly.
• Supports Decay-Associated Spectra (DAS) and full target-mechanism fitting.

5) Global analysis across conditions

• Fits multiple datasets simultaneously (e.g., different concentrations, solvents, windows) with shared spectra and condition-dependent kinetics.
• Enables cross-validation and robust parameter estimation.

6) Ambiguity and error analysis

• Explores solution-space ambiguity (T-transform invariances for D = C · Sᵀ).
• Quantifies confidence bounds on spectra/kinetics and assesses identifiability.

---

Typical workflow

1. Import a spectro-kinetic matrix (time × wavelength).
2. Run SVD to estimate component count and denoise (optional).
3. Initialize and run MCR-ALS with constraints to extract C and S.
4. If applicable, define a kinetic scheme and switch to HH-SM to fit rate constants and refine spectra globally.
5. Inspect residuals, confidence intervals, and ambiguity diagnostics.
6. Export spectra, kinetics, fitted parameters, and reconstructed datasets.

---

Typical use cases

• Pulse radiolysis studies (solvated electrons, radical chemistry).
• Femtosecond–microsecond pump–probe transient absorption.
• Photochemical intermediates and reaction-mechanism elucidation.
• Polymerization and redox kinetics; comparison with TD‑DFT/ab‑initio spectra.

---

Technical notes

• Interactive GUI built with R/Shiny; runs locally or in Docker.
• Compatible with isolated R_skana runtime using pinned R 4.3.3 and repo-local package isolation
• Removed dependency on inlmisc; includes local GetColors implementation
• Includes helper scripts in scripts/ directory for easy local deployment
• Recommended Docker deployment (see container section below):
  • docker run -d -p 3840:3840 --name skana saldenisov/skana:latest
  • Access via http://localhost:3840
• Integrates visualization, matrix factorization, and model fitting in one app.

Project Structure

SK-Ana/
├── Readme.md                    # This file
├── app.R                        # Shiny app entry point
├── ui.R, server.R, global.R     # Main application files
├── error_handler.R              # Error handling
├── Dockerfile, Dockerfile.arm64 # Docker build files
├── ui_files/                    # UI components
├── server_files/                # Server logic
├── data/                        # Example datasets
├── scripts/                     # Utility scripts for runtime/bootstrap and launch
├── tests/                       # Test files
├── docs/                        # Documentation
│   ├── deployment/              # Docker, CI/CD docs
│   └── development/             # Technical docs
├── .github/workflows/           # CI/CD automation
└── renv/                        # R package management

---

Related software

• MCR‑ALS (MATLAB GUI): SVD, MCR‑ALS, hybrid, ambiguity analysis.
• GloTarAn (R + Java): Global/target analysis (SVD, DAS).
• SK‑Ana (R + Shiny): SVD, MCR‑ALS, hybrid modeling, ambiguity exploration.

---

In summary

SK‑Ana provides a unified workflow to deconvolve, model, and interpret time‑resolved spectro‑kinetic data using both data‑driven and mechanistic approaches—bridging experiment, analysis, and simulation for robust mechanistic insight.

Docker container

For cross-platform compatibility, the preferred installation method is through a Docker container. SK-Ana provides multi-platform Docker images that automatically work on Windows, Linux, Intel Mac, and Apple Silicon Mac.

🔄 Automated Builds: Docker images are automatically built and published via GitHub Actions when new code is pushed. Both amd64 and arm64 architectures are built simultaneously and combined into a single multi-platform image.

Prerequisites

0. Install Docker Desktop
   • Windows: Docker Desktop for Windows
   • Mac: Docker Desktop for Mac (supports both Intel and Apple Silicon)
   • Linux: Docker Engine or Docker Desktop

Option 1: Pull Pre-built Image (Recommended)

The saldenisov/skana Docker image includes all latest fixes and R 4.4.1 compatibility.

All Platforms (Recommended - Multi-Architecture Image):

The latest tag is a multi-platform image that automatically selects the correct architecture:

docker run -d -p 3840:3840 --name skana saldenisov/skana:latest

Automatically works on:

• ✅ Windows (amd64)
• ✅ Linux (amd64)
• ✅ Mac Intel (amd64)
• ✅ Mac Apple Silicon (arm64) - No platform warnings!

Access at: http://localhost:3840

Platform-Specific Images (Optional):

If you want to explicitly specify the architecture:

For Windows/Linux/Intel Mac (amd64):

docker run -d -p 3840:3840 --name skana saldenisov/skana:latest-amd64

For Mac Apple Silicon (arm64):

docker run -d -p 3840:3840 --name skana saldenisov/skana:latest-arm64

Container Management

Stop container:

docker stop skana

Restart container:

docker restart skana

Remove container:

docker stop skana
docker rm skana

Update to latest version:

docker pull saldenisov/skana:latest
docker stop skana
docker rm skana
docker run -d -p 3840:3840 --name skana saldenisov/skana:latest

Option 2: Build from Source

For Mac Apple Silicon users or users who want to customize the image:

Mac Apple Silicon (arm64) - Native Build:

1. Clone or download this repository
2. Navigate to the SK-Ana directory
3. Build the arm64-optimized image:

cd /path/to/SK-Ana
docker build --platform linux/arm64 -f Dockerfile.arm64 -t skana:arm64 .

4. Run the native arm64 container:

docker run -d -p 3840:3840 -e PORT=3840 --name skana skana:arm64

Benefits of native arm64 build:

• No emulation overhead
• Better performance
• No platform mismatch warnings

Windows/Linux/Intel Mac - Standard Build:

cd /path/to/SK-Ana
docker build -t skana:latest .
docker run -d -p 3840:3840 -e PORT=3840 --name skana skana:latest

Available Images

Image Tag	Architectures	Base Image	Use Case
latest	amd64, arm64	Multi-platform	Recommended - Auto-selects architecture
latest-amd64	amd64 only	rocker/shiny:4.4.1	Windows, Linux, Intel Mac
latest-arm64	arm64 only	r-base:4.4.1	Mac Apple Silicon (M1/M2/M3)

Note: The latest tag automatically selects the correct architecture for your system. No need to specify platform explicitly!

Available Dockerfiles (For Building from Source)

Dockerfile	Platform	Base Image	Use Case
Dockerfile	amd64 (x86_64)	rocker/shiny:4.4.1	Windows, Linux, Intel Mac
Dockerfile.arm64	arm64	r-base:4.4.1	Mac Apple Silicon (M1/M2/M3)

Option 3: Original Docker Image

The original ppernot1/skana Docker container (amd64 only):

docker run -d -p 3840:3840 --name skana-original ppernot1/skana

Access at: http://localhost:3840

Note: The updated saldenisov/skana image includes bug fixes and is recommended for new deployments.

Troubleshooting

Platform warning on Mac: If you see:

WARNING: The requested image's platform (linux/amd64) does not match the detected host platform (linux/arm64/v8)

You have two options:

1. Continue using emulation (works fine, slightly slower)
2. Build native arm64 image using Dockerfile.arm64 (see "Build from Source" section)

Port already in use:

# Use a different port
docker run -d -p 3841:3840 --name skana saldenisov/skana:latest
# Access at http://localhost:3841

Container won't start:

# Check logs
docker logs skana

# Restart Docker Desktop and try again

For detailed Docker documentation, see:

• docs/deployment/DOCKER_PLATFORM_GUIDE.md - Platform-specific quick reference (recommended starting point)
• DOCKER.md - Complete Docker deployment guide
• README_DOCKER.md - Cross-platform Docker instructions
• docs/deployment/ - All deployment documentation

How to cite SK-Ana

If you use SK-Ana in one of your publications, do not forget to cite it and include the version you used for reproducibility:

Pernot, P. (2018) SK-Ana: Analysis of Spectro-Kinetic Data (Version X.X).
https://doi.org/10.5281/zenodo.1064370

References

Methods

• C. Ruckebusch, M. Sliwa, P. Pernot, A. d. Juan, R. Tauler (2012) "Comprehensive data analysis of femtosecond transient absorption spectra: A review", J. Photochem. Photobiol. C 13:1–27. DOI

Tutorial (in french)

• Apport de la simulation à la détermination de mécanismes réactionnels en chimie sous rayonnement. Action Nationale de Formation CNRS "Chimie sous Rayonnement et Radiochimie" (Oléron, 2017/09) PDF

Works using SK-Ana (please let me know of any missing reference)

• D.H. Cruz Neto, J. Soto, N. Maity, Ch. Lefumeux, T. Nguyen, P. Pernot, K. Steenkeste, D. Peláez, M.-H. Ha-Thi and Th. Pino (2023) J. Phys. Chem. Letters 14:4789–4795. (https://doi.org/10.1021/acs.jpclett.3c00594)

• M. Knezevic, V.-D. Quach, I. Lampre, M. Erard, P. Pernot, D. Berardan, Ch. Colbeau-Justin and M.N. Ghazzal (2023) J. Mater. Chem. A 11:6226-6236. (https://doi.org/10.1039/D2TA09920A)

• K. Iwamatsu, R. Gakhar, Ph. Halstenberg, B. Layne, S.M. Pimblott and J.F. Wishart (2022) Phys. Chem. Chem. Phys. 24:25088-25098. (https://doi.org/10.1039/D2CP01194H)

• C. Shang and P.E. Reiller (2021) Dalton Trans. 50:17165-17180. (https://doi.org/10.1039/D1DT03204F)

• M. Puget, V. Shcherbakov, S. Denisov, P. Moreau, J.-P. Dognon, M. Mostafavi and S. Le Caër (2021) Chem. Eur. J. 27:8185. (https://doi.org/10.1002/chem.202100562)

• R. Kaczmarek, S. Ward, D. Debnath, T. Jacobs, A. D. Stark, D. Korczyński, A. Kumar, M. D. Sevilla, S. A. Denisov, V. Shcherbakov, P. Pernot, M. Mostafavi, R. Dembinski and A. Adhikary (2020) Chemistry – A European Journal 26:9495–9505. (http://dx.doi.org/10.1002/chem.202000247)

• S. Al Gharib, J.-L. Marignier, A.K. El Omar, A. Naja, S. Le Caer, M. Mostafavi and J. Belloni (2019) J. Phys. Chem. C 123:22624-22633. (http://dx.doi.org/10.1021/acs.jpcc.9b06090)

• F. Wang, P. Pernot, J.-L. Marignier, P. Archirel and M. Mostafavi (2019) J. Phys. Chem. B _123, 2019, pp. __:6599-6608. (http://dx.doi.org/10.1021/acs.jpcb.9b05560)

• F. Wang, G.P. Horne, P. Pernot, P. Archirel and M. Mostafavi (2018) J. Phys. Chem. B _122, 2018, pp. __:7134-7142. (http://dx.doi.org/10.1021/acs.jpcb.8b03715)

• J. Ma, A. Kumar, Y. Muroya, S. Yamashita, T. Sakurai, S.A. Denisov, M.D. Sevilla, A. Adhikary, S. Seki and M. Mostafavi (2019) Nat. Commun. 10:102. (https://doi.org/10.1038/s41467-018-08005-z)

• J. Ma, S. A. Denisov, J. Marignier, P. Pernot, A. Adhikary, S. Seki and M. Mostafavi (2018) J. Phys. Chem. Lett. 9:5105-5109. (http://dx.doi.org/10.1021/acs.jpclett.8b02170)

• J. Ma, J. Marignier, P. Pernot, C. Houée-Levin, A. Kumar, M. D. Sevilla, A. Adhikary and M. Mostafavi (2018) Phys. Chem. Chem. Phys. 20:14927-14937. (http://dx.doi.org/10.1039/C8CP00352A)

• J. Ma, P. Archirel, P. Pernot, U. Schmidhammer, S. L. Caër and M. Mostafavi (2016) J. Phys. Chem. B 120:773–784. (http://dx.doi.org/10.1021/acs.jpcb.5b11315)

• J. Ma, P. Archirel, U. Schmidhammer, J. Teuler, P. Pernot and M. Mostafavi (2013) J. Phys. Chem. A 117:14048–14055. (http://dx.doi.org/10.1021/jp410598y)