geoips.sector_utils package#

Submodules#

geoips.sector_utils.estimate_area_extent module#

Utility for estimating the area extent, used in pyresample area definitions.

geoips.sector_utils.estimate_area_extent.center_longitude(min_longitude, max_longitude)[source]#

Determine the center longitude based off longitude in either degW or degE.

Parameters:

  • min_longitude (float) – Min and Max Longitude (degrees West or East)

  • max_longitude (float) – Min and Max Longitude (degrees West or East)

Returns:

Center longitude in degrees West or East

Return type:

float

geoips.sector_utils.estimate_area_extent.convert_west2east(longitude)[source]#

Convert Longitude from degrees West to degrees East, if applicable.

Parameters:

longitude (float) – Longitude (degrees West or East)

Returns:

Longitude in degrees East

Return type:

float

geoips.sector_utils.estimate_area_extent.esitmate_area_from_center(lat_0, lon_0, height, width, resolution)[source]#

Estimate the area extent for use in the YAML area definition.

Parameters:

  • lat_0 (float) – Center lat/lon values in degrees

  • lon_0 (float) – Center lat/lon values in degrees

  • height (int) – Pixel dimensions

  • width (int) – Pixel dimensions

  • resolution (int) – Resolution in meters

Returns:

Dictionary holding:

  • lower_left_xy - list of projection x/y coordinates of lower left corner of lower left pixel

  • upper_right_xy - list of projection x/y coordinates of upper right corner of upper right pixel

  • height - number of grid rows

  • width - number of grid columns

  • lat_0 - Center latitude in degrees

  • lon_0 - Center longitude in degrees

Return type:

dict

geoips.sector_utils.estimate_area_extent.estimate_area_extent(min_lat, min_lon, max_lat, max_lon, resolution)[source]#

Estimate the area extent for use in the YAML area definition.

Parameters:

  • min_lat (float) – Min/Max lat/lon values in degrees

  • min_lon (float) – Min/Max lat/lon values in degrees

  • max_lat (float) – Min/Max lat/lon values in degrees

  • max_lon (float) – Min/Max lat/lon values in degrees

  • resolution (float) – Resolution in meters

Returns:

Dictionary holding:

  • lower_left_xy - list of projection x/y coordinates of lower left corner of lower left pixel

  • upper_right_xy - list of projection x/y coordinates of upper right corner of upper right pixel

  • height - number of grid rows

  • width - number of grid columns

  • lat_0 - Center latitude in degrees

  • lon_0 - Center longitude in degrees

Return type:

dict

geoips.sector_utils.estimate_area_extent.generateMinMaxLatLong(lat_0, lon_0, height, width, resolution)[source]#

Generate minimum and maximum latitude longitude pairs.

Min/max lat/lon based off the resolution and height/width provided.

Parameters:

  • lat_0 (float) – Pair of latitude and longitude coordinates in degrees

  • lon_0 (float) – Pair of latitude and longitude coordinates in degrees

  • height (int) – Represents pixel dimensions and resolution of image in meters

  • width (int) – Represents pixel dimensions and resolution of image in meters

  • resolution (int) – Represents pixel dimensions and resolution of image in meters

Returns:

min_lat, max_lat, min_lon, max_lon

Return type:

list of floats

geoips.sector_utils.estimate_area_extent.haversine_distance(lat1, lon1, lat2, lon2)[source]#

Calculate the distance between two latitude and longitude points.

Uses the haversine formula.

Parameters:

  • lat1 (float) – Pair of latitude and longitude coordinates in degrees

  • lon1 (float) – Pair of latitude and longitude coordinates in degrees

  • lat2 (float) – Pair of latitude and longitude coordinates in degrees

  • lon2 (float) – Pair of latitude and longitude coordinates in degrees

Returns:

Distance in meters between two coordinates

Return type:

float

geoips.sector_utils.overpass_predictor module#

Overpass predictor, based on Two Line Element files.

geoips.sector_utils.overpass_predictor.calculate_overpass(tle, observer_lat, observer_lon, date, satellite_name)[source]#

Calculate next overpass for a satellite at an observer location and time.

Parameters:

  • tle (ephem.EarthSatellite) – tle for satellite

  • observer_lat (float) – observer latitude

  • observer_lon (float) – observer longitude

  • date (datetime.datetime) – start time for next overpass

  • satellite_name (str) – name of satellite

Returns:

next overpass information

Return type:

dict

geoips.sector_utils.overpass_predictor.check_tle_name_to_passed_names(tle_name, satellite_names_list)[source]#

Check if the satellite name in the TLE files is in the satellite names list.

Satellite names in the TLE files may be longer than the names passed to the overpass predictor For example, a user might request ‘GCOM-W1’, and the name in the TLE file is ‘GCOM-W1 (SHIZUKU)’.

Parameters:

  • tle_name (str) – satellite name read from the TLE file

  • satellite_names_list (list of str) – list of user specified satellites to read from TLE file

Returns:

True if tle_name is in the passed satellite names list

Return type:

bool

geoips.sector_utils.overpass_predictor.floor_minute(datetime_obj)[source]#

Remove seconds and microseconds from datetime object.

Parameters:

datetime_obj (datetime.datetime) – datetime

Returns:

datetime with no seconds/microseconds

Return type:

datetime.datetime

geoips.sector_utils.overpass_predictor.predict_overpass_area_def(tlefile, area_definition, satellite_list, start_datetime, check_midpoints=False)[source]#

Predict satellite overpass for an area_definition.

Parameters:

  • tlefile (str) – file path of TLE

  • area_definition (pyresample AreaDefinition) – pyresample area definition

  • satellite_list (list) – list of satellites to predict the overpass times

  • start_datetime (datetime.datetime) – start time to find the next available overpass

  • check_midpoints (bool) – check mid points of area definition for additional overpassses

Returns:

dictionary holding next satellite overpass estimates (sorted by satellite -> overpass info)

Return type:

dict

geoips.sector_utils.overpass_predictor.predict_overpass_yaml(tlefile, sectorfile, sector_list, satellite_list, start_datetime, check_midpoints=False)[source]#

Predict satellite overpass for sectors from a given yaml sector file.

Parameters:

  • tlefile (str) – file path of TLE

  • sectorfile (str) – file path of sectorfile

  • sector_list (list) – list of sectors held within the sectorfile

  • satellite_list (list) – list of satellites to predict the overpass times

  • start_datetime (datetime.datetime) – start time to find the next available overpass

  • check_midpoints (bool) – check mid points of area definition for additional overpassses

Returns:

dictionary holding next satellite overpass estimates for sectors (sorted by sector -> satellite -> overpass info)

Return type:

dict

geoips.sector_utils.overpass_predictor.predict_satellite_overpass(tlefile, satellite_name, satellite_tle, area_def, start_datetime, check_midpoints=False)[source]#

Estimate next satellite overpass information with ephem.

Parameters:

  • tlefile (str) – file path of TLE

  • satellite_name (str) – name of satellite

  • satellite_tle (dict) – dictionary holding satellite tle line1 and line2 data

  • area_def (pyresample AreaDefinition) – area definition

  • start_datetime (datetime.datetime) – start time to find the next available overpass

  • check_midpoints (bool) – check mid points of area definition for additional overpassses

Returns:

dictionary holding next overpass information

Return type:

dict

geoips.sector_utils.overpass_predictor.read_satellite_tle(tlefile, satellite_list)[source]#

Open and extract satellite infromation from TLE file.

Parameters:

  • tlefile (str) – file path of TLE

  • satellite_list (list of str) – list of satellites to read from TLE

Returns:

satellite TLE data

Return type:

dict

geoips.sector_utils.projections module#

Projection information for setting up pyresample area definitions.

geoips.sector_utils.projections.get_projection(name)[source]#

Get a dictionary of projection names containing the specified keys.

Dictionary keys:

  • name: the basemap projection short name

  • p4name: the Proj4 projection name

  • longname: a long name describing the projection

  • type: an integer indicating how the projection must be set up

The type field tells the program which arguments will be useful to a given projection

  • Can use corner lats and lons or center lats and lons with width and height

  • Ignores corner lats and lons and width/height arguments. Uses center lat/lon

  • Can use corner lats and lons or corner coordinates in the local projection space, but ignores all other location parameters.

geoips.sector_utils.tc_tracks module#

Modules to access TC tracks, based on locations found in the deck files.

geoips.sector_utils.tc_tracks.create_tc_sector_info_dict(clat, clon, synoptic_time, storm_year, storm_basin, storm_num, aid_type=None, storm_name=None, final_storm_name=None, deck_line=None, source_sector_file=None, pressure=None, vmax=None)[source]#

Create storm info dictionary from items.

Parameters:

  • clat (float) – center latitude of storm

  • clon (float) – center longitude of storm

  • synoptic_time (datetime.datetime) – time of storm location

  • storm_year (int) – 4 digit year of storm

  • storm_basin (str) – 2 digit basin identifier

  • storm_num (int) – 2 digit storm number

  • aid_type (str, default=None) – type of TC aid (BEST, MBAM, etc)

  • storm_name (str, default=None) – Common name of storm

  • final_storm_name (str, default=None) – Final name found throughout entire track file (ie, if reprocessing, will ensure early storm locations are identified with final storm name)

  • deck_line (str, default=None) – source deck line for storm information

  • pressure (float, default=None) – minimum pressure

  • vmax (float, default=None) – maximum wind speed

Returns:

fields – Dictionary of sector information, as passed into function.

Return type:

dict

geoips.sector_utils.tc_tracks.get_tc_area_id(fields, finalstormname, tcyear)[source]#

Get TC area_id from fields, to be used as pyresample AreaDefinition area_id.

Will be of form: * tcYYYYBBNNname (ie, tc2016io01one)

geoips.sector_utils.tc_tracks.get_tc_long_description(area_id, fields)[source]#

Return long_description of TC sector.

This is commonly used as the long name/description on the pyresample AreaDefinition.

geoips.sector_utils.tc_tracks.interpolate_storm_location(interp_dt, longitudes, latitudes, synoptic_times)[source]#

Interpolate the storm location at a specific time.

Based on a list of known locations and times

geoips.sector_utils.tc_tracks.set_tc_area_def(fields, tcyear=None, finalstormname=None, source_sector_file=None, clat=None, clon=None, tc_spec_template='tc_web', aid_type=None)[source]#

Set the TC area definition, using specified arguments.

Parameters:

  • fields (dict) – Dictionary of TC sector_info fields (clat, clon, storm name, etc) Valid fields can be found in geoips.sector_utils.utils.SECTOR_INFO_ATTRS

  • tcyear (int, default=None) – Passed tcyear - since current year may not match tcyear for SHEM storms

  • finalstormname (str, default=None) – finalstormname allows reprocessed storms to go in final storm directory

  • source_sector_file (str, default=None) – attach source_sector_file to area_definition if known

  • clat (float, default=None) – specify clat/clon separately from that found in ‘fields’

  • clon (float, default=None) – specify clat/clon separately from that found in ‘fields’

  • tc_spec_template (str, default="tc_web") – Path to template YAML file to use when setting up area definition.

  • aid_type (str, default=None) – type of TC aid (BEST, MBAM, etc)

Returns:

pyresample AreaDefinition object with specified parameters.

Return type:

pyresample.AreaDefinition

geoips.sector_utils.tc_tracks.trackfile_to_area_defs(trackfile_name, trackfile_parser='bdeck_parser', tc_spec_template=None)[source]#

Get TC area definitions for the specified text trackfile.

Limit to optionally specified trackfile_sectorlist

Parameters:

  • trackfile (str) – Full path to trackfile, convert each line into a separate area_def

  • trackfile_parser (str) – Parser to use from plugins.modules.sector_metadata_generators on trackfiles

Returns:

List of pyresample AreaDefinition objects

Return type:

list

geoips.sector_utils.tc_tracks_database module#

Utilities for creating a database of tropical cyclone tracks.

geoips.sector_utils.tc_tracks_database.check_db(filenames=None, process=False)[source]#

Check TC database for passed filenames.

filenames is a list of filenames and directories. if a list element is a string directory name, it expands to list of files in dir.

geoips.sector_utils.tc_tracks_database.get_all_storms_from_db(start_datetime, end_datetime, tc_spec_template=None, trackfile_parser=None, include_track_files=False)[source]#

Get all entries from all storms within a specific range of time from the TC DB.

Parameters:

  • start_datetime (datetime.datetime) – Start time of desired range

  • end_datetime (datetime.datetime) – End time of desired range

Returns:

List of pyresample Area Definitions, each storm location that falls within the desired time range.

Return type:

list of pyresample Area Definitions

Examples

>>> startdt = datetime.strptime('20200216', '%Y%m%d')
>>> enddt = datetime.strptime('20200217', '%Y%m%d')
>>> get_storm_from_db(startdt, enddt)
geoips.sector_utils.tc_tracks_database.open_tc_db(dbname='/users/surratt/geoips/outdirs/longterm_files/tc/tc_decks.db')[source]#

Open the TC Decks Database, create it if it doesn’t exist.

geoips.sector_utils.tc_tracks_database.reprocess_storm(tc_trackfilename)[source]#

Reprocess storm tc_trackfilename, using info in TC tracks database.

geoips.sector_utils.tc_tracks_database.update_fields(tc_trackfilename, cc, conn, process=False)[source]#

Update fields in TC track database with passed tc_trackfilename.

geoips.sector_utils.utils module#

Utilities for working with dynamic sector specifications.

geoips.sector_utils.utils.check_center_coverage(xarray_obj, area_def, varlist, covg_varname=None, covg_varlist=None, width_degrees=8, height_degrees=8, verbose=False, hours_before_sector_time=18, hours_after_sector_time=6)[source]#

Check if there is any data covering the center of the sector.

Do not provide any longitude padding for coverage check sectoring - we want to see if there is any data within the exact center box, not within +- 3 degrees of the center box.

geoips.sector_utils.utils.copy_sector_info(src_area_def, dest_area_def)[source]#

Copy sector info from src_area_def to dest_area_def.

geoips.sector_utils.utils.create_areadefinition_from_yaml(yamlfile, sector)[source]#

Take a YAML with misc metadata and create a pyresample areadefinition.

Misc. metadata will be parsed from the YAML file and manually added to the areadefinition

Parameters:

  • yamlfile (str) – full path to YAML area definition file

  • sector (str) – name of sector

Returns:

pyresample AreaDefinition based on YAML specification.

Return type:

pyresample.AreaDefinition

geoips.sector_utils.utils.filter_area_defs_actual_time(area_defs, actual_datetime)[source]#

Filter list of area_defs to only include the passed actual_datetime.

geoips.sector_utils.utils.get_lat_center(lats)[source]#

Return the center longitude point from lats array.

geoips.sector_utils.utils.get_lon_center(lons)[source]#

Return the center longitude point from lons array.

geoips.sector_utils.utils.get_max_lat(lats)[source]#

Get maximum latitude from array of latitudes.

Parameters:

lats (numpy.ndarray) – numpy MaskedArray of latitudes

Returns:

Maximum latitude, between -90 and 90

Return type:

float

geoips.sector_utils.utils.get_max_lon(lons)[source]#

Get maximum longitude from array of longitudes, handling date line.

Parameters:

lons (numpy.ndarray) – numpy MaskedArray of longitudes

Returns:

Maximum longitude, between -180 and 180

Return type:

float

geoips.sector_utils.utils.get_min_lat(lats)[source]#

Get minimum latitude from array of latitudes.

Parameters:

lats (numpy.ndarray) – numpy MaskedArray of latitudes

Returns:

Minimum latitude, between -90 and 90

Return type:

float

geoips.sector_utils.utils.get_min_lon(lons)[source]#

Get minimum longitude from array of longitudes, handling date line.

Parameters:

lons (numpy.ndarray) – numpy MaskedArray of longitudes

Returns:

Minimum longitude, between -180 and 180

Return type:

float

geoips.sector_utils.utils.get_sectors_from_yamls(sector_list)[source]#

Get AreaDefinition objects with custom “sector_info” dictionary.

Based on YAML area definition contained in “sectorfnames” files.

Parameters:

sector_list (list of str) – list of strings of desired sector names to retrieve from YAML files

Returns:

List of pyresample AreaDefinition objects, with arbitrary additional YAML entries added as attributes to each area def (this is to allow specifying “sector_info” metadata dictionary within the YAML file)

Return type:

list

geoips.sector_utils.utils.get_static_area_defs_for_xarray(xarray_obj, sectorlist)[source]#

Get all STATIC area definitions for the current xarray object.

Filter based on requested sectors.

Parameters:

  • xarray_obj (xarray.Dataset) – xarray Dataset to which we are assigning area_defs

  • sectorlist (list of str) – list of sector names

Returns:

List of pyresample AreaDefinition objects

Return type:

list of pyresample.AreaDefinition

geoips.sector_utils.utils.get_tc_area_defs_for_xarray(xarray_obj, tcdb_sector_list=None, tc_spec_template=None, trackfile_parser=None, hours_before_sector_time=18, hours_after_sector_time=6, aid_type=None)[source]#

Get all TC area definitions for the current xarray object, and requested sectors.

Parameters:

  • xarray_obj (xarray.Dataset) – xarray Dataset to which we are assigning area_defs

  • tcdb_sector_list (list of str, default=None) –

    • list of sector names to process, of format: tc2020io01amphan.

    • If None, or ‘all’ contained in list, process all matching TC sectors.

  • actual_datetime (datetime.datetime, default=None) – Optional datetime to match for dynamic sectors

  • var_for_coverage (str) – Default None, optional variable to sector to check exact time

  • hours_before_sector_time (float, default=18) – hours to look before sector time

  • hours_after_sector_time (float, default=6) – hours to look after sector time

  • aid_type (str, default=None) – string to look for in “aid_type” TC deck file field for inclusion

Returns:

List of pyresample AreaDefinition objects required for passed xarray

Return type:

list of pyresample AreaDefinition

geoips.sector_utils.utils.get_trackfile_area_defs(trackfiles, trackfile_parser, trackfile_sectorlist=None, tc_spec_template=None, aid_type=None, start_datetime=None, end_datetime=None)[source]#

Get all TC area definitions for the current xarray object, and requested sectors.

Parameters:

  • trackfiles (list) – List of trackfiles to convert into area_defs

  • trackfile_parser (str) – Parser to use from plugins.modules.sector_metadata_generators on trackfiles

  • str (trackfile_sectorlist list of) –

    • list of sector names to process, of format: tc2020io01amphan.

    • If None, or ‘all’ contained in list, process all matching TC sectors.

  • default=None –

    • list of sector names to process, of format: tc2020io01amphan.

    • If None, or ‘all’ contained in list, process all matching TC sectors.

  • aid_type (str, default=None) – If specified, string to look for in “aid_type” TC deck file field for inclusion

Returns:

List of pyresample AreaDefinition objects

Return type:

list of pyresample.AreaDefinition

geoips.sector_utils.utils.is_dynamic_sector(area_def)[source]#

Determine if the AreaDefinition object is a dynamic region of interest.

Parameters:

area_def (pyresample.AreaDefinition) – pyresample AreaDefinition object specifying region of interest

Returns:

  • True if area_def.sector_start_datetime exists and is not None,

  • False otherwise

Return type:

bool

geoips.sector_utils.utils.is_requested_aid_type(area_def, aid_type=None)[source]#

Return True if passed area_def is of requested aid_type.

geoips.sector_utils.utils.is_sector_type(area_def, sector_type_str)[source]#

Determine if the type of area_def sector is as specified in passed sector_type.

Parameters:

  • area_def (pyresample.AreaDefinition) – pyresample AreaDefinition object specifying region of interest

  • sector_type_str (str) –

    • String specifying the type of sector, must match ‘sector_type’ attribute on AreaDefinition object

    • currently one of ‘tc’, ‘pyrocb’, ‘volcano’, ‘atmosriver’ ‘static’

Returns:

True if area_def.sector_type == ‘sector_type’, False otherwise

Return type:

bool

geoips.sector_utils.utils.remove_duplicate_storm_positions(area_defs, aid_type=None)[source]#

Remove duplicate storm positions from passed list of area_defs.

Uses “is_requested_aid_type” and “storm_locations_match” utilities.

geoips.sector_utils.utils.set_tc_coverage_check_area_def(area_def, width_degrees=8, height_degrees=8)[source]#

Set the area definition for checking coverage for TC overpasses.

Take a small box around the center of the storm to evaluate coverage, rather than the entire image.

Parameters:

area_def (pyresample.AreaDefinition) – original area definition

Returns:

pyresample AreaDefinition pertaining to the region for plotting

Return type:

pyresample.AreaDefinition

geoips.sector_utils.utils.set_text_area_def(xarray_obj, area_def)[source]#

Set the area definition for text files.

This uses raw sectored data, not interpolated.

Parameters:

  • xarray_obj (xarray.Dataset) – xarray dataset

  • area_def (pyresample.AreaDefinition) – original area definition

Returns:

pyresample AreaDefinition pertaining to the region for generating text file

Return type:

pyresample.AreaDefinition

geoips.sector_utils.utils.storm_locations_match(area_def, other_area_def)[source]#

Return True if passed pyresample AreaDefinitions are the same location.

Match if center lat, center lon, storm year, storm basin, and synoptic time all match.

geoips.sector_utils.yaml_utils module#

Utilities for working with YAML sector specifications.

geoips.sector_utils.yaml_utils.add_description_to_yamldict(yaml_dict, sectorname, sector_type, sector_start_datetime=None, info_dict=None)[source]#

Add passed sector description information to passed YAML dictionary.

geoips.sector_utils.yaml_utils.add_dynamic_datetime_to_yamldict(yaml_dict, sectorname, sector_start_datetime, sector_end_datetime)[source]#

Add passed dynamic datetime info to passed YAML dictionary.

geoips.sector_utils.yaml_utils.add_projection_to_yamldict(yaml_dict, sectorname, center_lat, center_lon, center_x=0, center_y=0, template_yaml=None)[source]#

Add projection information to YAML dictionary.

geoips.sector_utils.yaml_utils.add_sectorinfo_to_yamldict(yaml_dict, sectorname, sector_info_dict)[source]#

Add sector_info dictionary to YAML dictionary.

geoips.sector_utils.yaml_utils.area_def_to_yamldict(area_def)[source]#

Convert passed pyresample AreaDefinition to a valid YAML dictionary.

geoips.sector_utils.yaml_utils.area_def_to_yamlfile(area_def, out_fname)[source]#

Write pyresample AreaDefinition out as a valid YAML dictionary.

geoips.sector_utils.yaml_utils.write_yamldict(yamldict, out_fname, force=False)[source]#

Write yamldict to out_fname.

Parameters:

  • yamldict (dict) – Dictionary to write out to YAML file

  • out_fname (str) – Output filename to write YAML dict to

  • force (bool, default=False) – If True, overwrite existing file.

Returns:

Path to output file if successfully produced

Return type:

str

Module contents#

Geoips sector utils init file.