def get_places_in(dcids, place_type):
""" Returns :obj:`Place`s contained in :code:`dcids` of type
:code:`place_type`.
Args:
dcids (:obj:`iterable` of :obj:`str`): Dcids to get contained in places.
place_type (:obj:`str`): The type of places contained in the given dcids to
filter by.
Returns:
The returned :obj:`Place`'s are formatted as a :obj:`dict` from a given
dcid to a list of places identified by dcids of the given `place_type`.
Raises:
ValueError: If the payload returned by the Data Commons REST API is
malformed.
Examples:
We would like to get all Counties contained in
`California <https://browser.datacommons.org/kg?dcid=geoId/06>`_. Specifying
the :code:`dcids` as a :obj:`list` result in the following.
>>> get_places_in(["geoId/06"], "County")
{
'geoId/06': [
'geoId/06041',
'geoId/06089',
'geoId/06015',
'geoId/06023',
'geoId/06067',
...
# and 53 more
]
}
"""
dcids = filter(lambda v: v == v, dcids) # Filter out NaN values
dcids = list(dcids)
url = utils._API_ROOT + utils._API_ENDPOINTS['get_places_in']
payload = utils._send_request(url,
req_json={
'dcids': dcids,
'place_type': place_type,
})
# Create the results and format it appropriately
result = utils._format_expand_payload(payload, 'place', must_exist=dcids)
return result
def get_populations(dcids, population_type, constraining_properties={}):
""" Returns :obj:`StatisticalPopulation`'s located at the given :code:`dcids`.
Args:
dcids (Union[:obj:`list` of :obj:`str`, :obj:`pandas.Series`]): Dcids
identifying :obj:`Place`'s of populations to query for. These dcids are
treated as the property value associated with returned :obj:`Population`'s
by the property
`location <https://browser.datacommons.org/kg?dcid=location>`_
population_type (:obj:`str`): The population type of the
:obj:`StatisticalPopulation`
constraining_properties (:obj:`map` from :obj:`str` to :obj:`str`, optional):
A map from constraining property to the value that the
:obj:`StatisticalPopulation` should be constrained by.
Returns:
When :code:`dcids` is an instance of :obj:`list`, the returned
:obj:`StatisticalPopulation` are formatted as a :obj:`dict` from a given
dcid to the unique :obj:`StatisticalPopulation` located at the dcid as
specified by the `population_type` and `constraining_properties` *if such
exists*. A given dcid will *NOT* be a member of the :obj:`dict` if such
a population does not exist.
When :code:`dcids` is an instance of :obj:`pandas.Series`, the returned
:obj:`StatisticalPopulation` are formatted as a :obj:`pandas.Series` where
the `i`-th entry corresponds to populations located at the given dcid
specified by the `population_type` and `constraining_properties` *if such
exists*. Otherwise, the cell is empty.
Raises:
ValueError: If the payload returned by the Data Commons REST API is
malformed.
Examples:
We would like to get
- The `population of employed persons in California <https://browser.datacommons.org/kg?dcid=dc/p/x6t44d8jd95rd>`_
- The `population of employed persons in Kentucky <https://browser.datacommons.org/kg?dcid=dc/p/fs929fynprzs>`_
- The `population of employed persons in Maryland <https://browser.datacommons.org/kg?dcid=dc/p/lr52m1yr46r44>`_.
These populations are specified as having a
`population_type` as :obj:`Person` and the `constraining_properties`
as `employment <https://browser.datacommons.org/kg?dcid=employment>`_
= BLS_Employed
With a :obj:`list` of dcids for our states, we can get the populations we
want as follows.
>>> dcids = ["geoId/06", "geoId/21", "geoId/24"]
>>> pvs = {'employment': 'BLS_Employed'}
>>> dc.get_populations(dcids, 'Person', constraining_properties=pvs)
{
"geoId/06": "dc/p/x6t44d8jd95rd",
"geoId/21": "dc/p/fs929fynprzs",
"geoId/24": "dc/p/lr52m1yr46r44"
}
We can also specify the :code:`dcids` as a :obj:`pandas.Series` like so.
>>> import pandas as pd
>>> dcids = pd.Series(["geoId/06", "geoId/21", "geoId/24"])
>>> pvs = {'employment': 'BLS_Employed'}
>>> dc.get_populations(dcids, 'Person', constraining_properties=pvs)
0 dc/p/x6t44d8jd95rd
1 dc/p/fs929fynprzs
2 dc/p/lr52m1yr46r44
dtype: object
"""
# Convert the dcids field and format the request to GetPopulations
dcids, req_dcids = utils._convert_dcids_type(dcids)
pv = [{
'property': k,
'value': v
} for k, v in constraining_properties.items()]
url = utils._API_ROOT + utils._API_ENDPOINTS['get_populations']
payload = utils._send_request(url,
req_json={
'dcids': req_dcids,
'population_type': population_type,
'pvs': pv,
})
# Create the results and format it appropriately
result = utils._format_expand_payload(payload,
'population',
must_exist=dcids)
if isinstance(dcids, pd.Series):
flattened = utils._flatten_results(result, default_value="")
return pd.Series([flattened[dcid] for dcid in dcids],
index=dcids.index)
# Drop empty results while flattening
return utils._flatten_results(result)
def get_observations(dcids,
measured_property,
stats_type,
observation_date,
observation_period=None,
measurement_method=None):
""" Returns values of :obj:`Observation`'s observing the given :code:`dcids`.
Args:
dcids (Union[:obj:`list` of :obj:`str`, :obj:`pandas.Series`]): Dcids
identifying nodes that returning :obj:`Observation`'s observe. These dcids
are treated as the property value associated with returned
:obj:`Observation`'s by the property
`observedNode <https://browser.datacommons.org/kg?dcid=observedNode>`_
measured_property (:obj:`str`): The measured property.
stats_type (:obj:`str`): The statistical type for the observation.
observation_date (:obj:`str`): The associated observation date in ISO8601
format.
observation_period (:obj:`str`, optional): An optional parameter specifying
the observation period.
measurement_method (:obj:`str`, optional): An optional parameter specifying
the measurement method.
Raises:
ValueError: If the payload returned by the Data Commons REST API is
malformed.
Returns:
When :code:`dcids` is an instance of :obj:`list`, the returned
:obj:`Observation`'s are formatted as a :obj:`dict` from a given dcid to the
unique :obj:`Observation` observing the dcid where the observation is
specified by what is given in the other parameters *if such exists*. A given
dcid will *NOT* be a member of the :obj:`dict` if such an observation does
not exist.
When :code:`dcids` is an instance of :obj:`pandas.Series`, the returned
:obj:`Observation`'s are formatted as a :obj:`pandas.Series` where the
`i`-th entry corresponds to observation observing the given dcid as specified
by the other parameters *if such exists*. Otherwise, the cell holds NaN.
Examples:
We would like to get the following for December, 2018:
- The `total count of employed persons in California <https://browser.datacommons.org/kg?dcid=dc/o/wetnm9026gf73>`_
- The `total count of employed persons in Kentucky <https://browser.datacommons.org/kg?dcid=dc/o/4nklvdnkfq835>`_
- The `total count of employed persons in Maryland <https://browser.datacommons.org/kg?dcid=dc/o/nkntbc4vpshn9>`_.
The observations we want are observations of the populations representing
employed individuals in each state (to get these, see
:any:module-datacommons.populations.get_populations). With a list of these
population dcids, we can get the observations like so.
>>> dcids = [
... "dc/p/x6t44d8jd95rd", # Employed individuals in California
... "dc/p/fs929fynprzs", # Employed individuals in Kentucky
... "dc/p/lr52m1yr46r44" # Employed individuals in Maryland
... ]
>>> get_observations(dcids, 'count', 'measuredValue', '2018-12',
... observation_period='P1M',
... measurement_method='BLSSeasonallyAdjusted'
... )
{
"dc/p/x6t44d8jd95rd": 18704962.0,
"dc/p/fs929fynprzs": 1973955.0,
"dc/p/lr52m1yr46r44": 3075662.0
}
We can also specify the :code:`dcids` as a :obj:`pandas.Series` like so.
>>> import pandas as pd
>>> dcids = pd.Series(["dc/p/x6t44d8jd95rd", "dc/p/fs929fynprzs", "dc/p/lr52m1yr46r44"])
>>> get_observations(dcids, 'count', 'measuredValue', '2018-12',
... observation_period='P1M',
... measurement_method='BLSSeasonallyAdjusted'
... )
0 18704962.0
1 1973955.0
2 3075662.0
dtype: float64
"""
# Convert the dcids field and format the request to GetObservation
dcids, req_dcids = utils._convert_dcids_type(dcids)
req_json = {
'dcids': req_dcids,
'measured_property': measured_property,
'stats_type': stats_type,
'observation_date': observation_date,
}
if observation_period:
req_json['observation_period'] = observation_period
if measurement_method:
req_json['measurement_method'] = measurement_method
# Issue the request to GetObservation
url = utils._API_ROOT + utils._API_ENDPOINTS['get_observations']
payload = utils._send_request(url, req_json=req_json)
# Create the results and format it appropriately
result = utils._format_expand_payload(payload,
'observation',
must_exist=dcids)
if isinstance(dcids, pd.Series):
flattened = utils._flatten_results(result, default_value="")
series = pd.Series([flattened[dcid] for dcid in dcids],
index=dcids.index)
return series.apply(pd.to_numeric, errors='coerce')
# Drop empty results by calling _flatten_results without default_value, then
# coerce the type to float if possible.
typed_results = {}
for k, v in utils._flatten_results(result).items():
try:
typed_results[k] = float(v)
except ValueError:
typed_results[k] = v
return typed_results
def get_places_in(dcids, place_type):
""" Returns :obj:`Place`s contained in :code:`dcids` of type
:code:`place_type`.
Args:
dcids (Union[:obj:`list` of :obj:`str`, :obj:`pandas.Series`]): Dcids to get
contained in places.
place_type (:obj:`str`): The type of places contained in the given dcids to
filter by.
Returns:
When :code:`dcids` is an instance of :obj:`list`, the returned
:obj:`Place`'s are formatted as a :obj:`dict` from a given dcid to a list of
places identified by dcids of the given `place_type`.
When :code:`dcids` is an instance of :obj:`pandas.Series`, the returned
:obj:`Place`'s are formatted as a :obj:`pandas.Series` where the `i`-th
entry corresponds to places contained in the place identified by the dcid
in `i`-th cell if :code:`dcids`. The cells of the returned series will always
contain a :obj:`list` of place dcids of the given `place_type`.
Raises:
ValueError: If the payload returned by the Data Commons REST API is
malformed.
Examples:
We would like to get all Counties contained in
`California <https://browser.datacommons.org/kg?dcid=geoId/06>`_. Specifying
the :code:`dcids` as a :obj:`list` result in the following.
>>> get_places_in(["geoId/06"], "County")
{
'geoId/06': [
'geoId/06041',
'geoId/06089',
'geoId/06015',
'geoId/06023',
'geoId/06067',
...
# and 53 more
]
}
We can also specify the :code:`dcids` as a :obj:`pandas.Series` like so.
>>> import pandas as pd
>>> dcids = pd.Series(["geoId/06"])
>>> get_places_in(dcids, "County")
0 [geoId/06041, geoId/06089, geoId/06015, geoId/...
dtype: object
"""
# Convert the dcids field and format the request to GetPlacesIn
dcids, req_dcids = utils._convert_dcids_type(dcids)
url = utils._API_ROOT + utils._API_ENDPOINTS['get_places_in']
payload = utils._send_request(url, req_json={
'dcids': req_dcids,
'place_type': place_type,
})
# Create the results and format it appropriately
result = utils._format_expand_payload(payload, 'place', must_exist=dcids)
if isinstance(dcids, pd.Series):
return pd.Series([result[dcid] for dcid in dcids])
return result
def get_populations(dcids, population_type, constraining_properties={}):
""" Returns :obj:`StatisticalPopulation`'s located at the given :code:`dcids`.
Args:
dcids (:obj:`iterable` of :obj:`str`): Dcids
identifying :obj:`Place`'s of populations to query for. These dcids are
treated as the property value associated with returned :obj:`Population`'s
by the property
`location <https://browser.datacommons.org/kg?dcid=location>`_
population_type (:obj:`str`): The population type of the
:obj:`StatisticalPopulation`
constraining_properties (:obj:`map` from :obj:`str` to :obj:`str`, optional):
A map from constraining property to the value that the
:obj:`StatisticalPopulation` should be constrained by.
Returns:
The returned :obj:`StatisticalPopulation` are formatted as a :obj:`dict` from a given
dcid to the unique :obj:`StatisticalPopulation` located at the dcid as
specified by the `population_type` and `constraining_properties` *if such
exists*. A given dcid will *NOT* be a member of the :obj:`dict` if such
a population does not exist.
Raises:
ValueError: If the payload returned by the Data Commons REST API is
malformed.
Examples:
We would like to get
- The `population of employed persons in California <https://browser.datacommons.org/kg?dcid=dc/p/x6t44d8jd95rd>`_
- The `population of employed persons in Kentucky <https://browser.datacommons.org/kg?dcid=dc/p/fs929fynprzs>`_
- The `population of employed persons in Maryland <https://browser.datacommons.org/kg?dcid=dc/p/lr52m1yr46r44>`_.
These populations are specified as having a
`population_type` as :obj:`Person` and the `constraining_properties`
as `employment <https://browser.datacommons.org/kg?dcid=employment>`_
= BLS_Employed
With a :obj:`list` of dcids for our states, we can get the populations we
want as follows.
>>> dcids = ["geoId/06", "geoId/21", "geoId/24"]
>>> pvs = {'employment': 'BLS_Employed'}
>>> dc.get_populations(dcids, 'Person', constraining_properties=pvs)
{
"geoId/06": "dc/p/x6t44d8jd95rd",
"geoId/21": "dc/p/fs929fynprzs",
"geoId/24": "dc/p/lr52m1yr46r44"
}
"""
# Convert the dcids field and format the request to GetPopulations
dcids = filter(lambda v: v == v, dcids) # Filter out NaN values
dcids = list(dcids)
pv = [{
'property': k,
'value': v
} for k, v in constraining_properties.items()]
url = utils._API_ROOT + utils._API_ENDPOINTS['get_populations']
payload = utils._send_request(url,
req_json={
'dcids': dcids,
'population_type': population_type,
'pvs': pv,
})
# Create the results and format it appropriately
result = utils._format_expand_payload(payload,
'population',
must_exist=dcids)
# Drop empty results while flattening
return _flatten_results(result)