`lib-weather` 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793914772/FIN+5.3.1+lib-weather 中文整理基于 FIN 5.3.1

导读： 气象服务和功能

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

目录（导读）

lib
meta
docs
tags
apps
funcs
views
def
supertypes
Overview
Model
- Weather Rec
- Points
- Forecast
- Weather vs Outside Tags
Sync
degreeDays(site, dates, base: null, opts: {})
degreeDaysBase(site)
- src
toWeather(rec, checked: true)
weatherReadLocs(loc)
weatherSunriseTime(coord, date, tz)
weatherSunsetTime(coord, date, tz)
weatherSyncHis(weatherRefs, span: null)

概述（中译）

气象服务和功能

API 正文（英文）

docs

Overview • Model • Sync


customaryUnits	Add this tag to the WeatherExt rec to force all units in forecast and history syncs to be in US customary system (degrees F)
metricUnits	Add this tag to the WeatherExt rec to force all units in forecast and history syncs to be in metric system (degrees C)
weatherAutoSyncForecast	Applied to a `weatherStation` to indicate that the weather forecast should be automatically synchronized using built-in weather subscription
weatherAutoSyncHis	Applied to a `weatherStation` to indicate that point histories should automatically be synchronized with built-in weather subscription
weatherSyncIds	Applied to a `weatherStation` to indicate which weather points to sync for that station

apps


weather	Views to visualize and configure weather stations

funcs


degreeDays	Given a `site` or `weather` record compute both the heating and cooling degree-days for the given date range
degreeDaysBase	Given a `site` or `weather` record, return the default balance point temperature to use for `degreeDays()`
toWeather	Attempt to get the weather station record from
weatherReadLocs	Search for matching weather stations given a city name
weatherSunriseTime	Get sunrise for date and location
weatherSunsetTime	Get sunset for date and location
weatherSyncHis	Import the latest historical data from the weather web service to the local history database

views


weatherDegreeDay	Chart degree day calculations for historical weather data
weatherForecast	Chart forecasted weather data
weatherHistory	Chart historical weather data
weatherStations	Managed the configured weather stations in the project database

app:weather

Views to visualize and configure weather stations

meta


def	app:weather
disKey	ui::weather
icon	weather
is	app
lib	lib:weather

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
app	UI application grouping of views

customaryUnits

Add this tag to the WeatherExt rec to force all units in forecast and history syncs to be in US customary system (degrees F). NOTE: this tag must be configured before any history syncs.

meta


def	customaryUnits
is	marker
lib	lib:weather

supertypes


marker	Marker labels a dict with typing information

lib weather

Overview

The WeatherExt provides a convenient mechanism to integrate both historical and current/forecast weather into the SkySpark database using a web-based weather service.

As a general policy, your site records should be associated with a weather station via the weatherStationRef tag.

Model

Weather is modelled using the following high level concepts:

weatherStation: record which models the top-level of a weather site/city/station
weather and point: data points associated with the weather (temp, humidity, etc)

Weather Rec

At the top level we model a weather site using the weatherStation tag. The weather site typically should have standard geo tags for the location of the weather station/city:

weatherStation: marker tag for weather station
dis: display name for the weather site
tz: all weather records must have timezone name
geoCity: should have city name
geoState: should have station/region name (if US this is two letter state code)
geoCountry: should have two letter ISO 3166-1 country code
geoCoord: optional geographic coordinate as latitude,longitude
weatherAutoSyncForecast: if you want auto-sync of forecast data
weatherAutoSyncHis: if you want auto-sync of historical data
weatherSyncIds: list of points to sync for this weather station

Important Note: The geo tags on the weather rec should not be modified from the values returned when learning a weather station. In particular, the geoCity, geoState, and geoCountry tags are used as the unique identifier for resolving a particular weather station. Our weather data provider is in the process of assigning unique identifiers for each weather station, but until that information is available to us, the geo tags should be considered "owned" by the weather extension.

Troubleshooting: If you upgraded from 2.1 to 3.0 and some of your weather stations are no longer syncing then there is probably a mismatch between the geo tags on your weather station record and what the weather data server expects. Verify the geo tags by searching for the weather station again. If you notice that any of the geo tags are different, you should manually edit your weather station record to fix the geo tags.

Another option is to completely remove the weather station (and its associated points) and then simply add the weather station again. This command will trash the bad weather station and all its weather points:

readById(@BadWeatherStationId).weatherTrash

Points

Multiple weather point records associated with a weather station store the historical data. You can specify which weather points to sync by configuring the weatherSyncIds tag on the weather site. See the tag docs for the list of available weather points. The builder app also provides a useful tool for finding weather stations, and configuring the weather points you want to sync.

All weather points are associated with their top level weather site via the weatherStationRef tag. These points also define all the standard his tags.

Forecast

The WeatherExt will automatically try to maintain a real-time snapshot of current observations and two day forecast. The current weather observation is stored using the curVal tag on the weather point.

The forecast data for a weather point is stored as transient forecast data in the historian. See hisRead() for details on the forecast options. For example:

// Get all historical and forecast data for Richmond weather points this week
readAll(point and weatherStationRef->geoCity=="Richmond").hisRead(thisWeek, {forecast})

// Get only forecast data for Richmond weather points this week
readAll(point and weatherStationRef->geoCity=="Richmond").hisRead(thisWeek, {forecastOnly})

Weather vs Outside Tags

We often model both local weather sensors and data from an official weather station. Local sensors are typically used for HVAC control sequences. But we might use official weather data for checking local sensor calibration or baseline energy normalization. In Haystack, weather station data is annotated with weather and point and site-local sensors with outside:

point air temp versus outside air temp
point air humidity versus outside air humidity

Sync

SkySpark includes a built-in weather subscription which is available as long as your license is under maintenance. With this subscription your weather stations can be auto-sync'ed for forecast data (including current conditions) and historical 3-hourly data. Auto-sync is controlled by these two tags:

weatherAutoSyncForecast: if configured will periodically poll weather service and maintain the weatherForecast rec with current conditions and 2 day forecast
weatherAutoSyncHis: if configured will periodically poll weather service for 3-hourly updates and write into the historian for temp, humidity, sunrise, and conditions

Note any initial historical data must be manually synchronized using the weatherSyncHis() function. If you have a large batch of historical data to import, you might wish to run the sync as background job.

If you wish to your own data or weather sources, then you will want to configure your recs using the model described here. But ensure that the auto sync tags are omitted.

def

func:degreeDays

degreeDays(site, dates, base: null, opts: {})

Given a site or weather record compute both the heating and cooling degree-days for the given date range. The dates can be any range supported by the hisRead() function. The base parameter specifies the balance point:

if null then degreeDaysBase() is used
if a number is passed, then it is used as both the heating and cooling balance temp
otherwise must be a dict with "heat" and "cool" tags to specify different balance temps

The opts parameter is a Dict that supports the following tags:

forecast: set to marker to include forecast data when computing degree days

Degree days are calculated using the average air temp for each day:

heatDegreeDays = heatBase - avg  // 0 if result is negative
coolDegreeDays = avg - coolBase  // 0 if result is negative

The results are returned as a history grid with the following columns:

ts: midnight of each day computed
heat: heating degree days in °daysF or °daysC
cool: cooling degree days in °daysF or °daysC

Any dates where no air temp data is available are computed as null degree days.

Examples

read(site).degreeDays(2010-10)
read(site).degreeDays(2010-10, 68°F)
read(site).degreeDays(pastMonth, {heat:17°C, cool:20°C})
read(site).degreeDays(pastMonth, {heat:17°C, cool:20°C}, {forecast})

meta


def	func:degreeDays
is	func
lib	lib:weather
name	degreeDays

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:degreeDaysBase

degreeDaysBase(site)

Given a site or weather record, return the default balance point temperature to use for degreeDays(). This function can return a single number to use for both the heating and cooling balance point, or it can return a dict with separate balance points using the tags "heat" and "cool". The number(s) returned must have an explicit unit of either °C or °F. The default implementation is 18°C or 65°F. Also see isMetric().

Examples:

65°F                    // single balance point
{heat:17°C, cool:19°C}  // separate balance points

meta


def	func:degreeDaysBase
is	func
lib	lib:weather
name	degreeDaysBase
overridable	✓

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

src

(site) => do
  if (isMetric(site)) 18°C else 65°F
end

def

func:toWeather

toWeather(rec, checked: true)

Attempt to get the weather station record from:

if rec has weatherStation tag, then return it
if rec has weatherStationRef tag, then dereference
if rec has siteRef, attempt to dereference from that

meta


def	func:toWeather
is	func
lib	lib:weather
name	toWeather

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:weatherReadLocs

weatherReadLocs(loc)

Search for matching weather stations given a city name. Resulting grid contains the following columns if available:

dis: full display name to use for prompt
disRec: best display name for weather rec (city, state, country)
geoCity: city name of station
geoState: region or US state code
geoCountry: ISO 3166-1 two letter code
geoCoord: longitude,latitude of station/city
tz: best guess for timezone

Side effects:

performs blocking network IO

meta


def	func:weatherReadLocs
is	func
lib	lib:weather
name	weatherReadLocs

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:weatherSunriseTime

weatherSunriseTime(coord, date, tz)

Get sunrise for date and location.

meta


def	func:weatherSunriseTime
is	func
lib	lib:weather
name	weatherSunriseTime

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:weatherSunsetTime

weatherSunsetTime(coord, date, tz)

Get sunset for date and location.

meta


def	func:weatherSunsetTime
is	func
lib	lib:weather
name	weatherSunsetTime

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

func:weatherSyncHis

weatherSyncHis(weatherRefs, span: null)

Import the latest historical data from the weather web service to the local history database. The weathers parameter must be weather recs in any format suppored by toRecList():

Ref or Ref[]
Dict/Dict[]
Grid

If the range is unspecified, then an attempt is made to synchronize any data after hisEnd of each weather point (last timestamp read). Otherwise must be a value supported by toDateSpan().

This method is designed to be run in the context of a job via the job. However note that the job must not define the jobSchedule tag. If an attempt is made to run this function using a scheduled job, then an exception is raised. Instead of using this func, ongoing his sync for weather is controlled by the weatherAutoSyncHis tag.

meta


admin	✓
def	func:weatherSyncHis
is	func
lib	lib:weather
name	weatherSyncHis

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
func	Axon function

def

metricUnits

Add this tag to the WeatherExt rec to force all units in forecast and history syncs to be in metric system (degrees C). NOTE: this tag must be configured before any history syncs.

meta


def	metricUnits
is	marker
lib	lib:weather

supertypes


marker	Marker labels a dict with typing information

def

view:weatherDegreeDay

Chart degree day calculations for historical weather data

meta


appName	weather
def	view:weatherDegreeDay
disKey	ui::degreeDays
icon	view
is	view
lib	lib:weather

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view: { inherit:"chart" }
weatherStations: { var input share kind:"Ref<weatherStation>[]" disKey:"ui::weather" navCluster }
span: { var input share kind:"Span" defVal:Span("today") }
data: { expr:"weatherDegreeDays({{weatherStations}}, {{span}})" }

def

view:weatherForecast

Chart forecasted weather data

meta


appName	weather
def	view:weatherForecast
disKey	ui::forecast
icon	view
is	view
lib	lib:weather

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view: { inherit:"chart" }
weatherStations: { var input share kind:"Ref<weatherStation>[]" disKey:"ui::weather" navCluster }
data: { expr:"weatherForecast({{weatherStations}})" }

def

view:weatherHistory

Chart historical weather data

meta


appName	weather
def	view:weatherHistory
disKey	ui::historical
icon	view
is	view
lib	lib:weather
order	100

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view: { inherit:"chart" }
weatherStations: { var input share kind:"Ref<weatherStation>[]" disKey:"ui::weather" navCluster }
span: { var input share kind:"Span" defVal:Span("today") }
data: { expr:"weatherHistorical({{weatherStations}}, {{span}})" }

def

view:weatherStations

Managed the configured weather stations in the project database

meta


admin	✓
appName	weather
def	view:weatherStations
defName	weatherStation
disKey	ui::stations
icon	view
is	view
lib	lib:weather

supertypes


feature	Feature namespace of definitions formatted as `feature:name`
view	Fresco UI view

src

view:   { inherit:"table" }
search: { input var kind:"Str" defVal:"" }
new:    { action:"recNew" uiInput:"uiMisc::WeatherActions.newAction" }
edit:   { action:"recEdit" }
trash:  { action:"recTrash" }
sync:   { disKey:"ui::sync" select multi action:"uiMisc::WeatherActions.onSync" }
menu:   { action:"uiContextMenu" }
data:   { expr:"readAll(weatherStation, { sort, search:{{search}} })" }

def

weatherAutoSyncForecast

Applied to a weatherStation to indicate that the weather forecast should be automatically synchronized using built-in weather subscription.

meta


def	weatherAutoSyncForecast
is	marker
lib	lib:weather
tagOn	weatherStation

supertypes


marker	Marker labels a dict with typing information

def

weatherAutoSyncHis

Applied to a weatherStation to indicate that point histories should automatically be synchronized with built-in weather subscription.

meta


def	weatherAutoSyncHis
is	marker
lib	lib:weather
tagOn	weatherStation

supertypes


marker	Marker labels a dict with typing information

def

weatherSyncIds

Applied to a weatherStation to indicate which weather points to sync for that station. The following list shows the sync ids and what weather points they map to as specified in the Project Haystack weather model children points.

temp: air-temp
apparent: apparent temp
condition: weatherCond
humidity: air humidity
precip: precipitation
windSpeed: wind-speed
windDir: wind-direction
pressure: atmospheric-pressure
cloudage: cloudage
sunrise: daytime
dew: air dewPoint
visibility: visibility

meta


def	weatherSyncIds
is	list
lib	lib:weather
of	str
tagOn	weatherStation

supertypes


val	Data value type
list	Ordered list of zero or more values

lib-weather 库参考 ​

目录（导读） ​

概述（中译） ​

API 正文（英文） ​

docs ​

apps ​

funcs ​

views ​

app:weather ​

customaryUnits ​

lib weather ​

Overview ​

Model ​

Weather Rec ​

Points ​

Forecast ​

Weather vs Outside Tags ​

Sync ​

func:degreeDays ​

degreeDays(site, dates, base: null, opts: {}) ​

func:degreeDaysBase ​

degreeDaysBase(site) ​

src ​

func:toWeather ​

toWeather(rec, checked: true) ​

func:weatherReadLocs ​

weatherReadLocs(loc) ​

func:weatherSunriseTime ​

weatherSunriseTime(coord, date, tz) ​

func:weatherSunsetTime ​

weatherSunsetTime(coord, date, tz) ​

func:weatherSyncHis ​

weatherSyncHis(weatherRefs, span: null) ​

metricUnits ​

view:weatherDegreeDay ​

src ​

view:weatherForecast ​

src ​

view:weatherHistory ​

src ​

view:weatherStations ​

src ​

weatherAutoSyncForecast ​

weatherAutoSyncHis ​

weatherSyncIds ​

`lib-weather` 库参考

目录（导读）

概述（中译）

API 正文（英文）

docs

apps

funcs

views

app:weather

customaryUnits

lib weather

Overview

Model

Weather Rec

Points

Forecast

Weather vs Outside Tags

Sync

func:degreeDays

degreeDays(site, dates, base: null, opts: {})

func:degreeDaysBase

degreeDaysBase(site)

src

func:toWeather

toWeather(rec, checked: true)

func:weatherReadLocs

weatherReadLocs(loc)

func:weatherSunriseTime

weatherSunriseTime(coord, date, tz)

func:weatherSunsetTime

weatherSunsetTime(coord, date, tz)

func:weatherSyncHis

weatherSyncHis(weatherRefs, span: null)

metricUnits

view:weatherDegreeDay

src

view:weatherForecast

src

view:weatherHistory

src

view:weatherStations

src

weatherAutoSyncForecast

weatherAutoSyncHis

weatherSyncIds