Merge pull request #81 from StratoDem/78-drivetime

78 drivetime

Author: mjclawar

CHANGELOG.md

@@ -2,6 +2,30 @@
 
 All notable changes to this project will be documented in this file. This project adheres to [Semantic Versioning](http://semver.org/).
 
+## [3.3.0] - 2019-09-18
+### Adds
+- Adds new buffer types to the `DrivetimeFilter`. It now supports:
+    - `'drivetime'`
+    - `'drivetime_simple'`
+    - `'drivetime_unweighted'`
+    - `'drivetime_destination'`
+    - `'drivetime_destination_simple'`
+    - `'drivetime_destination_unweighted'`
+- Adds a `WalktimeFilter` which supports the following types:
+    - `'walktime'`
+    - `'walktime_unweighted'`
+    - `'walktime_destination'`
+    - `'walktime_destination_unweighted'`
+- Adds `detailed_type` as a new optional argument to `OverlapsDrivetimeFilter` which allows:
+    - `'overlaps_drivetime'`  
+    - `'overlaps_drivetime_destination'`
+- Adds `detailed_type` as a new optional argument to `OverlapsWalktimeFilter` which allows:
+    - `'overlaps_walktime'`  
+    - `'overlaps_walktime_destination'`  
+
+## Related issues
+- [69](https://github.com/StratoDem/strato-query/issues/69)
+
 ## [3.2.0] - 2019-09-10
 ### Adds
 - Adds new query param classes

setup.py

@@ -13,7 +13,7 @@
 
 setup(
     name='strato_query',
-    version='3.2.0',
+    version='3.3.0',
     author='Michael Clawar, Raaid Arshad, Eric Linden',
     author_email='tech@stratodem.com',
     packages=[

strato_query/examples/examples.py

@@ -58,6 +58,36 @@ def example_count_query(cls):
         print(df.head())
         print('Results truncated')
 
+    @classmethod
+    def example_count_query_destination(cls):
+        # Number of households ages 25-39 with net worth of at least $50,000
+        # within 20-minute drive to a location South of Boston in the year 2017
+
+        df = cls.query_api_df(
+            query_params=APIQueryParams(
+                query_type='COUNT',
+                table='networth_tract_annual_net_worth_age',
+                data_fields=('year', 'age_g_bottom_coded', 'net_worth_g', 'households'),
+                data_filters=(
+                    BetweenFilter(var='age_g_bottom_coded', val=[6, 8]).to_dict(),
+                    GreaterThanOrEqualToFilter(var='net_worth_g', val=3).to_dict(),
+                    EqualToFilter(var='year', val=2017).to_dict(),
+                    DrivetimeFilter(
+                        latitude=42.256922,
+                        longitude=-71.040571,
+                        detailed_type='drivetime_destination',
+                        minutes=20).to_dict(),
+                ),
+                groupby=(),
+                order=(),
+                aggregations=(),
+            )
+        )
+
+        print('Number of households 25-39 with $50k+ net worth in 2017 in a 20 min drive to coord:')
+        print(df.head())
+        print('Results truncated')
+
     @classmethod
     def example_query_with_area_join_and_aggregation(cls):
         # Population density in the Boston MSA by year prior to 2015
@@ -271,6 +301,8 @@ def example_pure_shape_union_query(cls):
 def run_examples():
     ExampleQueries.example_count_query()
     print('\n\n')
+    ExampleQueries.example_count_query_destination()
+    print('\n\n')
     ExampleQueries.example_query_with_area_join_and_aggregation()
     print('\n\n')
     ExampleQueries.example_median_query()

strato_query/filters.py

@@ -25,6 +25,7 @@
     'NotEqualToFilter',
     'NotInFilter',
     'DrivetimeFilter',
+    'WalktimeFilter',
     'MileRadiusFilter',
     'IntersectsFilter',
     'OverlapsMileRadiusFilter',
@@ -166,20 +167,33 @@ def __init__(self,
         longitude: float
             Center longitude
         minutes: int or float
-            Minutes drive from latitude-longitude center
+            Minutes drive from or to latitude-longitude center
         detailed_type: str
             One of:
             - 'drivetime': use a normal drivetime, which weights results
             - 'drivetime_simple': use a drivetime with weights, but using simplified shapes
             - 'drivetime_unweighted': return unweighted results (used to get all geographies
                 intersecting at all with the drive time area)
+            - 'drivetime_destination': use a normal drivetime, which weights results, but the
+                location is the destination instead of the start point
+            - 'drivetime_destination_simple': use a drivetime with weights, but using simplified
+                shapes, and the location as the destination
+            - 'drivetime_destination_unweighted': return unweighted results (used to get all
+                geographies intersecting at all with the drive time area), and use the location as
+                the destination
         with_traffic: bool
             Use traffic estimates to compute the drive time area?
         start_time: str
             The departure time for the drivetime, used in concert with "with_traffic" set to True
             e.g., "2019-05-25T18:00:00"
         """
-        assert detailed_type in {'drivetime', 'drivetime_simple', 'drivetime_unweighted'}
+        assert detailed_type in {
+            'drivetime',
+            'drivetime_simple',
+            'drivetime_unweighted',
+            'drivetime_destination',
+            'drivetime_destination_simple',
+            'drivetime_destination_unweighted'}
         assert isinstance(with_traffic, bool)
         assert start_time is None or isinstance(start_time, str)
 
@@ -194,6 +208,49 @@ def __init__(self,
                 start_time=start_time))
 
 
+class WalktimeFilter(BaseFilter):
+    def __init__(self,
+                 latitude: float,
+                 longitude: float,
+                 minutes: Union[int, float],
+                 detailed_type: str = 'walktime'):
+        """
+        Filter a query to geographies contained by the walktime area
+
+        Parameters
+        ----------
+        latitude: float
+            Center latitude
+        longitude: float
+            Center longitude
+        minutes: int or float
+            Minutes walk from latitude-longitude center
+        detailed_type: str
+            One of:
+            - 'walktime': use a normal walktime, which weights results
+            - 'walktime_unweighted': return unweighted results (used to get all geographies
+                intersecting at all with the walk time area)
+            - 'walktime_destination': use a normal walktime, which weights results, but the
+                location is the destination instead of the start point
+            - 'walktime_destination_unweighted': return unweighted results (used to get all
+                geographies intersecting at all with the walk time area), and use the location as
+                the destination
+        """
+        assert detailed_type in {
+            'walktime',
+            'walktime_unweighted',
+            'walktime_destination',
+            'walktime_destination_unweighted'}
+
+        super().__init__(
+            filter_type=detailed_type,
+            filter_variable='',
+            filter_value=dict(
+                latitude=latitude,
+                longitude=longitude,
+                minutes=minutes))
+
+
 class IntersectsFilter(BaseFilter):
     def __init__(self, var: str, val: dict):
         super().__init__(
@@ -240,6 +297,7 @@ def __init__(self,
                  latitude: float,
                  longitude: float,
                  minutes: Union[int, float],
+                 detailed_type: str = 'overlaps_drivetime',
                  with_traffic: bool = False,
                  start_time: Optional[str] = None):
         """
@@ -252,7 +310,9 @@ def __init__(self,
         latitude: float
         longitude: float
         minutes: int or float
-            Minutes drive from latitude-longitude center
+            Minutes drive from or to the latitude-longitude center
+        detailed_type: str
+            One of either "overlaps_drivetime" or "overlaps_drivetime_destination"
         with_traffic: bool
             Use traffic estimates to compute the drive time area?
         start_time: str
@@ -265,9 +325,10 @@ def __init__(self,
         assert isinstance(minutes, (int, float))
         assert with_traffic is None or isinstance(with_traffic, bool)
         assert start_time is None or isinstance(start_time, str)
+        assert detailed_type in {'overlaps_drivetime', 'overlaps_drivetime_destination'}
 
         super().__init__(
-            filter_type='overlaps_drivetime',
+            filter_type=detailed_type,
             filter_variable=var,
             filter_value=dict(
                 latitude=latitude,
@@ -282,7 +343,8 @@ def __init__(self,
                  var: str,
                  latitude: float,
                  longitude: float,
-                 minutes: Union[int, float]):
+                 minutes: Union[int, float],
+                 detailed_type: str = 'overlaps_walktime'):
         """
         Filter a query by geometries overlapping the point's surrounding buffer
 
@@ -294,14 +356,17 @@ def __init__(self,
         longitude: float
         minutes: int or float
             Minutes walk from latitude-longitude center
+        detailed_type: str
+            One of either "overlaps_walktime" or "overlaps_walktime_destination"
         """
         assert isinstance(var, str)
         assert isinstance(latitude, float)
         assert isinstance(longitude, float)
         assert isinstance(minutes, (int, float))
+        assert detailed_type in {'overlaps_walktime', 'overlaps_walktime_destination'}
 
         super().__init__(
-            filter_type='overlaps_walktime',
+            filter_type=detailed_type,
             filter_variable=var,
             filter_value=dict(
                 latitude=latitude,