eta_utility.connectors.forecast_solar module

This module implements a REST API connector to the forecast.solar API.

Documentation:

Get solar production estimate for specific location (defined by latitude and longitude) and a specific plane orientation (defined by declination and azimuth) for an installed module power.

Historic solar production historic means here that the average of all years of the available weather data on that day is considered, the current weather is thus not included in the calculation.

Clear sky solar production If there were no clouds it would be a clear sky. clearsky thus calculates the theoretically possible production.

class eta_utility.connectors.forecast_solar.ForecastSolarConnection(url: str = 'https://api.forecast.solar', *, api_key: str = 'None', url_params: dict[str, Any] | None = None, query_params: dict[str, Any] | None = None, nodes: Nodes | None = None)[source]

Bases: BaseSeriesConnection

ForecastSolarConnection is a class to download and upload multiple features from and to the Forecast.Solar database as timeseries.

Parameters:
  • usr – Not needed for Forecast.Solar.

  • pwd – Not needed for Forecast.Solar.

  • api_key – Token for API authentication.

  • nodes – Nodes to select in connection.

baseurl: ClassVar[str] = 'https://api.forecast.solar'
time_format: ClassVar[str] = '%Y-%m-%dT%H:%M:%SZ'
headers: ClassVar[dict[str, str]] = {'Content-Type': 'application/json'}
url_params: dict[str, Any] | None

Url params for the forecast.Solar api

query_params: dict[str, Any] | None

Query params for the forecast.Solar api

read_node(node: NodeForecastSolar) pandas.DataFrame[source]

Download data from the Forecast.Solar Database.

Parameters:

node – Node to read values from.

Returns:

pandas.DataFrame containing the data read from the connection.

select_data(results: pd.DataFrame, from_time: pd.Timestamp | None = None, to_time: pd.Timestamp | None = None) tuple[pd.DataFrame, pd.Timestamp][source]

Forecast.solar api returns the data for the whole day. Select data only for the time interval.

Parameters:
  • nodes – pandas.DataFrame containing the raw data read from the connection.

  • from_time – Starting time to begin reading (included in output).

  • to_time – Time to stop reading at (included in output).

Returns:

pandas.DataFrame containing the selected data read from the connection and the current timestamp.

read(nodes: Nodes | None = None) pd.DataFrame[source]

Return current value from the Forecast.Solar Database.

Parameters:

nodes – List of nodes to read values from.

Returns:

pandas.DataFrame containing the data read from the connection.

write(values: Mapping[AnyNode, Any]) None[source]

Write data to a list of nodes

Parameters:

values – Dictionary of nodes and data to write {node: value}.

subscribe(handler: SubscriptionHandler, nodes: Nodes | None = None, interval: TimeStep = 1) None[source]

Subscribe to nodes and call handler when new data is available.

Parameters:
  • nodes – Identifiers for the nodes to subscribe to.

  • handler – Function to be called upon receiving new values, must accept attributes: node, val.

  • interval – Interval for receiving new data. Interpreted as seconds when given as integer.

read_series(from_time: datetime, to_time: datetime, nodes: Nodes | None = None, interval: TimeStep = 1, **kwargs: Any) pd.DataFrame[source]

Download timeseries data from the Forecast.Solar Database

Parameters:
  • nodes – List of nodes to read values from.

  • from_time – Starting time to begin reading (included in output).

  • to_time – Time to stop reading at (not included in output).

  • interval – Interval between time steps. It is interpreted as seconds if given as integer.

  • kwargs – Other parameters (ignored by this connector).

Returns:

Pandas DataFrame containing the data read from the connection.

subscribe_series(handler: SubscriptionHandler, req_interval: TimeStep, offset: TimeStep | None = None, nodes: Nodes | None = None, interval: TimeStep = 1, data_interval: TimeStep = 1, **kwargs: Any) None[source]

Subscribe to nodes and call handler when new data is available. This will always return a series of values. If nodes with different intervals should be subscribed, multiple connection objects are needed.

Parameters:
  • handler – SubscriptionHandler object with a push method that accepts node, value pairs.

  • req_interval – Duration covered by requested data (time interval). Interpreted as seconds if given as int

  • offset – Offset from datetime.now from which to start requesting data (time interval). Interpreted as seconds if given as int. Use negative values to go to past timestamps.

  • data_interval – Time interval between values in returned data. Interpreted as seconds if given as int.

  • interval – interval (between requests) for receiving new data. It is interpreted as seconds when given as an integer.

  • nodes – Identifiers for the nodes to subscribe to.

  • kwargs – Any additional arguments required by subclasses.

close_sub() None[source]

Close an open subscription. This should gracefully handle non-existant subscriptions.

timestr_from_datetime(dt: datetime) str[source]

Create an Forecast.Solar compatible time string.

Parameters:

dt – Datetime object to convert to string.

Returns:

Forecast.Solar compatible time string.

classmethod route_valid(nodes: Nodes) bool[source]

Check if node routes make up a valid route, by using the Forecast.Solar API’s check endpoint.

Parameters:

nodes – List of nodes to check.

Returns:

Boolean if the nodes are on the same route.

classmethod calculate_watt_hours_period(df: pandas.DataFrame, watts_column: str) pandas.DataFrame[source]

Calculates watt hours for each period based on the average watts provided. Assumes the DataFrame is indexed by timestamps.

classmethod summarize_watt_hours_over_day(df: pandas.DataFrame) pandas.DataFrame[source]

Sums up watt hours over each day.

classmethod get_dataframe_of_values(df: pandas.DataFrame, watts_column: str = 'watts') tuple[pandas.DataFrame, pandas.DataFrame][source]

Process the original DataFrame to return a DataFrame with watt_hours_period, watt_hours (summarized over the day), and watt_hours_day.