Solar irradiance clear sky index

Who it’s for

Solar operators, O&M engineers and asset managers who already log irradiance from a pyranometer or a reference cell and want to know how much of the day the site actually collected. The question is not whether the sun was out, but how far below a clear sky the site ran and in which hours. A monitoring team reviewing yesterday, or a technician deciding whether a site visit is worth the drive, both start here.

What it does

The card compares measured global horizontal irradiance against a clear-sky reference curve and shades the gap between them. The headline is the share of the reference the site actually delivered over the window on screen, and the shaded area is what it did not, reported in Wh/m2 beneath it, so a thin high haze and a bank of cumulus are told apart by the shape and the timing of the loss rather than by a single number.

• The headline is the share of the reference the site delivered. 0.68 of clear sky means the sensor recorded 68 % of the energy the reference offered over the window, with no interval counted above its own reference, so 1.00 is the ceiling and a day with no shortfall reaches it. The denominator is the site-calibrated reference — the modelled clear-sky global horizontal irradiance for this site and instant, scaled by the site factor described below — not the extraterrestrial irradiance that a different index uses. Naming the denominator is the only way to tell those apart without running them.

• The number on the card is not the clearSkyIndex key an alarm rule reads. The card’s figure is an energy-weighted aggregate over the window on screen, measured against the site-calibrated reference and capped at 1.00. The clearSkyIndex key that the Calculate Clear Sky Irradiance and Index field publishes is an instantaneous ratio against the unadjusted model and can go above 1.00. The two coincide when the site factor is 1.00 and part company when it is not, so take an alarm threshold from the key rather than by reading it off the card.

• The reference curve is calibrated from the site’s own best moments. Solar position comes from the NOAA algorithm and the clear-sky ceiling from the Haurwitz model, and the two are then scaled by a single site factor taken from the highest ratios the site itself reached in the window on screen. That one number absorbs the model’s bias, the sensor’s calibration and the tilt of the plane, which is why the card needs no threshold from anybody.

• The gap is reported, never explained. Soiling, haze, shading and a drifting calibration produce gaps that overlap, and a prototype measured a thin haze and a soiled array one thousandth apart. The card gives the size and the timing of the loss and leaves the cause to the operator.

• A silent sensor is not a perfect one. Time the device did not report leaves the arithmetic instead of being filled in with the last reading, and the footer says how much of the window’s sunlight was actually observed — weighted by clear sky, so a gap at noon counts for more than one at dusk. A pyranometer that drops out over the middle of the day reports a short day, not a flawless one.

• When it saw too little, it says so. Below the coverage you set, the card drops to its neutral colour and the footer reports how little it saw, ranked directly behind the time window so it is the last thing to go on a narrow card. A loss figure measured over half a day is not the same claim as one measured over all of it.

• A window with no daylight in it gets no figure at all. Set the dashboard to an hour after sunset and the card reads No daylight, not a flawless 1.00. A ratio needs something to be a ratio of, and an empty denominator is not a perfect day. A window too short to hold an interval — a single sample — reads Not enough data for the same reason.

• The card says how old its reading is. Once the silence is longer than three times the measured sample spacing, the footer names the age of the newest reading, ranked directly behind the time window. That is the same gap length the shortfall arithmetic uses to stop counting a held reading, so the card cannot say two different things about one silence.

• The plot carries its own scale. Each curve is named in the legend beneath it, and the plot prints its own maximum in W/m2, with gridlines at 25, 50 and 75 % of that value. The hours are marked under the plot on clock boundaries, such as 09:00, 12:00 and 15:00, rather than from the first sample, so a dip can be placed in the day, and a mark that falls on midnight shows the date. The marks thin as the card narrows, and a card too short to hold them keeps the plot and drops the marks.

• Nothing on the card is cut off mid-word. The footer keeps whole parts while they fit and drops the rest from the tail, rather than ellipsising: a truncated time range would read as a complete one that ends early, which is worse than one that is not shown.

• The card follows the dashboard’s own theme. There is no light or dark setting. The widget reads the inherited text colour and derives its ink, hairlines, plot track and shading from it, so a card dropped on a dark board turns dark with it and the shaded shortfall stays readable.

• Nothing leaves the browser. Solar position and the clear-sky ceiling are computed in the widget, with no service call, no API key and no external library.

• The reading is global horizontal. A sensor mounted in the plane of the array measures plane-of-array irradiance instead, and the reference curve will sit below it for most of the day.

• Reports what was lost against a clear sky: it does not forecast, and it does not name a cause.

Requirements

What must exist before the card can draw anything:

• A sensor reporting irradiance in W/m2 as a time series — a pyranometer, a reference cell, or a gateway that forwards either. The card reads whatever key that value arrives under.
• The site’s latitude and longitude. Roughly one irradiance device in five carries its own coordinates, so the card expects them typed into its settings unless it is told to read them from the entity, and it never guesses. Without them it draws the measured series and says so, because a curve drawn for the wrong place is worse than no curve.
• A dashboard time window that covers daylight. The reference is calibrated from the daylight samples in the window on screen, so a window with fewer than twenty of them falls back to the unadjusted model and says so on the card.

How to set up

Two decisions make a working card: bind the key that carries irradiance, and tell it where the site is. Everything else already has a default that works.

Data keys

Key	Type	Required	What happens without it
The irradiance value, in W/m2	Timeseries	Yes	The card says which key to add and draws no chart, rather than an empty axis
latitude and longitude on the entity	Attribute	Only when Location source reads the entity’s attributes	The footer names the two keys it looked for, and the card draws the measured series alone

Bind one entity and one irradiance key on the Data tab. The card reads the key it is given: the same quantity ships under many different names across the fleet, so it assumes none of them.

The coordinates come from one place, chosen with Location source, and never from both. Fixed coordinates are typed into the settings below and suit a device that does not report its own position. The entity’s attributes are read straight from the entity the card is bound to, so nothing extra goes on the Data tab. A card fed by a function datasource has no entity to read them from, and its footer says so.

Data

Setting	Default	Effect
Dim the card after no data for (minutes, 0 = never)	0	Dims the card once the newest sample is older than this. Off by default, because a site that reports only in daylight would otherwise dim every night. The age of the last reading is named in the footer regardless of this setting

Site location

Setting	Default	Effect
Location source	Fixed coordinates	Where the latitude and longitude come from: typed in below, or read from the entity’s attributes. The dialog shows only the two settings for the source chosen
Latitude (degrees north)	empty	The site latitude, negative in the southern hemisphere. Used with fixed coordinates
Longitude (degrees east)	empty	The site longitude, negative west of Greenwich. Used with fixed coordinates
Latitude attribute key	latitude	The entity attribute that carries the latitude. Used when reading the entity’s attributes
Longitude attribute key	longitude	The entity attribute that carries the longitude. Used when reading the entity’s attributes

Reference curve

Setting	Default	Effect
Site factor percentile	95	Which of the site’s own ratios becomes the reference. Lower it toward 90 on a site whose sensor spikes
Site factor lower limit	0.6	How far below the model the reference may be scaled on a persistently overcast window
Site factor upper limit	1.15	How far above the model it may be scaled, which is what a tilted or over-reading sensor needs
Minimum sun elevation (degrees)	5	Below this elevation the index is not computed and the hours are left out of the shortfall, because the model and the sensor both lose accuracy near the horizon
Qualify the reading below this coverage (%)	80	How much of the window’s sunlight the sensor must have observed before the figure stands unqualified. Below it the card drops to its neutral colour and the footer says how little it saw, ahead of everything except the window

Style

Setting	Default	Effect
Auto-scale text and spacing to card size	on	Steps the type and the spacing with the measured card box. Turn it off to keep one fixed size
Site name text	platform default	Font of the site name on the top line
Headline text	platform default	Font of the large headline figure
Secondary line text	platform default	Font of the energy and window line under it

How to customize

• To read the gap for one day rather than a run of them — set the dashboard time window to that day. The reference, the shortfall and the headline are all computed over the window on screen.
• To point the card at a different series — replace the bound key on the Data tab.
• To fix the site when the device does not report its own position — leave Location source on fixed coordinates and set Latitude (degrees north) and Longitude (degrees east).
• To read coordinates from the entity instead — set Location source to the entity’s attributes, then set Latitude attribute key and Longitude attribute key to the names those attributes carry.
• To make the reference stricter or more forgiving — set Site factor percentile. A lower percentile trusts fewer of the site’s peaks and lifts the measured shortfall.
• To keep the reference from chasing a bad window — set Site factor lower limit and Site factor upper limit, which bound how far the site factor may move from the model.
• To drop or keep the first and last hours of the day — set Minimum sun elevation (degrees).
• To change how much of the day the sensor must have seen before the figure stands on its own — set Qualify the reading below this coverage (%). Raise it on a site whose sensor is reliable and whose numbers get quoted. Lower it on one that drops out often and where a qualified figure every day would stop being read.
• To dim the card when a reading has gone quiet — set Dim the card after no data for (minutes, 0 = never). The card names the age of the last reading in the footer whether or not this is set. The setting decides only whether the whole card also fades.
• To keep the card’s text a fixed size — turn off Auto-scale text and spacing to card size, then set Site name text, Headline text and Secondary line text.

Tips

• Set the window to a single day before reading the headline. Over a week the figure is the whole week’s delivery against the whole week’s potential, which is a fair number but a different question from the one most reviews start with.

• Read the coverage before the headline on any day the sensor was unreliable. The figure is computed over the time the sensor actually reported, so a day it half missed produces a small loss that is honest about what was seen and silent about what was not.

• Watch the shape of the shaded area rather than its size. A gap that opens at the same hour every day points somewhere different from one that tracks the weather, and the card shows the timing precisely because the cause cannot be read from the total.

• A site factor that sits at the upper limit is worth checking. It usually means the sensor is tilted into the plane of the array rather than mounted horizontally, in which case the reference is doing the best it can with a reading the model was not written for.