Overview#

How to cite MoonShine#

Poon, L., Jenks, I. T., Crampton, W. G. R. (2024). MoonShine: A software-hardware system for simulating moonlight ground illuminance and re-creating artificial moonlight cycles in a laboratory environment. Methods in Ecology and Evolution. https://doi.org/10.1111/2041-210X.14299

MoonShineP and its companion program MoonShineR#

MoonShineP is an open-source software-hardware system for re-creating moonlight cycles (as well as sunlight and twilight cycles) in a laboratory setting, using LED light. MoonShineP comprises a Python program running on a Raspberry Pi computer that controls the intensity of an array of individually addressable LEDs positioned in diffusion boxes. MoonShineP uses a companion R package with accompanying R scripts, MoonShineR, to predict moonlight and/or solar ground illuminance values (in lux) through a defined time range, at any geographical location. The predicted illuminance values are converted into LED intensity values and saved to a .csv schedule file. MoonShineP uses this file to control the LED array. MoonShineR can also be used to predict moonlight ground illuminance for use as a model predictor variable. This document is a tutorial and operating manual for MoonShineP and MoonShineR.

MoonShineR is a R package and two R scripts designed to predict the ground illuminance of moonlight, twilight, and sunlight at any geographic location and any time or range of times. Each of the three versions of MoonShineR programs serves a different purposes, and generates outputs tailored to that purpose.

All the required files are hosted on the GitHub site: https://github.com/Crampton-Lab/MoonShine

  1. MoonShineR: R package simply predicts moonlight/twilight/sunlight illuminance. It is intended for use in field studies where a biologist requires moonlight illuminance values as a model predictor variable.

MoonShineR: Moonlight scheduler and MoonShineR: Sunlight & twilight scheduler are designed for use in combination with MoonShineP (Fig. 1).

  1. MoonShineR: Moonlight scheduler predicts only moonlight illuminance values and convert these into LED intensity values. It generates an LED_schedule_moon.csv table that serves as the schedule for MoonShineP.

  2. MoonShineR: Sunlight & twilight scheduler predicts only sunlight and twilight illuminance values and converts these into LED intensity values. It generates an LED_schedule_sun.csv table that serves as a schedule for MoonShineP.

MoonShineP#

MoonShineP is an LED control system for recreating realistic moonlight, twilight, and sunlight regimes in a laboratory setting. A light regime can be freely edited, making it ideal for experiments requiring a specific lighting scenario. MoonShineP runs a Python program on the Linux operating system of a Raspberry Pi computer to control an array of LEDs. Every minute, the Python program reads the light schedule (generated by MoonShineR: schedulers) to refresh the LED intensities. Users can run a moonlight schedule as well as a sunlight and twilight schedule simultaneously on the Raspberry Pi. In this way, the Raspberry Pi can separately control two arrays of LED strips, so as to fully re-create all three major sources of natural light, around the clock (see concept in Fig. 1).

_images/map.png

Fig. 1 A flowchart of how MoonShineP works with the .csv schedule files created by MoonShineR to re-create light. MoonShineP can either create moonlight only (in a custom-made lightbox with neutral density filter sheets to calibrate light levels to natural moonlight levels), or sunlight and twilight (with the LEDs affixed to the ceiling, and no filtering utilized), or both moonlight and sunlight + twilight together.#

Table of contents#

Key to manual#

  • File names are indicated in pink text, for example xxx.csv.

  • File pathways names are indicated in italics, for example, Pi/Desktop/control_moon

  • Column names are also indicated in italics with single quote marks, for example, ‘datetime’.

  • R code, Python code, or terminal commands are shown in boxes. For example,

    this is a line of code

  • Internal hyperlinks within this documents & links to external websites are indicated in blue text.

Manual last updated Feb 1, 2024#