Ecology · Astronomy · Environmental time series
SOLAR
Calculate sunrise, sunset, daylight duration (photoperiod), solar noon, solar declination, maximum solar elevation and extraterrestrial solar radiation for the observation dates of any existing RainbowStats time series at a specified geographic location.
Syntax
SOLAR(series,location)series is an existing RainbowStats series, resolved as a SeriesOperator. It supplies the dates used for the astronomical calculations; its measured values are not inputs to the solar equations.
location is a GeoLocationOperator created by GEO_LOCATION(latitude,longitude[,elevationMeters,timeZone]). Latitude is positive north, longitude positive east, elevation is in meters, and the optional time zone is an IANA zone such as America/Los_Angeles.
No start or end dates are required. The input series supplies the observation calendar. No remote astronomy service, weather API or sensor is required.
Examples
salmon = DART("BON","CHINOOK")
location = GEO_LOCATION(45.64436,-121.94075,24,"America/Los_Angeles")
solar = SOLAR(salmon,location)
daylight = EXTRACT(solar,"DAYLIGHT")
radiation = EXTRACT(solar,"RADIATION")
In this example, salmon is an existing time-series variable, such as daily Columbia River salmon observations from DART. Solar measurements are computed for its observation dates; SOLAR does not fetch or modify the salmon counts.
Available extracts
| EXTRACT key | Units | Scientific meaning |
|---|---|---|
DAYLIGHT | hours/day | Sunrise-to-sunset duration, also called photoperiod; a seasonal environmental cue for migration, spawning and plant development. |
SUNRISE | decimal UTC hours | Estimated apparent sunrise for the observation date and location. |
SUNSET | decimal UTC hours | Estimated apparent sunset for the observation date and location. |
SOLAR_NOON | decimal UTC hours | Estimated time of solar transit, distinct from 12:00 civil clock time. |
DECLINATION | degrees | Sun's seasonal angular displacement north or south of the celestial equator. |
MAX_ELEVATION | degrees | Approximate maximum solar altitude above the horizon on the observation date. |
RADIATION | MJ/m²/day | Estimated daily extraterrestrial solar irradiation on a horizontal surface, not observed surface sunlight. |
Supported aliases: SOLAR_RADIATION and EXTRATERRESTRIAL_RADIATION for RADIATION; SOLAR_DECLINATION for DECLINATION; SOLAR_ELEVATION for MAX_ELEVATION.
When to use SOLAR
Ecology and fisheries: investigate whether salmon migration, spawning, fish passage, plankton cycles or other biological events vary with photoperiod, the seasonal direction of daylight change, water temperature and river flow. Combine with DART and USGS measurements.
Hydrology and reservoirs: examine seasonal solar forcing alongside streamflow, reservoir storage, evaporation proxies and water temperature. Combine with USGS and USBR observations.
Agriculture and phenology: investigate flowering, crop development, growing seasons, dormancy and other photoperiod-sensitive responses.
Climate, air quality and energy: use deterministic solar geometry as a reference variable when studying temperature, seasonal air-quality variation, and potential solar-energy availability. Combine with AQS or other meteorological series.
Statistical interpretation
Solar geometry is deterministic given location and date, making these variables useful as reproducible explanatory factors. However, daylight and radiation are strongly seasonal and may be correlated with temperature, precipitation, river flow and biological outcomes. A high correlation alone does not establish an independent causal effect.
For regression, compare models with and without solar variables; consider seasonal indicators, temperature, flow, lag structures, autocorrelation-robust inference and out-of-sample validation. Daily changes in photoperiod may also be scientifically relevant, but should be calculated from a numeric daylight series rather than assumed to be a separate solar extract.
Methods, precision and limitations
The solar calculations use approximate astronomical equations for declination and the equation of time, an apparent-horizon correction for sunrise and sunset, and an FAO-56-style estimate of extraterrestrial irradiation. They are intended for environmental analysis, not high-precision navigation or observatory timing.
Elevation can affect the visible horizon under an unobstructed-horizon assumption. Actual local terrain, buildings, atmospheric conditions, clouds and aerosol attenuation are not modeled. Extraterrestrial radiation is not measured ground-level solar radiation.
Sunrise and sunset may be undefined during polar day or polar night. For monthly or annual input series, calculations correspond to the observation dates, not automatically to period averages. UTC clock-hour values should not be confused with local civil time or daylight-saving time.
Current output: The present SolarOperator represents dated solar measurements as JSON; its metric extracts are not yet native numeric DataSeries objects. Direct use in regression and line charts requires the planned DataSeries conversion.
Available extracts
Save the command result in a variable, then use EXTRACT(result, "key"). Availability can depend on the input form and fitted model.
DAYLIGHTSUNRISESUNSETSOLAR_NOONDECLINATIONMAX_ELEVATIONRADIATIONSOLAR_RADIATIONEXTRATERRESTRIAL_RADIATIONSOLAR_DECLINATIONSOLAR_ELEVATION
In indexed patterns such as beta:n, replace n with the required index.