Type:	Package
Title:	Design Complex Light Regimes
Version:	1.0.0
Description:	A system for accurately designing complex light regimes using LEDs. Takes calibration data and user-defined target irradiances and it tells you what intensities to use. For more details see Vong et al. (2025) <doi:10.1101/2025.06.06.658293>.
License:	GPL (≥ 3)
Encoding:	UTF-8
URL:	https://github.com/ginavong/LightFitR/
BugReports:	https://github.com/ginavong/LightFitR/issues
LazyData:	true
Depends:	R (≥ 3.5)
Imports:	utils, graphics, lubridate, nnls, stringr
RoxygenNote:	7.3.2
Suggests:	knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition:	3
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2025-07-24 15:27:11 UTC; Gina Vong
Author:	Gina Vong [aut, cre, cph]
Maintainer:	Gina Vong <gywv500@york.ac.uk>
Repository:	CRAN
Date/Publication:	2025-07-25 16:30:14 UTC

calibration data

Description

Example calibration data

Usage

calibration

Format

A data frame with 12 columns:

filename

File that the raw data came from

time

The time when a given measurement was taken

led

LED channel being calibrated at that timepoint

intensity

Intensity the light is set to

wavelength

The wavelength this row describes

irradiance

The irradiance measured at that wavelength by the spectrometer

Source

<https://github.com/ginavong/2024_LightFitR_MethodsPaper/blob/master/data/heliospectra_measurements/calibration/Apollo_Calib_20240827/Apollo_calibration_annotated_20240827.Rda>

Check that the intended irradiances are acheivable by the lights

Description

Check that the intended irradiances are acheivable by the lights

Usage

checkRange(
  intended_irradiance,
  calibration_leds,
  calibration_wavelengths,
  calibration_intensities,
  calibration_irradiances
)

Arguments

Value

Boolean: TRUE = pass, FALSE = fail

Examples

calib <- LightFitR::calibration
irradiances <- LightFitR::target_irradiance
checkRange(irradiances, calib$led, calib$wavelength, calib$intensity, calib$irradiance)

closest intensities

Description

Matrix of closest intensities for example purposes. Generated from 'target_irradiance'

Usage

example_closest

Format

A matrix with 9 rows and 10 columns: each row represents an LED channel and each column represents an event

example intensities

Description

Matrix of random intensities for example purposes

Usage

example_intensities

Format

A matrix with 9 rows and 10 columns: each row represents an LED channel and each column represents an event

regime matrix

Description

Example regime matrix

Usage

example_regime

Format

A matrix with 13 rows and 10 columns:

time

time in HH:MM:SS format

hour

The hour of the event

minute

The minute of the event

second

The second of the event

380nm

Intensity at 380nm LED channel

400nm

Intensity at 400nm LED channel

etc.

Check formatting of the heliospectra matrices

Description

Heliospectra DYNA matrices should have 9 rows (1 for each LED channel) and up to 150 columns (max number of events that Heliospectra DYNA can store)

Usage

helio.checkFormat(check_matrix)

Arguments

Value

Vector of booleans: TRUE = pass, FALSE = fail

Examples

matrix_to_check <- LightFitR::target_irradiance
helio.checkFormat(target_irradiance)

Check that the 9th white channel is set to 0

Description

We currently cannot support programming the white (5700k) LED channel.

Usage

helio.checkWhite(irradiance_matrix)

Arguments

Value

Boolean: TRUE = pass, FALSE = fail

Format regime_matrix for csv output that Heliospectra lights can parse

Description

Format regime_matrix for csv output that Heliospectra lights can parse

Usage

helio.csv_schedule(regime_matrix, filename)

Arguments

Value

Matrix formatted for Heliospectra lights csv

Examples

tempfile_name = tempfile(fileext='.csv')
helio.csv_schedule(LightFitR::example_regime, tempfile_name)

Turn Heliospectra into disco lights

Description

Congratulations! You've found the easter egg function!

Usage

helio.disco(filename, format = c("csv", "json"))

Arguments

Details

This writes a schedule for Heliospectra DYNA lights which randomly changes colour every second for a fun disco effect. The disco will last until the Heliospectra runs out of memory (150 events), so you can get 2 min 30s of disco out of your expensive lights... Enjoy!

Value

Disco schedule file for the heliospectra

Examples

tempfile_name = tempfile(fileext='.txt')
helio.disco(tempfile_name, format='json')

heliospectra DYNA LEDs

Description

Data about the heliospectra DYNA LED channels

Usage

helio.dyna.leds

Format

A data frame with 9 rows and 3 columns:

name

Name of the LED channel

wavelength

Wavelength of the LED channel

colour

Colour of the LED channel

Source

<https://heliospectra.com/led-grow-lights/dyna/>

Maximum number of events

Description

Maximum number of events programmable onto heliospectra

Usage

helio.eventLimit

Format

Integer representing maximum allowable events

Format regime_matrix for json output that Heliospectra lights can parse

Description

Format regime_matrix for json output that Heliospectra lights can parse

Usage

helio.json_schedule(regime_matrix, filename)

Arguments

Value

Character in json format that Heliospectra can parse

Examples

tempfile_name = tempfile(fileext='.txt')
helio.csv_schedule(LightFitR::example_regime, tempfile_name)

Add white (5700k) LED to intensities matricies after calculations

Description

Add white (5700k) LED to intensities matricies after calculations

Usage

internal.addWhiteZero(intensities_matrix)

Arguments

Value

Matrix of intensities with 9 rows

Internal function to make a calibration dataframe from user-supplied vectors of calibration data

Description

Internal function to make a calibration dataframe from user-supplied vectors of calibration data

Usage

internal.calibCombine(
  calibration_leds,
  calibration_wavelengths,
  calibration_intensities,
  calibration_irradiances
)

Arguments

Value

Correctly formatted dataframe of calibration data, for use in other functions

Internal function to check matrix for NAs

Description

Internal function to check matrix for NAs

Usage

internal.checkNAs(check_matrix)

Arguments

Value

Boolean: TRUE = pass, FALSE = fail

Internal function. Find the intensities corresponding to the closest irradiance match between intended and calibration.

Description

Internal function. Find the intensities corresponding to the closest irradiance match between intended and calibration.

Usage

internal.closestIntensities(
  irradiance_matrix,
  calibration_df,
  peaks = LightFitR::helio.dyna.leds$wavelength
)

Arguments

Value

Matrix of closest intensities, in the same format as 'irradiance_matrix'

Examples

# Format calibration data correctly
calib <- LightFitR::calibration[, c(3, 5, 4, 6)]

# Run function
internal.closestIntensities(LightFitR::target_irradiance, calib)

Internal function. Find the closest wavelengths to the stated peaks

Description

Internal function. Find the closest wavelengths to the stated peaks

Usage

internal.closestWavelength(wavelength_vec, peak_wavelengths)

Arguments

Value

Vector of wavelengths closest to the stated peaks

Internal function. Takes vector of timepoints (POSICxt format) and converts into format readable by heliospectra.

Description

Internal function. Takes vector of timepoints (POSICxt format) and converts into format readable by heliospectra.

Usage

internal.makeTimes(timeVector_POSIXct)

Arguments

Value

Matrix of times. Each row corresponds to hours, minutes, seconds

Remove empty white (5700k) LED from calculations

Description

Remove empty white (5700k) LED from calculations

Usage

internal.rmWhite(irradiance_matrix)

Arguments

Value

Matrix of irradiances, with 9th row removed as we currently don't support 5700k LED channel

Tidy intensities generated by algorithm so that lights can accept them

Description

Tidy intensities generated by algorithm so that lights can accept them

Usage

internal.tidyIntensities(intensities_matrix, calibration_intensities)

Arguments

Value

Maxtrix of intensities which are integers and capped at the maximum possible intensity

Create a regime (matrix) to program lights to achieve intended irradiances

Description

This is a wrapper function that carries out multiple steps:

1. Calculate closest intensities

2. Predict the intensities to use to achieve the target irradiance (via a system of linear equations or non-negative least squares)

3. Tidy the intensities (rounding to integer, keep within the range of intensities that the lights can be set to)

4. Format the intensities and timestamps into a human-readable regime matrix

Usage

makeRegime(
  timeVector_POSIXct,
  irradiance_matrix,
  calibration_leds,
  calibration_wavelengths,
  calibration_intensities,
  calibration_irradiances,
  peaks = LightFitR::helio.dyna.leds$wavelength,
  method = "nnls"
)

Arguments

Value

Matrix with light regime needed to program the lights

NNLS vs SLE

NNLS and SLE largely predict the same intensities, except in outlier cases. The default is NNLS, but if your predicted intensities end up being very far off, try SLE.

Examples

# Prep variables
calib <- LightFitR::calibration
times <- LightFitR::time_vector
target_irradiance <- LightFitR::target_irradiance

# Run function
makeRegime(times, target_irradiance, calib$led, calib$wavelength, calib$intensity, calib$irradiance)

Use non-linear least squares to interpolate intensities

Description

Use non-linear least squares to interpolate intensities

Usage

nnls_intensities(
  irradiance_matrix,
  closest_intensities,
  calibration_leds,
  calibration_wavelengths,
  calibration_intensities,
  calibration_irradiances,
  peaks = LightFitR::helio.dyna.leds$wavelength
)

Arguments

Value

Matrix of intensities to set the lights to, to achieve desired irradiances

Examples

# Prep variables
target_irradiance = LightFitR::target_irradiance
closest = LightFitR::example_closest
calib = LightFitR::calibration

# Run the function
nnls_intensities(target_irradiance, closest,
  calib$led, calib$wavelength, calib$intensity, calib$irradiance)

Read a heliospectra script (json format) into a matrix.

Description

Read a heliospectra script (json format) into a matrix.

Usage

read.helio_json(helio_script)

Arguments

Value

Matrix containing the regime encoded by the Heliospectra script

Examples

example_file <- system.file("extdata", "example_json_schedule.txt",
  package = "LightFitR", mustWork = TRUE)
read.helio_json(example_file)

Use a system of linear equations to calculate intensities

Description

Use a system of linear equations to calculate intensities

Usage

sle_intensities(
  irradiance_matrix,
  closest_intensities,
  calibration_leds,
  calibration_wavelengths,
  calibration_intensities,
  calibration_irradiances,
  peaks = LightFitR::helio.dyna.leds$wavelength
)

Arguments

Value

Matrix of intensities to set the lights to, to achieve desired irradiances

Examples

#' # Prep variables
target_irradiance = LightFitR::target_irradiance
closest = LightFitR::example_closest
calib = LightFitR::calibration

# Run the function
sle_intensities(target_irradiance, closest,
  calib$led, calib$wavelength, calib$intensity, calib$irradiance)

target irradiances

Description

Matrix of random target irradiances for example purposes

Usage

target_irradiance

Format

A matrix with 9 rows and 10 columns: each row represents an LED channel and each column represents an event

time vector

Description

Example timepoints for events

Usage

time_vector

Format

A vector of length 10 with timepoints in POSIXct format

Write the schedule to file that Heliospectra can parse

Description

Writes to json or csv format

Usage

write.helioSchedule(regime_matrix, filename, format = c("csv", "json"))

Arguments

Value

Heliospectra schedule file in either the csv or json format

Examples

tempcsv_name = tempfile(fileext='.csv')
write.helioSchedule(LightFitR::example_regime, tempcsv_name, format='csv')

temptxt_name = tempfile(fileext='.txt')
write.helioSchedule(LightFitR::example_regime, temptxt_name, format='json')