new endpoint: covid_hosp_facility_lookup

- the hhs covid hosp dataset is keyed by `hospital_pk`, which is a 
unique identifier for healthcare facilities.
- the key is not generally well-known, but querying the 
`covid_hosp_facility` dataset requires key(s)
- the new endpoint returns facility information (including key) for 
given regions (e.g. city, state, zip, ccn, fips)
- users would be expected to lookup hospitals of interest e.g. by state 
or city. then query `covid_hosp_facility` with the key for those 
hospitals.
- server and clients updates
- all unit and integrations pass

note that new indexes are added to the database to facilitate fast 
lookups. otherwise it would be a full table scan each time, which does 
not scale well. indexes are expected to be very small.

Author: dfarrow0

integrations/acquisition/covid_hosp/facility/test_scenarios.py

@@ -85,3 +85,79 @@ def test_acquire_dataset(self):
           '450822', Epidata.range(20200101, 20210101))
       self.assertEqual(response['result'], 1)
       self.assertEqual(len(response['epidata']), 1)
+
+  def test_facility_lookup(self):
+    """Lookup facilities using various filters."""
+
+    # only mock out network calls to external hosts
+    mock_network = MagicMock()
+    mock_network.fetch_metadata.return_value = \
+        self.test_utils.load_sample_metadata()
+    mock_network.fetch_dataset.return_value = \
+        self.test_utils.load_sample_dataset()
+
+    # acquire sample data into local database
+    with self.subTest(name='first acquisition'):
+      acquired = Update.run(network=mock_network)
+      self.assertTrue(acquired)
+
+    # texas ground truth, sorted by `hospital_pk`
+    # see sample data at testdata/acquisition/covid_hosp/facility/dataset.csv
+    texas_hospitals = [{
+      'hospital_pk': '450771',
+      'state': 'TX',
+      'ccn': '450771',
+      'hospital_name': 'TEXAS HEALTH PRESBYTERIAN HOSPITAL PLANO',
+      'address': '6200 W PARKER RD',
+      'city': 'PLANO',
+      'zip': '75093',
+      'hospital_subtype': 'Short Term',
+      'fips_code': '48085',
+      'is_metro_micro': 1,
+    }, {
+      'hospital_pk': '450822',
+      'state': 'TX',
+      'ccn': '450822',
+      'hospital_name': 'MEDICAL CITY LAS COLINAS',
+      'address': '6800 N MACARTHUR BLVD',
+      'city': 'IRVING',
+      'zip': '75039',
+      'hospital_subtype': 'Short Term',
+      'fips_code': '48113',
+      'is_metro_micro': 1,
+    }, {
+      'hospital_pk': '451329',
+      'state': 'TX',
+      'ccn': '451329',
+      'hospital_name': 'RANKIN HOSPITAL MEDICAL CLINIC',
+      'address': '1611 SPUR 576',
+      'city': 'RANKIN',
+      'zip': '79778',
+      'hospital_subtype': 'Critical Access Hospitals',
+      'fips_code': '48461',
+      'is_metro_micro': 0,
+    }]
+
+    with self.subTest(name='by state'):
+      response = Epidata.covid_hosp_facility_lookup(state='tx')
+      self.assertEqual(response['epidata'], texas_hospitals)
+
+    with self.subTest(name='by ccn'):
+      response = Epidata.covid_hosp_facility_lookup(ccn='450771')
+      self.assertEqual(response['epidata'], texas_hospitals[0:1])
+
+    with self.subTest(name='by city'):
+      response = Epidata.covid_hosp_facility_lookup(city='irving')
+      self.assertEqual(response['epidata'], texas_hospitals[1:2])
+
+    with self.subTest(name='by zip'):
+      response = Epidata.covid_hosp_facility_lookup(zip='79778')
+      self.assertEqual(response['epidata'], texas_hospitals[2:3])
+
+    with self.subTest(name='by fips_code'):
+      response = Epidata.covid_hosp_facility_lookup(fips_code='48085')
+      self.assertEqual(response['epidata'], texas_hospitals[0:1])
+
+    with self.subTest(name='no results'):
+      response = Epidata.covid_hosp_facility_lookup(state='not a state')
+      self.assertEqual(response['result'], -2)

src/client/delphi_epidata.R

@@ -585,6 +585,27 @@ Epidata <- (function() {
     return(.request(params))
   }
 
+  # Lookup COVID hospitalization facility identifiers
+  covid_hosp_facility_lookup <- function(state, ccn, city, zip, fips_code) {
+    # Set up request
+    params <- list(source = 'covid_hosp_facility_lookup')
+    if(!missing(state)) {
+      params$state <- state
+    } else if(!missing(ccn)) {
+      params$ccn <- ccn
+    } else if(!missing(city)) {
+      params$city <- city
+    } else if(!missing(zip)) {
+      params$zip <- zip
+    } else if(!missing(fips_code)) {
+      params$fips_code <- fips_code
+    } else {
+      stop('one of `state`, `ccn`, `city`, `zip`, or `fips_code` is required')
+    }
+    # Make the API call
+    return(.request(params))
+  }
+
   # Export the public methods
   return(list(
     range = range,
@@ -613,6 +634,7 @@ Epidata <- (function() {
     covidcast = covidcast,
     covidcast_meta = covidcast_meta,
     covid_hosp = covid_hosp,
-    covid_hosp_facility = covid_hosp_facility
+    covid_hosp_facility = covid_hosp_facility,
+    covid_hosp_facility_lookup = covid_hosp_facility_lookup
   ))
 })()

src/client/delphi_epidata.coffee

@@ -419,5 +419,25 @@ class Epidata
     # Make the API call
     _request(callback, params)
 
+  # Lookup COVID hospitalization facility identifiers
+  @covid_hosp_facility_lookup: (state, ccn, city, zip, fips_code) ->
+    # Set up request
+    params =
+      'source': 'covid_hosp_facility'
+    if state?
+      params.state = state
+    else if ccn?
+      params.ccn = ccn
+    else if city?
+      params.city = city
+    else if zip?
+      params.zip = zip
+    else if fips_code?
+      params.fips_code = fips_code
+    else
+      throw { msg: 'one of `state`, `ccn`, `city`, `zip`, or `fips_code` is required' }
+    # Make the API call
+    _request(callback, params)
+
 # Export the API to the global environment
 (exports ? window).Epidata = Epidata

src/client/delphi_epidata.js

@@ -661,6 +661,35 @@ function _createClass(Constructor, protoProps, staticProps) { if (protoProps) _d
           } // Make the API call
 
 
+          return _request(callback, params);
+        } // Lookup COVID hospitalization facility identifiers
+
+      }, {
+        key: "covid_hosp_facility_lookup",
+        value: function covid_hosp_facility_lookup(state, ccn, city, zip, fips_code) {
+          var params; // Set up request
+
+          params = {
+            'source': 'covid_hosp_facility'
+          };
+
+          if (state != null) {
+            params.state = state;
+          } else if (ccn != null) {
+            params.ccn = ccn;
+          } else if (city != null) {
+            params.city = city;
+          } else if (zip != null) {
+            params.zip = zip;
+          } else if (fips_code != null) {
+            params.fips_code = fips_code;
+          } else {
+            throw {
+              msg: 'one of `state`, `ccn`, `city`, `zip`, or `fips_code` is required'
+            };
+          } // Make the API call
+
+
           return _request(callback, params);
         }
       }]);

src/client/delphi_epidata.py

@@ -643,3 +643,25 @@ def covid_hosp_facility(
       params['publication_dates'] = Epidata._list(publication_dates)
     # Make the API call
     return Epidata._request(params)
+
+  # Lookup COVID hospitalization facility identifiers
+  @staticmethod
+  def covid_hosp_facility_lookup(
+      state=None, ccn=None, city=None, zip=None, fips_code=None):
+    """Lookup COVID hospitalization facility identifiers."""
+    # Set up request
+    params = {'source': 'covid_hosp_facility_lookup'}
+    if state is not None:
+      params['state'] = state
+    elif ccn is not None:
+      params['ccn'] = ccn
+    elif city is not None:
+      params['city'] = city
+    elif zip is not None:
+      params['zip'] = zip
+    elif fips_code is not None:
+      params['fips_code'] = fips_code
+    else:
+      raise Exception('one of `state`, `ccn`, `city`, `zip`, or `fips_code` is required')
+    # Make the API call
+    return Epidata._request(params)

src/ddl/covid_hosp.sql

@@ -1043,6 +1043,10 @@ CREATE TABLE `covid_hosp_facility` (
   UNIQUE KEY (`hospital_pk`, `collection_week`, `publication_date`),
   -- for fast lookup of a time-series for a given hospital and publication date
   KEY (`publication_date`, `hospital_pk`, `collection_week`),
-  -- for fast lookup of all hospital identifiers in a given state
-  KEY (`state`, `hospital_pk`)
+  -- for fast lookup of hospitals in a given location
+  KEY (`state`, `hospital_pk`),
+  KEY (`ccn`, `hospital_pk`),
+  KEY (`city`, `hospital_pk`),
+  KEY (`zip`, `hospital_pk`),
+  KEY (`fips_code`, `hospital_pk`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8;

src/server/api.php

@@ -1446,6 +1446,67 @@ function get_covid_hosp_facility($hospital_pks, $collection_weeks, $publication_
   return count($epidata) === 0 ? null : $epidata;
 }
 
+// queries the `covid_hosp_facility` table for hospital discovery
+//   $state (optional): 2-letter state abbreviation
+//   $ccn (optional): cms certification number (ccn) of the given facility
+//   $city (optional): name of
+//   $zip (optional): 2-letter state abbreviation
+//   $fips_code (optional): 2-letter state abbreviation
+//   note: exactly one of the above parameters should be non-null. if more than
+//         one is non-null, then only the first filter will be used.
+function get_covid_hosp_facility_lookup($state, $ccn, $city, $zip, $fips_code) {
+  $epidata = array();
+  $table = '`covid_hosp_facility` c';
+  $fields = implode(', ', array(
+    'c.`hospital_pk`',
+    'MAX(c.`state`) `state`',
+    'MAX(c.`ccn`) `ccn`',
+    'MAX(c.`hospital_name`) `hospital_name`',
+    'MAX(c.`address`) `address`',
+    'MAX(c.`city`) `city`',
+    'MAX(c.`zip`) `zip`',
+    'MAX(c.`hospital_subtype`) `hospital_subtype`',
+    'MAX(c.`fips_code`) `fips_code`',
+    'MAX(c.`is_metro_micro`) `is_metro_micro`',
+  ));
+  // basic query info
+  $group = 'c.`hospital_pk`';
+  $order = "c.`hospital_pk` ASC";
+  // build the filter
+  // these are all fast because the table has indexes on each of these fields
+  $condition = 'FALSE';
+  if ($state !== null) {
+    $condition = filter_strings('c.`state`', $state);
+  } else if ($ccn !== null) {
+    $condition = filter_strings('c.`ccn`', $ccn);
+  } else if ($city !== null) {
+    $condition = filter_strings('c.`city`', $city);
+  } else if ($zip !== null) {
+    $condition = filter_strings('c.`zip`', $zip);
+  } else if ($fips_code !== null) {
+    $condition = filter_strings('c.`fips_code`', $fips_code);
+  }
+  // final query using specific issues
+  $query = "SELECT {$fields} FROM {$table} WHERE ({$condition}) GROUP BY {$group} ORDER BY {$order}";
+  // get the data from the database
+  $fields_string = array(
+    'hospital_pk',
+    'state',
+    'ccn',
+    'hospital_name',
+    'address',
+    'city',
+    'zip',
+    'hospital_subtype',
+    'fips_code',
+  );
+  $fields_int = array('is_metro_micro');
+  $fields_float = null;
+  execute_query($query, $epidata, $fields_string, $fields_int, $fields_float);
+  // return the data
+  return count($epidata) === 0 ? null : $epidata;
+}
+
 // queries a bunch of epidata tables
 function get_meta() {
   // query and return metadata
@@ -1956,6 +2017,17 @@ function meta_delphi() {
       $epidata = get_covid_hosp_facility($hospital_pks, $collection_weeks, $publication_dates);
       store_result($data, $epidata);
     }
+  } else if($source === 'covid_hosp_facility_lookup') {
+    if(require_any($data, array('state', 'ccn', 'city', 'zip', 'fips_code'))) {
+      $state = isset($_REQUEST['state']) ? extract_values($_REQUEST['state'], 'str') : null;
+      $ccn = isset($_REQUEST['ccn']) ? extract_values($_REQUEST['ccn'], 'str') : null;
+      $city = isset($_REQUEST['city']) ? extract_values($_REQUEST['city'], 'str') : null;
+      $zip = isset($_REQUEST['zip']) ? extract_values($_REQUEST['zip'], 'str') : null;
+      $fips_code = isset($_REQUEST['fips_code']) ? extract_values($_REQUEST['fips_code'], 'str') : null;
+      // get the data
+      $epidata = get_covid_hosp_facility_lookup($state, $ccn, $city, $zip, $fips_code);
+      store_result($data, $epidata);
+    }
   } else {
     $data['message'] = 'no data source specified';
   }