Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Expose configuration for handling coded values like -666666666 #75

Open
wants to merge 3 commits into
base: master
Choose a base branch
from
Open

Expose configuration for handling coded values like -666666666 #75

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2d41acb
Add failing tests for coded values handling
jeancochrane May 4, 2019
648f7c8
Handle coded values by casting to null or raising an error
jeancochrane May 4, 2019
e610ae7
Fix data formatting for individual API results in .get
jeancochrane May 7, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
82 changes: 73 additions & 9 deletions census/core.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,42 @@ def list_or_str(v):
return v
return [v]

def cast_nulls(func):
"""
Decorator to format null values in API result casting functions.
"""
def null_wrapper(v, cast_nulls):
# This value indicates that there were too few observations to compute
# an estimate. See:
# https://www.census.gov/data/developers/data-sets/acs-1year/notes-on-acs-estimate-and-annotation-values.html
if str(v) == '-666666666':
if cast_nulls is True:
return None
else:
raise NullValueException('Unhandled coded value: ', str(v))
else:
return func(v)
return null_wrapper
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Another (maybe simpler) way to do this would be to avoid the decorator abstraction and use a "checking" function instead. I liked the decorator since it felt to me like a semantic way of indicating that this checking logic is a high-level modification that can be applied somewhat abstractly to the other type casting functions.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I'd be a bit more comfortable with this architecture if we had more cases than just the -666666666. That said I'm comfortable to go with this approach until we accumulate more cases, and then we can potentially refactor if appropriate.


@cast_nulls
def to_str(v):
"""
Cast an API result to a string.
"""
return str(v)

@cast_nulls
def to_float(v):
"""
Cast an API result to a float.
"""
return float(v)

@cast_nulls
def float_or_str(v):
"""
Try casting an API result to a float, and fall back to a string.
"""
try:
return float(v)
except ValueError:
Expand Down Expand Up @@ -92,6 +127,10 @@ class UnsupportedYearException(CensusException):
pass


class NullValueException(Exception):
pass


class Client(object):
endpoint_url = 'https://api.census.gov/data/%s/%s'
definitions_url = 'https://api.census.gov/data/%s/%s/variables.json'
Expand Down Expand Up @@ -158,6 +197,10 @@ def get(self, fields, geo, year=None, **kwargs):

@retry_on_transient_error
def query(self, fields, geo, year=None, **kwargs):
cast_nulls = kwargs.get('cast_nulls', True)
if cast_nulls not in [True, False]:
raise CensusException('cast_nulls argument must be True or False')
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not totally confident in cast_nulls as the best name for the configuration argument that adjusts this behavior. In particular, it doesn't communicate that the alternative is to raise an error. Still, it was the best I had.


if year is None:
year = self.default_year

Expand Down Expand Up @@ -187,10 +230,31 @@ def query(self, fields, geo, year=None, **kwargs):

headers = data.pop(0)
types = [self._field_type(header, year) for header in headers]
results = [{header : (cast(item) if item is not None else None)
for header, cast, item
in zip(headers, types, d)}
for d in data]
results = []
error = False
for d in data:
row = []
for header, cast, item in zip(headers, types, d):
if item is not None:
try:
result = {header: cast(item, cast_nulls)}
except NullValueException:
# This value needs to raise an error, but we need the
# rest of the row values for context, so flag the
# error and continue the iteration
error = True
result = {header: item}
Copy link
Contributor Author

@jeancochrane jeancochrane May 7, 2019 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Some additional context for why we need to finish this inner loop before raising the error is that the results generated by for d in data look something like this:

{'var_name': -666666666, 'state': 42, 'county': 11}

The inner loop for header, cast, item in zip(headers, types, d) processes each of these elements in turn, returning a formatted "row" for the final results. The problem with raising an error in the inner loop is that we'll only know one of these header: item pairs (like var_name: -666666666 or 'state': 42) but unless you know all of the elements it's impossible to determine which API call raised the error.

else:
result = None
row.append(result)
if error:
msg = 'Null estimate code found: ' + str(row)
msg += '\nSee the Census documentation for more information:'
msg += '\nhttps://www.census.gov/data/developers/data-sets/acs-1year/notes-on-acs-estimate-and-annotation-values.html'
raise CensusException(msg)
else:
for result in row:
results.append(result)
return results

elif resp.status_code == 204:
Expand All @@ -204,17 +268,17 @@ def _field_type(self, field, year):
url = self.definition_url % (year, self.dataset, field)
resp = self.session.get(url)

types = {"fips-for" : str,
"fips-in" : str,
types = {"fips-for" : to_str,
"fips-in" : to_str,
"int" : float_or_str,
"float": float,
"string": str}
"float": to_float,
"string": to_str}

if resp.status_code == 200:
predicate_type = resp.json().get("predicateType", "string")
return types[predicate_type]
else:
return str
return to_str

@supported_years()
def us(self, fields, **kwargs):
Expand Down
63 changes: 62 additions & 1 deletion census/tests/test_census.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
import requests

from census.core import (
Census, UnsupportedYearException)
Census, UnsupportedYearException, CensusException)

KEY = os.environ.get('CENSUS_KEY', '')

Expand Down Expand Up @@ -121,6 +121,67 @@ def test_la_canada_2015(self):
)


class TestCodedValues(CensusTestCase):
"""
Tests for handling coded values, like -666666666 and -999999999.
"""
def test_handle_666666666(self):
"""
Test the default behavior of handling -666666666 values, which is to
cast them to null.
"""
# This call should return a value of -666666666
return_val = self._client.acs5.state_county_tract('B19081_001E',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want this to be the default behavior? I think the default should be the behavior of cast_null=True, but I'm persuadable.

42,
101,
'989100',
year=2016)
self.assertEqual(return_val[0]['B19081_001E'], None)

def test_handle_666666666_as_error(self):
"""
Test raising an error for -666666666 values.
"""
with self.assertRaises(CensusException):
return_val = self._client.acs5.state_county_tract('B19081_001E',
42,
101,
'989100',
year=2016,
cast_nulls=False)

def test_handle_666666666_as_null(self):
"""
Test casting -666666666 values to null.
"""
return_val = self._client.acs5.state_county_tract('B19081_001E',
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should also test that a warning is emitted that a value was cast to a null. Particularly if we decide to make this the default behavior.

42,
101,
'989100',
year=2016,
cast_nulls=True)
self.assertEqual(return_val[0]['B19081_001E'], None)

def test_bad_cast_nulls_argument(self):
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

great to have these tests!

"""
Test that an error gets raised for poorly-formated cast_nulls argument.
"""
with self.assertRaises(CensusException):
return_val = self._client.acs5.state('NAME',
Census.ALL,
cast_nulls='foobar')

with self.assertRaises(CensusException):
return_val = self._client.acs5.state('NAME',
Census.ALL,
cast_nulls=None)

with self.assertRaises(CensusException):
return_val = self._client.acs5.state('NAME',
Census.ALL,
cast_nulls=10)


class TestEndpoints(CensusTestCase):

def check_endpoints(self, client_name, tests, **kwargs):
Expand Down