add geographic_instances to time series (#103)

* add geographic_instances to time series 

* fixed geographic_instances docstring 

* Update geog extent docs for TSTs

* Black

---------

Co-authored-by: Finn Roberts <robe2037@umn.edu>

Author: qunderriner

docs/source/change-log.rst

@@ -10,6 +10,13 @@ This project adheres to `Semantic Versioning`_.
 
 .. _Semantic Versioning: http://semver.org/
 
+0.6.1
+-----
+
+* The IPUMS API now supports geographic extent selection for NHGIS time series tables.
+  Accordingly, a `geographic_instances` attribute has been added to the 
+  :py:class:`~ipumspy.api.metadata.TimeSeriesTableMetadata` class to store retrieved
+  geographic extent metadata for a given time series table.
 
 0.6.0
 -----

docs/source/ipums_api/ipums_api_aggregate/index.rst

@@ -151,37 +151,6 @@ The returned object will contain the metadata for the requested dataset. For exa
 
 You can also request metadata for individual data tables using the same workflow with the :class:`DataTableMetadata <ipumspy.api.metadata.DataTableMetadata>` data class.
 
-Geographic Extent Selection
-+++++++++++++++++++++++++++
-
-When working with small geographies it can be computationally intensive to work with
-nationwide data. To avoid this problem, you can request data from a specific geographic area 
-using the ``geographic_extents`` argument.
-
-The following extract requests ACS 5-year sex-by-age counts at the census block group level, but
-only includes block groups that fall within Alabama and Arkansas (identified by their FIPS codes with
-a trailing 0):
-
-.. code:: python
-
-   extract = AggregateDataExtract(
-      collection="nhgis",
-      description="Extent selection example",
-      datasets=[
-         Dataset(name="2018_2022_ACS5a", data_tables=["B01001"], geog_levels=["blck_grp"]),
-         Dataset(name="2017_2021_ACS5a", data_tables=["B01001"], geog_levels=["blck_grp"])
-      ],
-      geographic_extents=["010", "050"]
-   )
-
-.. tip::
-   You can see available extent selection API codes, if any, in the ``geographic_instances`` attribute of
-   a submitted :class:`DatasetMetadata <ipumspy.api.metadata.DatasetMetadata>` object.
-
-Note that extent selection is *not* a dataset-specific parameter. That is, the selected extents
-are applied to all datasets in the extract. It is not possible to request different extents for different
-datasets in a single extract.
-
 Time Series Tables
 ------------------
 
@@ -237,6 +206,37 @@ into separate files (by default, time is arranged across columns).
 As with datasets and data tables, you can request metadata about the available specification options
 for a specific time series table using the :class:`TimeSeriesTableMetadata <ipumspy.api.metadata.TimeSeriesTableMetadata>` class.
 
+Geographic Extent Selection
+---------------------------
+
+When working with small geographies it can be computationally intensive to work with
+nationwide data. To avoid this problem, you can request data from a specific geographic area 
+using the ``geographic_extents`` argument
+
+The following extract requests ACS 5-year sex-by-age counts at the census block group level, but
+only includes block groups that fall within Alabama and Arkansas (identified by their FIPS codes with
+a trailing 0):
+
+.. code:: python
+
+   extract = AggregateDataExtract(
+      collection="nhgis",
+      description="Extent selection example",
+      datasets=[
+         Dataset(name="2018_2022_ACS5a", data_tables=["B01001"], geog_levels=["blck_grp"]),
+         Dataset(name="2017_2021_ACS5a", data_tables=["B01001"], geog_levels=["blck_grp"])
+      ],
+      geographic_extents=["010", "050"]
+   )
+
+.. tip::
+   You can see available extent selection API codes, if any, in the ``geographic_instances`` attribute of
+   a submitted :class:`DatasetMetadata <ipumspy.api.metadata.DatasetMetadata>` or 
+   :class:`TimeSeriesTableMetadata <ipumspy.api.metadata.TimeSeriesTableMetadata>` object.
+
+Note that the selected extents are applied to all datasets and time series tables in an extract. 
+It is not possible to request different extents for different data sources in a single extract.
+
 Shapefiles
 ----------
 
@@ -317,7 +317,7 @@ Many NHGIS supplemental data files can be found under the "Supplemental Data" he
 for all supported supplemental data endpoints and advice on how to convert file URLs found on the website into
 acceptable API request URLs.
 
-Once you've identified a file's location, you can use the``ipumspy`` :py:meth:`.get` method to download it. For
+Once you've identified a file's location, you can use the ipumspy :py:meth:`.get` method to download it. For
 instance, to download a state-level NHGIS crosswalk file, we could use the following:
 
 .. code:: python

src/ipumspy/api/extract.py

@@ -712,9 +712,9 @@ def __init__(
             shapefiles: list of shapefile names
             description: short description of your extract
             data_format: desired format of the extract data file. One of ``"csv_no_header"``, ``"csv_header"``, or ``"fixed_width"``.
-            geographic_extents: Geographic extents to use for all ``datasets`` in the extract definition (for instance, to
-                                to obtain data within a particular state). Use ``['*']`` to select all available extents. Note that
-                                not all geographic levels support extent selection.
+            geographic_extents: Geographic extents to use for all ``datasets`` and ``time_series_tables`` in the extract definition (for instance, to
+                                to obtain data within a particular state). Note that geographic extent selection is only supported for geographies
+                                that nest within states.
             tst_layout: desired data layout for all  ``time_series_tables`` in the extract definition.
                         One of ``"time_by_column_layout"`` (default), ``"time_by_row_layout"``, or ``"time_by_file_layout"``.
             breakdown_and_data_type_layout: desired layout of any ``datasets`` that have multiple data types or breakdown values. Either

src/ipumspy/api/metadata.py

@@ -81,8 +81,8 @@ class DatasetMetadata(IpumsMetadata):
     """
     geographic_instances: Optional[List[Dict]] = field(default=None, init=False)
     """
-    Dictionary containing names and descriptions for all valid geographic extents 
-        for the dataset
+    Dictionary containing names and descriptions for the geographic extents available for the
+        dataset, if any
     """
     breakdowns: Optional[List[Dict]] = field(default=None, init=False)
     """
@@ -129,6 +129,8 @@ class TimeSeriesTableMetadata(IpumsMetadata):
     """Dictionary containing information on the available data years for the time series table"""
     geog_levels: Optional[List[Dict]] = field(default=None, init=False)
     """Dictionary containing names and descriptions for the geographic levels available for the time series table"""
+    geographic_instances: Optional[List[Dict]] = field(default=None, init=False)
+    """Dictionary containing names and descriptions for all valid geographic extents available for any year in the time series table"""
 
     def __post_init__(self):
         self._path = f"metadata/time_series_tables/{self.name}"