4.1. covid19_stats module

This is the top-level module for this repository. It defines the location of the resource directory relative to the module’s installation location (see Section 2), and the main COVID-19 database singleton object.

class covid19_stats.COVID19Database

This class implements a singleton pattern with static access methods to US GIS data and COVID-19 cumulative summary case and death data, for territorial units within the United States. It lazily instantiates itself via GIS loading functionality.

The main data this singleton object contains is the cumulative COVID-19 cumulative cases and deaths, for US counties, produced by the NY Times COVID-19 database.

This creates a custom FIPS code, with number 00001, by melding together the five New York City boroughs (Manhattan, Brooklyn, Queens, The Bronx, and Staten Island). This makes the COVID-19 geographic data set consistent with the COVID-19 cumulative cases and deaths data sets of the NY Times COVID-19 database.

In addition to a dict of MSA regions created or loaded by create_and_store_msas_and_fips_2019, this class also contains CONUS and state and territory regions dictionaries.

classmethod all_counties_nytimes_covid19_data()

Returns:: a DataFrame of the big shebang, the reason behind the reason, for the whole data set of COVID-19 cumulative cases and deaths. It is unordered. Here are the keys in this DataFrame: date (type date), county (of type string), state (of type string), fips (the FIPS code of type string), cumulative cases (of type int), and cumulative death (of type int).

As of 25 February 2021, there are almost \(10^6\) records in this list.

Return type:: DataFrame

classmethod data_conus()

Returns:

the same type of region data structure for a specific MSA. Easier to show rather than describe in words this dict.

{'RNAME': 'CONUS',
 'region name': 'CONUS',
 'prefix': 'conus',
 'fips': ['48059',
  '48253',
  '48441',
  '39133',
  '39153',
  '13095',
  '13177',
  '13273',
  '13321',
  '41043',
  '36001',
  '36083',
  '36091',
  '36093',
  ...],
 'population': 308126624}

Return type:

dict

classmethod data_msas_2019()

Returns:: the dict of MSA region information. It returns the same data structure as what create_and_store_msas_and_fips_2019 returns.
Return type:: dict

classmethod data_nonconus_states_territories()

Returns:

the dict of US state and territory information, for states and territories not in the CONUS. It returns the same type of data structure as what create_and_store_msas_and_fips_2019 returns. But better show-than-tell, here is the data for the state of Hawaii.

{'hawaii': {'RNAME': 'Hawaii',
  'region name': 'Hawaii',
  'prefix': 'hawaii',
  'fips': ['15009', '15003', '15001', '15007', '15005'],
  'population': 1415786}}

The identifying key is the lowercase, no-spaced version of the state’s name. Look at the values of the dict that mapping_state_rname_nonconus returns.

Return type:: dict

classmethod data_states()

Returns:

the dict of US state information, for states in the CONUS. It returns the same type of data structure as what create_and_store_msas_and_fips_2019 returns. But better show-than-tell, here is the data for the state of Rhode Island.

{'rhode_island': {'RNAME': 'Rhode Island',
  'region name': 'Rhode Island',
  'prefix': 'rhode_island',
  'fips': ['44001', '44003', '44005', '44007', '44009'],
  'population': 1059361}}

The identifying key is the lowercase, no-spaced version of the state’s name. Look at the values of the dict that mapping_state_rname_conus returns.

Return type:: dict

classmethod fips_adj_2018()

Returns:: the dict of adjacency information for US counties and territories. It returns the same data structure as what construct_adjacency returns.
Return type:: dict

classmethod fips_countystate_dict()

Returns:: the dict of county FIPS code to a dict of county and state. It returns one of the dicts (mapping of county FIPS code to county and state name) that create_and_store_fips_counties_2019 returns.
Return type:: dict

classmethod fips_data_2019()

Returns:: the dict of county geographical information. It returns the same data structure as what create_and_store_fips_2019 returns.
Return type:: dict

classmethod fips_dataframe_2019(): Returns a DataFrame with following columns: FIPS, county name, state or territory, and population. Data comes from dict vomited out by fips_popdict_2019 and fips_countystate_dict.

classmethod fips_msas_2019()

Returns:: the dict of county FIPS code to the MSA, identified by its prefix (for example, nyc is the New York City metropolitan area). Implictly, this dict only contains the counties that lie within an MSA.
Return type:: dict

classmethod fips_popdict_2019()

Returns:: the dict of county population data. It returns the same data structure as what create_and_store_fips_2019 returns.
Return type:: dict

classmethod mapping_state_rname_conus()

Returns:

a dict of state names, for states in the CONUS, to the region identifying name. Here is what it returns,

{'New Mexico': 'new_mexico',
 'Minnesota': 'minnesota',
 'Maryland': 'maryland',
 'Tennessee': 'tennessee',
 'Oregon': 'oregon',
 'New Hampshire': 'new_hampshire',
 'Ohio': 'ohio',
 'Maine': 'maine',
 'Utah': 'utah',
 'Alabama': 'alabama',
 'Michigan': 'michigan',
 'Iowa': 'iowa',
 'New York': 'new_york',
 'South Carolina': 'south_carolina',
 'Nebraska': 'nebraska',
 'Vermont': 'vermont',
 'Arizona': 'arizona',
 'California': 'california',
 'Virginia': 'virginia',
 'North Dakota': 'north_dakota',
 'Kansas': 'kansas',
 'District of Columbia': 'district_of_columbia',
 'North Carolina': 'north_carolina',
 'Delaware': 'delaware',
 'Massachusetts': 'massachusetts',
 'Oklahoma': 'oklahoma',
 'Florida': 'florida',
 'Montana': 'montana',
 'Idaho': 'idaho',
 'Pennsylvania': 'pennsylvania',
 'Texas': 'texas',
 'Illinois': 'illinois',
 'Kentucky': 'kentucky',
 'Mississippi': 'mississippi',
 'Wyoming': 'wyoming',
 'Colorado': 'colorado',
 'Arkansas': 'arkansas',
 'Indiana': 'indiana',
 'Nevada': 'nevada',
 'Georgia': 'georgia',
 'New Jersey': 'new_jersey',
 'Connecticut': 'connecticut',
 'West Virginia': 'west_virginia',
 'Louisiana': 'louisiana',
 'Rhode Island': 'rhode_island',
 'Wisconsin': 'wisconsin',
 'Missouri': 'missouri',
 'Washington': 'washington',
 'South Dakota': 'south_dakota'}

Return type:

dict

classmethod mapping_state_rname_nonconus()

Returns:

a dict of state names, for states and territories outside the CONUS, to the region identifying name. Here is what it returns,

{'Alaska': 'alaska', 'Hawaii': 'hawaii', 'Puerto Rico': 'puerto_rico'}

Return type:

dict

covid19_stats.get_stat_line(line)

This is a low level function that consumes each line os the CSV files (us-counties-2020.csv`, ``us-counties-2021.csv`, and ``us-counties-2022.csv), and returns a dict of useful information used by COVID19Database.

Parameters:: line (str) – line from valid row of CSV file (us-counties-2020.csv`, ``us-counties-2021.csv`, or ``us-counties-2022.csv), which contains information on running tally of cumulative deaths and cases of the county at a given date.
Returns:: a dict with the following keys: date which is a date of that county; county which is county name, state which is name of the state or US territory, fips which is the FIPS code code of the county; cumulative cases which is the cumulative number of cases by that date; and cumulative death which is the cumulative number of COVID-19 deaths by that date.
Return type:: dict