Release Guide¶

Naming Conventions¶

Major Releases¶

The POWER project bundles individual microservice versions to make a major releases of the POWER Services. All POWER services and resources will be following the Semantic Versioning Specification (SemVer) and have the reporting requirements. This will include the date of change, version number, a title, and a detailed description.

Conventions¶

Each individual service will have an independent version number that is tied to a specific promotion. All promotions to the production environment, regardless of how minor, will trigger a new version number. All promotions, version changes, require a statement of changes to be logged in reference to the version number. If a major release (Position 1) is triggered all the services will be frozen and a new version number change will be implemented.

Reporting¶

Each version number will contain a minimum amount of information:

1. Date of change
2. TVersion Number
3. Title
4. Detailed Description
5. Impact of the change(s) to the community and other services.

Numbering¶

[name-of-service] v01.02.03 or [name-of-service] v1.2.3

• Position 1: Major upgrades to the services and/or system (e.g. a breaking change).
• Position 2: Significant updates to Functionality and/or additions (e.g. adding/removing a new endpoint, an option, and/or temporal level).
• Position 3: Any change to the code that is pushed to production.

Version History¶

Websites¶

The changelog for the Websites that provide context about POWER's data and services.

Datastore¶

The changelog for the Datastore that supplies data to the APIs.

System APIs¶

The APIs that supply consistent configuration information across the APIs. System API Services

Temporal APIs¶

The APIs that return user community specific Analysis Ready Data (ARD) products. See more at Temporal API Services

Application APIs¶

The APIs that return user specified reports and validation products that use the Temporal APIs. Application API Services

Release Notes¶

Data Version 9.x.x¶

Traceability & Changes in Values¶

The Services Version 2 of POWER provides Data Version 901 POWER data (Services Version 1 provided Data Version 801). The Data Version 901 improves the 1) underling source data and 2) enhances traceability to source data. Specifically, the underling data sources for radiation-based parameters has changed from SRB v3 to SRB v4 for 1984 through 2000. From 2001, we now provide CERES SYN1deg until three months before present time. Like in previous versions, POWER continues to provide support for Near Real Time (NRT) availability with FLASHFlux. For the enhanced traceability, Data Version 901 POWER data includes improved parameter abbreviations and definitions, in order to be more clear about what parameter is being used. The most prominent change is that POWER provides data at the underlying data source's grid resolution.

So, changes in the values are to be expected:

• For meteorology-based parameters, we are no-longer using bilinear interpolation to put the source data on a common 0.5 x 0.5 degree grid as it was in Data Version 801 (to enhance traceability). Not using interpolation causes some slight variation in the values compared to the previous version, but the values are exactly the same as the source dataset for a particular point location. The differences in values between Data Version 801 and 901 could be more pronounced for a specific point location if:

• the location is close to a land/sea boundary.

• the location is close to the grid box boundary (since the data could potentially have pulled from a adjacent grid box when it was not using original source data grid).

• For solar-based parameters, we are no-longer replicating the source data on a common 0.5 x 0.5 degree grid; we changed the underling source data to newer versions. For more information, please review the data sources here.

• The elevation, or altitude, is also not interpolated so the same reasons for meteorology-based parameters apply.

New Parameters Names¶

Some of the parameter names in your example changed; the definition just to confirm:

• ALLSKY_TOA_SW_DWN to TOA_SW_DWN: Top-Of-Atmosphere Shortwave Downward Irradiance - The total solar irradiance incident (direct plus diffuse) on a horizontal plane at the top of the atmosphere (extraterrestrial radiation).

• DNR to ALLSKY_SFC_SW_DNI: The direct solar irradiance incident to a horizontal plane normal (perpendicular) to the direction of the sun's position under all sky conditions.

• SRF_ALB to ALLSKY_SRF_ALB: The direct solar irradiance incident to a horizontal plane normal (perpendicular) to the direction of the sun's position under all sky conditions.

• DIFF to ALLSKY_SFC_SW_DIFF: The diffuse (light energy scattered out of the direction of the sun) solar irradiance incident on a horizontal plane at the surface of the earth under all sky conditions.

• PRECTOT to PRECTOTCORR: Precipitation Corrected - The bias corrected average of total precipitation at the surface of the earth in water mass (includes water content in snow). In V1 you where getting PRECTOTCORR when you request PRECTOT.

• In the previous API version, that change happened dynamically but, in this version, we are working to enhance traceability between the underlying source data (to be clear what parameter is being used).

• KT to ALLSKY_KT: All Sky Insolation Clearness Index - A fraction representing clearness of the atmosphere and the all sky insolation that is transmitted through the atmosphere to strike the surface of the earth divided by the average of top of the atmosphere total solar irradiance incident.

• SG_HR_AZM_ANG_AVG to SG_SAA_HR: Average Solar Azimuth Angle for Climatological Month - The angle of the vector from the earth point to the suns position at GMT Times.

• SG_HR_HRZ_ANG_AVG to SG_HRZ_HR: Average Hourly Solar Angles Relative To The Horizon for Climatological Month - The vertical angle of the sun above the horizon at GMT Times. The determination of monthly averaged maximum solar angle relative to the horizon for each month is based on the monthly average day.