diyepw Python API

diyepw.analyze_noaa_isd_lite_file.analyze_noaa_isd_lite_file(file: str, compression: str = 'infer')

Performs an analysis of a single NOAA ISD Lite file, determining whether it is suitable for conversion into an AMY EPW file.

Parameters

  • file – The path of the NOAA ISD Lite file to be analyzed. The file may be uncompressed, or in any compression format permitted by pandas.read_csv(). If it is compressed, it must have a corresponding file extension, or the compression parameter must be passed. File name must begin with the WMO index of the weather station at which the observations in the file were recorded.

  • compression – If you pass compressed files that don’t end in the typical extension for their compression type (e.g. “.gz” for GZIP, “.zip” for ZIP, etc.) then you must pass this to indicate what the files’ compression format is. See the documentation of the compression parameter of pandas.read_csv() for more information.

Returns

dict in the form: {

’file’: <str> - absolute path to the file, ‘total_rows_missing’: <int> - The number of total rows that are missing data in this file, ‘max_consec_rows_missing’: <int> - The largest number of consecutive rows that are missing data in this file

}

diyepw.analyze_noaa_isd_lite_files.analyze_noaa_isd_lite_files(files: Iterable, *, max_missing_rows: int = 700, max_consecutive_missing_rows: int = 48, compression: str = 'infer')

Performs an analysis of a set of NOAA ISD Lite files, determining which of them are suitable for conversion into AMY EPW files.

Parameters

  • files – An collection of paths to the NOAA ISD Lite files to be analyzed. See this package’s analyze_noaa_isd_lite_file() function for more information.

  • max_missing_rows – The maximum number of total missing rows to allow in a file.

  • max_consecutive_missing_rows – The maximum number of consecutive missing rows to allow in a file.

  • compression – If you pass compressed files that don’t end in the typical extension for their compression type (e.g. “.gz” for GZIP, “.zip” for ZIP, etc.) then you must pass this to indicate what the files’ compression format is. See the documentation of the compression parameter of pandas.read_csv() for more information.

Returns

dict in the form: {

”good”: [<file_description>, …], “too_many_total_rows_missing”: [<file_description>, …], “too_many_consecutive_rows_missing”: [<file_description>, …]

} …where <file_description> is itself a dict in the form: {

’file’: <str> - absolute path to the file, ‘total_rows_missing’: <int> - The number of total rows that are missing data in this file, ‘max_consec_rows_missing’: <int> - The largest number of consecutive rows that are missing data in this file

}

diyepw.create_amy_epw_file.create_amy_epw_file(wmo_index: int, year: int, *, max_records_to_interpolate: int = 6, max_records_to_impute: int = 48, max_missing_amy_rows: int = 700, amy_epw_dir: Optional[str] = None, tmy_epw_dir: Optional[str] = None, amy_dir: Optional[str] = None, amy_files: Optional[Tuple[str, str]] = None, allow_downloads: bool = False) → str

Combine data from a Typical Meteorological Year (TMY) EPW file and Actual Meteorological Year (AMY) observed data to generate an AMY EPW file for a single calendar year at a given WMO. :param wmo_index: The WMO Index of the weather station for which the EPW file should be generated.

Currently only weather stations in the United States are supported.

Parameters

  • year – The year for which the EPW should be generated

  • amy_epw_dir – The directory into which the generated AMY EPW file should be written. If not defined, a temporary directory will be created

  • tmy_epw_dir – The source directory for TMY EPW files. If a file for the requested WMO Index is already present, it will be used. Otherwise a TMY EPW file will be downloaded (see this package’s get_tmy_epw_file() function for details). If no directory is given, the package’s default directory (in data/tmy_epw_files/ in the package’s directory) will be used, which will allow AMY files to be reused for future calls instead of downloading them repeatedly, which is quite time consuming.

  • amy_dir – The source directory for AMY files. If a file for the requested WMO Index and year is already present, it will be used. Otherwise a TMY EPW file will be downloaded (see this package’s get_noaa_isd_lite_file() function for details). If no directory is given, the package’s default directory (in data/ in the package’s directory) will be used, which will allow AMY files to be reused for future calls instead of downloading them repeatedly, which is quite time consuming.

  • amy_files – Instead of specifying amy_dir and allowing this method to try to find the appropriate file, you can use this argument to specify the actual files that should be used. There should be two files - the first the AMY file for “year”, and the second the AMY file for the subsequent year, which is required to support shifting the timezone from GMT to the timezone of the observed meteorology.

  • max_records_to_interpolate – The maximum length of sequence for which linear interpolation will be used to replace missing values. See the documentation of _handle_missing_values() below for details.

  • max_records_to_impute – The maximum length of sequence for which imputation will be used to replace missing values. See the documentation of _handle_missing_values() below for details.

  • max_missing_amy_rows – The maximum total number of missing rows to permit in a year’s AMY file.

  • allow_downloads – If this is set to True, then any missing TMY or AMY files required to generate the requested AMY EPW file will be downloaded from publicly available online catalogs. Otherwise, those files being missing will result in an error being raised.

Returns

The absolute path of the generated AMY EPW file

diyepw.create_amy_epw_files_for_years_and_wmos.create_amy_epw_files_for_years_and_wmos(years: List[int], wmo_indices: List[int], *, max_records_to_interpolate: int = 6, max_records_to_impute: int = 48, max_missing_amy_rows: int = 700, amy_epw_dir: Optional[str] = None, tmy_epw_dir: Optional[str] = None, amy_dir: Optional[str] = None, amy_files: Optional[Tuple[str, str]] = None, allow_downloads: bool = False) → dict

Create AMY EPW files for every combination of a set of WMO indices and years.

Except for “years” and “wmos” being lists rather than single values, all parameters are identical in effect to create_amy_epw_file() - see that function’s documentation for details. :param wmo_indices: A list of the WMO Indices of the weather stations for which the EPW files should be generated.

Currently only weather stations in the United States are supported.

Parameters

  • years – A list of years for which the EPW files should be generated

  • max_records_to_interpolate – The maximum length of sequence for which linear interpolation will be used to replace missing values. See the documentation of _handle_missing_values() below for details.

  • max_records_to_impute – The maximum length of sequence for which imputation will be used to replace missing values. See the documentation of _handle_missing_values() below for details.

  • max_missing_amy_rows – The maximum total number of missing rows to permit in a year’s AMY file.

  • amy_epw_dir – The directory into which the generated AMY EPW file should be written. If not defined, a temporary directory will be created. Note that, in addition to the generated AMY EPW files, an errors.csv file will be created in this directory if any errors were encountered, with error messages explaining which year/WMO Index combinations failed and why.

  • tmy_epw_dir – The source directory for TMY EPW files. If a file for the requested WMO Index is already present, it will be used. Otherwise a TMY EPW file will be downloaded (see this package’s get_tmy_epw_file() function for details). If no directory is given, the package’s default directory (in data/tmy_epw_files/ in the package’s directory) will be used, which will allow AMY files to be reused for future calls instead of downloading them repeatedly, which is quite time consuming.

  • amy_dir – The source directory for AMY files. If a file for the requested WMO Index and year is already present, it will be used. Otherwise a TMY EPW file will be downloaded (see this package’s get_noaa_isd_lite_file() function for details). If no directory is given, the package’s default directory (in data/ in the package’s directory) will be used, which will allow AMY files to be reused for future calls instead of downloading them repeatedly, which is quite time consuming.

  • amy_files – Instead of specifying amy_dir and allowing this method to try to find the appropriate file, you can use this argument to specify the actual files that should be used. There should be two files - the first the AMY file for “year”, and the second the AMY file for the subsequent year, which is required to support shifting the timezone from GMT to the timezone of the observed meteorology.

  • allow_downloads – If this is set to True, then any missing TMY or AMY files required to generate the requested AMY EPW file will be downloaded from publicly available online catalogs. Otherwise, those files being missing will result in an error being raised.

Returns

A dictionary of the files generated for each year/wmo combination, in the form { <year>: {

<wmo_index>: [<file_path>, …], …

}

exception diyepw.exceptions.DownloadNotAllowedError

Bases: Exception

To be raised in situations where downloading a file would be necessary in order for correct functionality, but the caller has not given permission for file downloads to take place

diyepw.get_noaa_isd_lite_file.get_noaa_isd_lite_file(wmo_index: int, year: int, *, output_dir: Optional[str] = None, allow_downloads: bool = False) → str

Given a WMO index and a year, retrieve the corresponding NOAA ISD Lite AMY file :param wmo_index: :param year: :param output_dir: Optional output directory - if not specified, the file will be saved to a package directory.

If the directory already contains a NOAA ISD Lite file matching the requested WMO Index and year, then a new file will not be downloaded from NOAA and that file’s path will be returned

Parameters

allow_downloads – Pass True to permit NOAA ISD Lite files and related information to be downloaded from ncdc.noaa.gov if they are not already present in output_dir.

Returns

The path to the NOAA ISD Lite file

diyepw.get_tmy_epw_file.get_tmy_epw_file(wmo_index: int, output_dir: Optional[str] = None, allow_downloads: bool = False)

Given a WMO index, retrieve a TMY (typical meteorological year) EPW file for that location :param wmo_index: :param output_dir: Optional output directory - if not specified, the file will be saved to a directory in the

diyepw package so that it can be reused in the future if needed. If the directory already contains a TMY EWP file matching the requested WMO Index, then a new file will not be downloaded, we will just return that file’s path

Parameters

allow_downloads – Set to True to allow downloads if TMY3 files or the catalog containing their names and URLs to be downloaded from http://climate.onebuilding.org if not already present. If you want to use this method without permitting downloads, then the TMY3 files can be downloaded manually and put into the directory specified by output_dir (which defaults to data/tmy_epw_files/ in the package’s own directory structure). In this case, the files must have names identical to those used by http://climate.onebuilding.org/WMO_Region_4_North_and_Central_America/USA_United_States_of_America/

Returns

The path to the TMY EPW file

diyepw.get_wmo_station_location.get_wmo_station_location(wmo_station_number: int)

Get the state, and county associated with a WMO station :param wmo_station_number: The WMO Station ID of the weather station to get location information for :return: Either a dict with fields “state” and “county”, or None if no information is available for

the passed WMO Station ID

class diyepw.meteorology.Meteorology

Bases: object

Represents a time series of meteorological measurements at a given location.

_station_number The identification number of the weather station that made the observations
_headers - Array - Header file data taken from an input file
_latitude - float - Latitude at which the data was observed
_longitude - float - Longitude at which the data was observed
_data_source - string - Currently always "NOAA_TMY," identifies the source of the data
_city - str - The name of the city in which the data was observed
_state - str - The name of the city in which the data was observed
_country - str - The name of the city in which the data was observed
_timezone_gmt_offset - float - The timezone where the data was observed, expressed as the difference

from GMT

_elevation - float - The elevation at which the data was observed in meters above sea level
_comment - str - A comment string describing the TMY file
_observations - DataFrame - Data representing the year's observations
property city
property country
property elevation
static from_tmy3_file(file_path: str)

Create an instance of this class based on a tmy3 file

Parameters

file_path – Path to a TMY file. For the definition of a tmy3 file,

see https://www.nrel.gov/docs/fy08osti/43156.pdf :return:

property latlong
property observations
set(column_name: str, val)

Overwrite one of the columns in this instance’s observations :param column_name: Must be the name of one of the columns in this instance’s observations :param val: Mixed.

If val is a single value, every value of the named column will be set to that value If val is a list or pandas.Series, it must contain the same number of items as there are

rows in this instance’s observations, and will replace those values for the named column

Returns

property state
property station_number
property timezone_gmt_offset
validate_against_epw_rules() → list

Check all observations to see whether they violate any restrictions that would prevent them from being used in an EPW file

Returns

A list of validation errors

write_epw(save_path)