Defines StormInfo and related functions for interacting with vitals ATCF data. More...

Detailed Description

Defines StormInfo and related functions for interacting with vitals ATCF data.

This module handles reading and manipulating individual entries of TCVitals files or CARQ entries of aid ("A deck") files. It provides each line as a StormInfo object with all available information contained within. This module does NOT supply much functionality for manipulating entire tcvitals databases. That is provided in the hwrf.revital module.

Note: StormInfo is good at complex manipulations of a single vitals time. However, it is inherently slow, and should not be used for large-scale manipulation of many vitals times such as multiple years of tcvitals or deck files. For example, model forecast verification packages should not use StormInfo. It is better to use compiled programs for such purposes. This slowness is inherent to Python, which is quite slow at creating and modifying objects.

Classes
class	CenturyError
	Raised when an implausible century is found. More...

class	InvalidATCF
	Raised when invalid ATCF data is found. More...

class	InvalidBasinError
	This exception is raised when an invalid Tropical Cyclone basin is found. More...

class	InvalidStormInfoLine
	This exception is raised when the StormInfo class receives an invalid tcvitals line or ATCF line that it cannot parse. More...

class	InvalidVitals
	Raised when a syntax error is found in the tcvitals, and the code cannot guess what the operator intended. More...

class	NoSuchVitals
	This should be raised when the user requests a specific storm or cycle of a storm and no such vitals exists. More...

class	StormInfo
	Storm vitals information from ATCF, B-deck, tcvitals or message files. More...

class	StormInfoError
	This is the base class of all exceptions raised when errors are found in the tcvitals, Best Track, Aid Deck or other storm information databases. More...

Functions
def	name_number_okay (vl)
	Given an array of StormInfo objects, iterate over those that have valid names and numbers. More...

def	basin_center_okay (vl)
	Given a list of StormInfo objects, iterates over those that have the right basins for the right centers. More...

def	vit_cmp_by_storm (a, b)
	A cmp comparison for StormInfo objects intended to be used with sorted(). More...

def	vitcmp (a, b)
	A cmp comparison for StormInfo objects intended to be used with sorted(). More...

def	storm_key (vit)
	Generates a hashable key for hashing StormInfo objects. More...

def	clean_up_vitals
	Given a list of StormInfo, sorts using the vitcmp comparison, discards suspect storm names and numbers as per name_number_okay, and discards invalid basin/center combinations as per basin_center_okay. More...

def	floatlatlon
	Converts a string like "551N" to 55.1, correctly handling the sign of each hemisphere. More...

def	quadrantinfo
	Internal function that parses wind or sea quadrant information. More...

def	parse_tcvitals
	Reads data from a tcvitals file. More...

def	find_tcvitals_for
	Faster way of finding tcvitals data for a specific case. More...

def	parse_carq
	Scans an A deck file connected to stream-like object fd, reading it into a list of StormInfo objects. More...

def	expand_basin
	Converts basin identifiers. More...

Variables
list	__all__
	List of symbols exported by "from hwrf.storminfo import *". More...

tuple	current_century = int(datetime.datetime.now().year)
	The first two digits of the year: the thousands and hundreds digits. More...

Function Documentation

def hwrf.storminfo.basin_center_okay ( vl )

Given a list of StormInfo objects, iterates over those that have the right basins for the right centers.

A, B, W, S and P are allowed for JTWC, and E, L, C and Q are allowed for NHC. Other entries are ignored. Also discards North hemispheric basin storms that are in the south hemisphere and vice-versa

Parameters

vl	An iterable of StormInfo objects to consider.

Definition at line 116 of file storminfo.py.

def hwrf.storminfo.clean_up_vitals	(	vitals,
		name_number_checker = `None`,
		basin_center_checker = `None`,
		vitals_cmp = `None`
	)

Given a list of StormInfo, sorts using the vitcmp comparison, discards suspect storm names and numbers as per name_number_okay, and discards invalid basin/center combinations as per basin_center_okay.

Lastly, loops over all lines keeping only the last line for each storm and analysis time. The optional name_number_checker is a function or callable object that takes a StormInfo as an argument, and returns True if the name and number match some internal requirements. By default, the name_number_okay function is used.

Parameters

vitals	A list of StormInfo
name_number_checker	A function that looks like name_number_okay() for determining which storm names and numbers are acceptable
basin_center_checker	A function that looks like basin_center_okay() for determining which basins and RSMCs are okay.
vitals_cmp	a cmp-like function for ordering two StormInfo objects

Definition at line 187 of file storminfo.py.

Referenced by hwrf.revital.Revital.clean_up_vitals(), and hwrf.revital.Revital.renumber().

def hwrf.storminfo.expand_basin	(	basin,
		subbasin = `None`
	)

Converts basin identifiers.

Given a one-letter or two-letter tropical basin identifier, and possibly another one-letter tropical basin identifier (subbasin), attempts to determine more information about the basin. Some information may be ambiguous if a two letter basin is specified. Returns a four-element tuple:

The internal (HWRF/GFDL) two-letter basin identifier. These have an unambiguous mapping to the one-letter basin.
The public, standard two-letter basin identifier used by JTWC and others. These are ambiguous: IO can be A or B, and SH can be S or P.
The one-letter basin identifier.
A description of the meaning of the basin.

Parameters

basin	the primary basin
subbasin	Optional: the subbasin, if known

Definition at line 1515 of file storminfo.py.

Referenced by hwrf.storminfo.StormInfo.change_basin().

def hwrf.storminfo.find_tcvitals_for	(	fd,
		logger = `None`,
		raise_all = `False`,
		when = `None`,
		stnum = `None`,
		basin1 = `None`
	)

Faster way of finding tcvitals data for a specific case.

A fast method of finding tcvitals in a file: instead of parsing each line into a StormInfo, it simply scans the characters of the line trying to find the right storm and time. Returns a list of matching vitals as StormInfo objects.

fd - the stream-like object to read from
logger - the logging.Logger to log to, or None
raise_all - if True, exceptions are raised immediately instead of just being logged.
when - the date to look for, or None
stnum - the storm number (ie.: 09 in 09L)
basin1 - the basin letter (ie.: L in 09L)

Warning: This function cannot handle errors in the formatting of the tcvitals lines. It will only work if the data in fd strictly follows the tcvitals format.

Definition at line 326 of file storminfo.py.

Referenced by hwrf.storminfo.parse_tcvitals().

def hwrf.storminfo.floatlatlon	(	string,
		fact = `10.0`
	)

Converts a string like "551N" to 55.1, correctly handling the sign of each hemisphere.

1 floatlatlon(string="311N",fact=10.0) = float(31.1) # degrees North

Returns: degrees North or degrees East

Parameters

string	Latitude or longitude in sum multiple of a degree, followed by N, S, E or W to specify the hemisphere. Must be a positive number
fact	The strung value is divided by this number. The default is to convert from tenths of a degree in string to a degree return value.

Note: This function does not accept negative numbers. That means the tcvitals "badval" -999 or -99 or -9999 will result in a None return value.

Definition at line 234 of file storminfo.py.

Referenced by hwrf.storminfo.StormInfo.hwrf_domain_center().

def hwrf.storminfo.name_number_okay ( vl )

Given an array of StormInfo objects, iterate over those that have valid names and numbers.

Discards TEST, UNKNOWN, and numbers 50-89

Parameters

vl	An iterable of StormInfo objects to consider.

Definition at line 105 of file storminfo.py.

def hwrf.storminfo.parse_carq	(	fd,
		logger = `None`,
		raise_all = `True`
	)

Scans an A deck file connected to stream-like object fd, reading it into a list of StormInfo objects.

Returns the list.

Parameters

logger	A logging.Logger to log to.
raise_all	If False, log and ignore errors instead of raising them.
fd	the file object to read

Returns: a list of StormInfo objects

Definition at line 378 of file storminfo.py.

Referenced by hwrf.revital.Revital.readcarq().

def hwrf.storminfo.parse_tcvitals	(	fd,
		logger = `None`,
		raise_all = `False`
	)

Reads data from a tcvitals file.

This reads line by line from the given file object fd, parsing tcvitals.

Returns: A list of StormInfo objects, one per line.

Parameters

fd	An opened file to read.
raise_all	If raise_all=True, exceptions will be raised immediately. Otherwise, any StormInfoError or ValueError will be logged or ignored, and parsing will continue.
logger	The logger is a logging.Logger object in which to log messages, or None (the default) to disable logging.

Definition at line 302 of file storminfo.py.

Referenced by hwrf.launcher.load(), hwrf.revital.Revital.readfiles(), and hwrf.revital.Revital.readvitals().

def hwrf.storminfo.quadrantinfo	(	data,
		qset,
		irad,
		qcode,
		qdata,
		what = `''`,
		conversion = `1.0`
	)

Internal function that parses wind or sea quadrant information.

This is part of the internal implementation of StormInfo: it deals with parsing wind or sea quadrant information.

Parameters

[out]	data	Output quadrant information, a dict mapping from the quadrant name in qset.
[out]	qset	output set of quadrants that were seen
	irad	Integer radius. For example, 34 may indicate the 34 kt wind radius.
	qcode	Special code used for circular (all quadrants) data
	qdata	String quadrant data information for each quadrant
	what	What type of data is this? Wind radii? Sea height radii? This should be an alphanumeric string.
	conversion	Unit conversion.

Definition at line 259 of file storminfo.py.

Referenced by hwrf.storminfo.StormInfo.hwrf_domain_center().

def hwrf.storminfo.storm_key ( vit )

Generates a hashable key for hashing StormInfo objects.

Lines are considered to be for the same database entry if they're from the same forecasting center, have the same basin, date/time and storm number. Note that the public two-letter basin (AL, EP, CP, WP, IO, SH, SL) is used here (stormid4) so that a/b and s/p conflicts are handled by keeping the last entry in the file.

Parameters

vit	the StormInfo of interest.

Returns: a tuple (center,stormid4,when) from the corresponding members of vit

Definition at line 174 of file storminfo.py.

Referenced by hwrf.storminfo.clean_up_vitals().

def hwrf.storminfo.vit_cmp_by_storm	(	a,
		b
	)

A cmp comparison for StormInfo objects intended to be used with sorted().

This is intended to be used on cleaned vitals returned by clean_up_vitals. For other purposes, use vitcmp.

Uses the following method:

Sort numerically by when.year
Break ties by sorting lexically by stormid3
Break ties by sorting by date/time
Break ties by retaining original order ("stable sort").

Parameters

a,b	StormInfo objects to order

Definition at line 134 of file storminfo.py.

def hwrf.storminfo.vitcmp	(	a,
		b
	)

A cmp comparison for StormInfo objects intended to be used with sorted().

Parameters

a,b	StormInfo objects to order. Uses the following method:

Sort numerically by date/time.
Break ties by a reverse sort by stormid. This places Invest (90s) first.
Break ties by ASCII lexical sort by center (ie.: JTWC first, NHC second)
Break ties by placing vitals WITH 34kt wind radii after those without.
Break ties by placing vitals with a full line (through 64kt radii) last
Break ties by retaining original order ("stable sort").

Definition at line 151 of file storminfo.py.

Variable Documentation

hwrf.storminfo.__all__

Initial value:

 = [ 'current_century', 'StormInfoError', 'InvalidBasinError', 
           'InvalidStormInfoLine', 'InvalidVitals', 'CenturyError', 
           'InvalidATCF', 'NoSuchVitals', 'name_number_okay',
           'basin_center_okay', 'vit_cmp_by_storm', 'vitcmp', 'storm_key',
           'clean_up_vitals', 'floatlatlon', 'quadrantinfo', 
           'parse_tcvitals', 'find_tcvitals_for', 'parse_carq', 'StormInfo',
           'expand_basin' ]

List of symbols exported by "from hwrf.storminfo import *".

Definition at line 21 of file storminfo.py.

hwrf.storminfo.current_century = int(datetime.datetime.now().year)

The first two digits of the year: the thousands and hundreds digits.

This is used to convert message files to tcvitals.

Definition at line 37 of file storminfo.py.

Detailed Description

Classes

Functions

Variables

Function Documentation

Variable Documentation