### Install censusdis using pip

Source: https://censusdis.readthedocs.io/en/latest/_sources/intro.rst.txt

Use this command to install the censusdis package in your Python environment.

```bash
pip install censusdis
```

--------------------------------

### Fetch Certificates

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Retrieves certificates from the censusdis.impl.fetch module. No specific setup is required beyond importing the module.

```python
certificates = censusdis.impl.fetch.certificates
```

--------------------------------

### Import censusdis and set up query parameters

Source: https://censusdis.readthedocs.io/en/latest/_sources/intro.rst.txt

Import the censusdis.data module and define constants for the dataset, year, and variables to be queried. This setup is necessary before making any data requests.

```python
import censusdis.data as ced

# American Community Survey 5-Year Data
# https://www.census.gov/data/developers/data-sets/acs-5year.html
DATASET = "acs/acs5"

# The year we want data for.
YEAR = 2020

# This are the census variables for total population and median household income.
# For more details, see
#
#     https://api.census.gov/data/2020/acs/acs5/variables.html,
#     https://api.census.gov/data/2020/acs/acs5/variables/B01003_001E.html, and
#     https://api.census.gov/data/2020/acs/acs5/variables/B19013_001E.html.
#
TOTAL_POPULATION_VARIABLE = "B01003_001E"
MEDIAN_HOUSEHOLD_INCOME_VARIABLE = "B19013_001E"

# The variables we are going to query.
VARIABLES = ["NAME", TOTAL_POPULATION_VARIABLE, MEDIAN_HOUSEHOLD_INCOME_VARIABLE]
```

--------------------------------

### PlotSpec YAML Loading Setup

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Provides a class method to set up a YAML loader that can deserialize '!PlotSpec' tags, enabling loading of PlotSpec objects from YAML files.

```python
    @classmethod
    def _yaml_loader(cls):
        loader = yaml.SafeLoader
        loader.add_constructor("!PlotSpec", _class_constructor(cls))
        return loader
```

--------------------------------

### Get Variables to Download from VariableSpecCollection

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Returns a unique list of all variables that need to be downloaded from the U.S. Census API by aggregating variables from all constituent VariableSpec objects.

```python
def variables_to_download(self) -> List[str]:
        """
        Return a list of the variables that need to be downloaded from the U.S. Census API.

        Returns all the variables to be downloaded by the :py:class:`~VariableSpec`'s
        in the collection.
        """
        return list(
            set(
                itertools.chain(
                    *[spec.variables_to_download() for spec in self._variable_specs]
                )
            )
        )
```

--------------------------------

### Get Groups to Download from VariableSpecCollection

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Returns a unique list of group names to be downloaded from the U.S. Census API by aggregating groups from all constituent VariableSpec objects.

```python
def groups_to_download(self) -> List[Tuple[str, bool]]:
        """
        Return the names of groups of variables that need to be downloaded from the U.S. Census API.

        The result is a list of the unique groups returned by all the :py:class:`~VariableSpec`'s
        given at construction time.

        Returns
        -------
            The names of groups to download.
        """
        return list(
            set(
                itertools.chain(
                    *[spec.groups_to_download() for spec in self._variable_specs]
                )
            )
        )
```

--------------------------------

### Get Geography Specifications

Source: https://censusdis.readthedocs.io/en/latest/_sources/intro.rst.txt

Use this to retrieve a dictionary of supported geography paths for a given dataset and year. This helps in understanding how to specify geographic arguments in queries.

```python
import censusdis.geography as cgeo

specs = cgeo.geo_path_snake_specs(DATASET, YEAR)
```

--------------------------------

### Get State FIPS Code by Abbreviation

Source: https://censusdis.readthedocs.io/en/latest/states.html

Use state abbreviations directly to get their corresponding FIPS codes. This is useful when you need the numeric identifier for an API.

```python
from censusdis import states

state = states.NJ
```

--------------------------------

### Download County Data for a Specific State

Source: https://censusdis.readthedocs.io/en/latest/_sources/intro.rst.txt

Use the `state` and `county` arguments in `ced.download` to retrieve data for a specific state and county level. This is useful when you need data for a smaller geographic area than the entire country.

```python
from censusdis import states

df_counties = ced.download(
    DATASET,
    YEAR,
    VARIABLES,
    state=states.NJ,
    county="*",
)
```

--------------------------------

### censusdis.data.geography_names

Source: https://censusdis.readthedocs.io/en/latest/data.html

Get the name of a specific geography. This function is useful for fetching human-readable names when only the FIPS code is known.

```APIDOC
## geography_names

### Description
Get the name of a specific geography.
The arguments are a subset of those to `download()`. This function is designed to make it easy to fetch the name of a geography when we know the FIPS code but want a human-readable name or label for display. 

### Method
`censusdis.data.geography_names(_dataset : str_, _vintage : int | Literal['timeseries']_, _** kwargs: str | Iterable[str]_)`

### Parameters
#### Path Parameters
- **dataset** (str) - Required - The dataset to download from. For example censusdis.datasets.ACS5.
- **vintage** (int | Literal['timeseries']) - Required - The vintage to download data for. For example, 2020.

#### Keyword Arguments
- **kwargs** (str | Iterable[str]) - Required - A specification of the geometry that we want data for. For example, state = “34”, county = “017” will download the name of Hudson County, New Jersey.

### Returns
- A dataframe with columns specifying the geography and one for the name.
- All column names will be in ALL CAPS.
```

--------------------------------

### Synthesize Fractional Variables in VariableList

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Post-processes downloaded data to compute fractional variables based on a specified denominator. Adds new columns to the DataFrame in-place.

```python
def synthesize(self, df_downloaded: Union[pd.DataFrame, gpd.GeoDataFrame]):
        """
        Post-process after downloading to compute variables like fractional variables are constructed.

        This is where fractional variables are generated.

        Parameters
        ----------
        df_downloaded
            A data frame of variables that were downloaded. Any systhesized variables
            are added as new columns.

        Returns
        -------
            None. Any additions are made in-place in `df_downloaded`.
        """
        if not self.denominator:
            return df_downloaded

        if isinstance(self.denominator, str):
            for variable in self._variables:
                frac = df_downloaded[variable] / df_downloaded[self.denominator]
                if self.frac_not:
                    df_downloaded[f"{self.frac_prefix}{variable}"] = 1.0 - frac
                else:
                    df_downloaded[f"{self.frac_prefix}{variable}"] = frac
        elif self.denominator:
            denominator = df_downloaded[self._variables].sum(axis="columns")
            for variable in self._variables:
                frac = df_downloaded[variable] / denominator
                if self.frac_not:
                    df_downloaded[f"{self.frac_prefix}{variable}"] = 1.0 - frac
                else:
                    df_downloaded[f"{self.frac_prefix}{variable}"] = frac
```

--------------------------------

### geography_names

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Get the name of a specific geography. This function is useful for fetching a human-readable name or label for a geography when you know its FIPS code.

```APIDOC
## geography_names

### Description
Get the name of a specific geography. The arguments are a subset of those to :py:func:`~download`. This function is designed to make it easy to fetch the name of a geography when we know the FIPS code but want a human-readable name or label for display.

### Parameters
#### Path Parameters
- **dataset** (str) - Required - The dataset to download from. For example `censusdis.datasets.ACS5`.
- **vintage** (VintageType) - Required - The vintage to download data for. For example, `2020`.
#### Query Parameters
- **kwargs** (cgeo.InSpecType) - Required - A specification of the geometry that we want data for. For example, `state = "34", county = "017"` will download the name of Hudson County, New Jersey.

### Returns
A dataframe with columns specifying the geography and one for the name. All column names will be in ALL CAPS.
```

--------------------------------

### Initialize VariableList

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Initializes a VariableList specification for downloading US Census API variables. Supports defining fractional variables using a denominator.

```python
def __init__(
    self,
    variables: Union[str, Iterable[str]],
    *,
    denominator: Union[str, bool] = False,
    frac_prefix: Optional[str] = None,
    frac_not: Optional[bool] = False,
):
    super().__init__(
        denominator=denominator, frac_prefix=frac_prefix, frac_not=frac_not
    )
    if isinstance(variables, str):
        variables = [variables]
    self.variables = variables
```

--------------------------------

### Get CRS Bounds Dataframe

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Constructs and returns a singleton GeoDataFrame containing the bounds of all CRSs used in the `plot_map` function. This is a utility for CRS selection.

```python
__gdf_crs_bounds: Optional[gpd.GeoDataFrame] = None
"""The bounds of the all CRSs we might use in `plot_map`. """


def _gdf_crs_bounds() -> gpd.GeoDataFrame:
    """
    Construct a dataframe witn the bound of all the CRSs we might use in `plot_map`.

    Returns
    -------
        The dataframe. It is a singleton you should not modify.
    """
    global __gdf_crs_bounds

    if __gdf_crs_bounds is None:
        with importlib.resources.path(
            f"{__package__}.resources", "crs_bounds.geojson"
        ) as path:
            __gdf_crs_bounds = gpd.GeoDataFrame.from_file(path)

    return __gdf_crs_bounds
```

--------------------------------

### Get Geography Names

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Fetches human-readable names for a specific geography using its FIPS code. Useful when only the FIPS code is known and a display name is needed.

```python
def geography_names(
    dataset: str,
    vintage: VintageType,
    **kwargs: cgeo.InSpecType,
) -> pd.DataFrame:
    """
    Get the name of a specific geography.

    The arguments are a subset of those to :py:func:`~download`. This
    function is designed to make it easy to fetch the name of a geography
    when we know the FIPS code but want a human-readable name or label for
    display.

    Parameters
    ----------
    dataset
        The dataset to download from. For example `censusdis.datasets.ACS5`.
    vintage
        The vintage to download data for. For example, `2020`.
    kwargs
        A specification of the geometry that we want data for. For example,
        `state = "34", county = "017"` will download the name of Hudson County,
        New Jersey.

    Returns
    -------
        A dataframe with columns specifying the geography and one for the name.
        All column names will be in ALL CAPS.
    """
    df = download(dataset, vintage, ["NAME"], **kwargs)

    return df

```

--------------------------------

### Initialize ShapeReader

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Initializes the ShapeReader class, setting up the local directory for shapefile storage. It can automatically fetch remote shape files if needed.

```python
shapefile_root = Path.home() / ".censusdis" / "data" / "shapefiles"
shapefile_root.mkdir(exist_ok=True, parents=True)
```

--------------------------------

### Download Census Data with Geographic Filters

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Demonstrates how to download census data for specific states using geographic filters. Accepts single state strings or iterables of states.

```python
import censusdis.data as ced
from censusdis.states import NJ, NY, CT

# Download data for a single state
df_one_state = ced.download("aca/acs5", 2020, ["NAME"], state=NJ)

# Download data for multiple states
df_tri_state = ced.download("aca/acs5", 2020, ["NAME"], state=[NJ, NY, CT])
```

--------------------------------

### PlotSpec Constructor

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Initializes a PlotSpec object, which defines how to plot downloaded data.

```APIDOC
## __init__ (PlotSpec)

### Description
Initializes a PlotSpec object for plotting data.

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **variable** (Optional[str]) - What variable to plot. Specify this to shade geographies based on the value of the variable. Leave out and set `boundary=True` to plot boundaries instead.
- **boundary** (bool) - Should we plot boundaries instead of filled geographies? If `True`, `variable` should not be specified. Defaults to `False`.
- **title** (Optional[str]) - A title for the plot.
- **with_background** (bool) - If `True`, plot over a background map. Defaults to `False`.
- **plot_kwargs** (Optional[Dict[str, Any]]) - Additional keyword args for matplotlib to use in plotting.
- **projection** (Optional[str]) - What projection to use. "US" means move AK, HI, and PR. `None` means use what the map is already in. Anything else is interpreted as an EPSG. Defaults to "US".
- **legend** (bool) - If `True` and plotting a variable (not a boundary) then add a legend. Defaults to `True`.
- **legend_format** (Optional[str]) - How to format the numbers on the legend. The options are "float", "int", "dollar", "percent", or a format string like "${x:.2f}" to choose any Python string format you want.

### Request Example
None

### Response
#### Success Response (200)
None

#### Response Example
None
```

--------------------------------

### Get State Name from FIPS Code

Source: https://censusdis.readthedocs.io/en/latest/states.html

Retrieve the human-friendly state name using its FIPS code. This is helpful for displaying state information in a readable format.

```python
from censusdis import states

state = states.CA

print(
    f"The name of the state with ID '{state}' "
    f"is '{states.NAMES_FROM_IDS[state]}'."
)
```

--------------------------------

### Fetch and Unzip Shapefile

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Downloads a zip archive containing shapefile data from a given URL, saves it, and then extracts its contents. It includes error handling for missing files and incorrect content types, and cleans up the zip file after extraction.

```python
def _fetch_file(
        self,
        name: str,
        base_url: str,
        *, 
        timeout: int,
    ) -> None:
        dir_path = self._shapefile_root / name

        if dir_path.is_dir():
            # Does it have the .shp file? If not maybe something
            # random went wrong in the previous attempt, or someone
            # deleted some stuff by mistake. So delete it and
            # reload.
            shp_path = dir_path / f"{name}.shp"
            if shp_path.is_file():
                # Looks like the shapefile is there.
                return

            # No shapefile so remove the whole directory and
            # hope for the best when we recreate it.
            shutil.rmtree(dir_path)

        # Make the directory
        dir_path.mkdir()

        # We will put the zip file in the dir we just created.
        zip_path = dir_path / f"{name}.zip"

        # Construct the URL to get the zip file.
        # url = self._url_for_file(name)
        zip_url = f"{base_url}/{name}.zip"

        # Fetch the zip file and write it.
        response = requests.get(
            zip_url,
            timeout=timeout,
            cert=certificates.map_cert,
            verify=certificates.map_verify,
        )

        if response.status_code == 404:
            raise MapException(
                f"{zip_url} was not found. "
                "The Census Bureau may not publish the shapefile you are looking for for the given year. "
                "Or the file you are looking for may be from a year where a naming convention that censusdis "
                "does not recognize was used."
            )

        headers = response.headers
        content_type = headers.get("Content-Type", None)

        if content_type != "application/zip":
            raise MapException(
                f"Expected content type application/zip' from {zip_url}, but got '{content_type}' instead."
            )

        with zip_path.open("wb") as file:
            file.write(response.content)

        # Unzip the file and extract all contents.
        try:
            with ZipFile(zip_path) as zip_file:
                zip_file.extractall(dir_path)
        except BadZipFile as exc:
            raise MapException(f"Bad zip file retrieved from {zip_url}") from exc
        finally:
            # We don't need the zipfile anymore.
            zip_path.unlink()
```

--------------------------------

### Get Groups to Download in CensusGroup

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Returns the names of variable groups to be downloaded from the U.S. Census API, along with a flag indicating whether to fetch only leaf variables.

```python
def groups_to_download(self) -> List[Tuple[str, bool]]:
        """
        Return the names of groups of variables that need to be downloaded from the U.S. Census API.

        The returned value are simply the groups specificed at construction time.

        Returns
        -------
            The names of groups to download.
        """
        return [(group, self._leaves_only) for group in self._group]
```

--------------------------------

### download()

Source: https://censusdis.readthedocs.io/en/latest/data.html

Downloads data, likely from a specified source or based on certain criteria.

```APIDOC
## Function: download()

### Description
Downloads data from a specified source or based on defined criteria.

### Parameters
None explicitly documented.

### Returns
Downloaded data.
```

--------------------------------

### DataSpec Class Initialization

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Initializes a DataSpec object to define data download parameters from the U.S. Census API. Specify dataset, vintage, variables, and geography. Optional parameters include contained_within, area_threshold, with_geometry, and remove_water.

```python
def __init__(
    self,
    dataset: str,
    vintage: VintageType,
    specs: Union[VariableSpec, Iterable[VariableSpec]],
    geography: Dict[str, Union[str, List[str]]],
    *,
    contained_within: Optional[Dict[str, Union[str, List[str]]]] = None,
    area_threshold: float = 0.8,
    with_geometry: bool = False,
    remove_water: bool = False,
):
    # Map symbolic names or use what we are given if there is no mapping.
    self._dataset = getattr(censusdis.datasets, dataset, dataset)
    self._vintage = vintage
    # If it is a raw list construct a collection around it.
    self._variable_spec = (
        specs if isinstance(specs, VariableSpec) else VariableSpecCollection(specs)
    )
    self._geography = self.map_state_and_county_names(geography)

    if contained_within is None:
        self._contained_within = None
    else:
        contained_within = self.map_state_and_county_names(contained_within)
        self._contained_within = ced.ContainedWithin(
            area_threshold, **contained_within
        )

    self._with_geometry = with_geometry
    self._remove_water = remove_water
```

--------------------------------

### _download_multiple

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Internal function to download data in batches and concatenate results, used when the number of variables exceeds the API limit.

```APIDOC
## _download_multiple

### Description
Downloads data in groups of columns (up to 50 at a time) and concatenates the results. This is necessary because the Census API has a limit on the number of columns per query.

### Parameters
- **dataset** (str) - The dataset to download from.
- **vintage** (VintageType) - The vintage to download data for.
- **download_variables** (List[str]) - The census variables to download.
- **query_filter** (Dict[str, str]) - A dictionary of values to filter on (server-side).
- **api_key** (Optional[str]) - Your US Census API key.
- **census_variables** (VariableCache) - A VariableCache instance.
- **with_geometry** (bool) - If True, a GeoDataFrame will be returned with geometry.
- **with_geometry_columns** (bool) - If True, includes geometry-related columns.
- **tiger_shapefiles_only** (bool) - If True, uses only TIGER shapefiles for geometry.
- **row_keys** (Union[str, Iterable[str]]) - Keys to identify rows.
- **kwargs** (cgeo.InSpecType) - Additional geographic filter specifications.

### Response
- **DataFrame** (pd.DataFrame) - The downloaded data, concatenated from multiple API calls.
```

--------------------------------

### Rename Columns in GeoDataFrame

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Applies a mapping function to rename columns in a GeoDataFrame. This is used to standardize column names, for example, by removing the year suffix from TIGER/Line shapefile column names.

```python
def mapper(col: str) -> str:
    if col.endswith(("20", "10", "00")):
        return col[:-2]
    return col

gdf.rename(mapper, axis="columns", inplace=True)
```

--------------------------------

### DataSpec.load_yaml

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Loads a DataSpec configuration from a YAML file.

```APIDOC
## load_yaml

### Description
Load a YAML file containing a `DataSpec`.

### Parameters
#### Path Parameters
- **path** (Union[str, Path]) - The path to the YAML file.

#### Query Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **DataSpec** - A `DataSpec` object loaded from the YAML file.

#### Response Example
None
```

--------------------------------

### Load YAML Specification

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Loads a YAML file containing a VariableSpec. Ensure the YAML file is correctly formatted and uses the supported constructors.

```python
loader = cls._yaml_loader()

loaded = yaml.load(open(path, "rb"), Loader=loader)

return loaded
```

--------------------------------

### Construct Census API Download URL

Source: https://censusdis.readthedocs.io/en/latest/data.html

Builds a URL for downloading data from the U.S. Census API. Specify the dataset, vintage, and variables. Server-side filtering can be applied using `query_filter` for efficiency.

```python
censusdis.data.census_table_url(_dataset : str_, _vintage : int | Literal['timeseries']_, _download_variables : Iterable[str]_, _*_ , _query_filter : Dict[str, str] | None = None_, _api_key : str | None = None_, _** kwargs: str | Iterable[str]_) → Tuple[str, Mapping[str, str], BoundGeographyPath][source]
```

--------------------------------

### Expand Download Variables

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Expands a list of download variables by including group variables and leaves of groups. Handles single string inputs and ensures order is maintained after deduplication.

```python
def expand_download_variables(
    dataset: str,
    vintage: VintageType,
    download_variables: Optional[Union[str, Iterable[str]]],
    *,  # Force keyword-only arguments
    group: Optional[Union[str, Iterable[str]]] = None,
    leaves_of_group: Optional[Union[str, Iterable[str]]] = None,
    skip_annotations: bool = False,
    variable_cache: VariableCache,
) -> List[str]:
    """
    Expand a list of download variables by including group variables and leaves of groups.

    Parameters
    ----------
    dataset
        The dataset to download from. For example ``"acs/acs5"``,
        ``"dec/pl"``, or ``"timeseries/poverty/saipe/schdist"``.
    vintage
        The vintage to download data for. For most data sets this is
        an integer year, for example, ``2020``. But for
        a timeseries data set, pass the string ``'timeseries'``.
    download_variables
        The census variables to download, for example ``["NAME", "B01001_001E"]``.
        Can be a single variable name as a string, or an iterable of variable
        names.
    group
        A list of group names to download variables from. See
        :py:meth:`VariableCache.group_variables` for more details on the semantics
        of group variables.
    leaves_of_group
        A list of group names to download the leaves of. See
        :py:meth:`VariableCache.group_leaves` for more details on the semantics of
        leaves vs. non-leaf group variables.
    skip_annotations
        If `True` try to filter out `group` or `leaves_of_group` variables that are
        annotations rather than actual values. See :py:meth:`VariableCache.group_variables`
        for more details. Variable names passed in `download_variables` are not
        affected by this flag.
    variable_cache
        A cache of metadata about variables.

    Returns
    -------
        The fully expanded list of variables to download.
    """
    # Turn the variables we were given into a list if they are not already.
    if download_variables is None:
        download_variables = []
    elif isinstance(download_variables, str):
        download_variables = [download_variables]
    elif not isinstance(download_variables, list):
        download_variables = list(download_variables)

    if group is None:
        group = []
    elif isinstance(group, str):
        group = [group]

    if leaves_of_group is None:
        leaves_of_group = []
    elif isinstance(leaves_of_group, str):
        leaves_of_group = [leaves_of_group]

    # Add group variables and leaves as appropriate.
    group_variables: List[str] = []
    for group_name in group:
        group_variables = group_variables + variable_cache.group_variables(
            dataset, vintage, group_name, skip_annotations=skip_annotations
        )
    group_leaf_variables: List[str] = []
    for group_name in leaves_of_group:
        group_leaf_variables = group_leaf_variables + variable_cache.group_leaves(
            dataset, vintage, group_name, skip_annotations=skip_annotations
        )

    # Concatenate them all.
    download_variables = download_variables + group_variables + group_leaf_variables

    # Dedup and maintain order.
    download_variables = list(dict.fromkeys(download_variables))

    return download_variables

```

--------------------------------

### censusdis.data.download()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Downloads data from the censusdis API.

```APIDOC
## download()

### Description
Initiates a download of data from the censusdis service. This is a general download function.

### Method
`download()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage
download_data()
```

### Response
None explicitly documented. Likely returns downloaded data or a status.
```

--------------------------------

### State Constants and Utilities

Source: https://censusdis.readthedocs.io/en/latest/states.html

Access predefined constants for US states, District of Columbia, and Puerto Rico, along with utility functions for converting between state IDs, abbreviations, and names.

```APIDOC
## State Data Access and Conversion

This module provides direct access to state data and utility functions for conversions.

### Constants

- **`ALL_STATES`**: A list of all US states.
- **`ALL_STATES_AND_DC`**: A list of all US states and the District of Columbia.
- **`ALL_STATES_DC_AND_PR`**: A list of all US states, the District of Columbia, and Puerto Rico.
- **`AK`**: Abbreviation for Alaska.
- **`AL`**: Abbreviation for Alabama.
- **`AR`**: Abbreviation for Arkansas.
- **`AZ`**: Abbreviation for Arizona.
- **`CA`**: Abbreviation for California.
- **`CO`**: Abbreviation for Colorado.
- **`CT`**: Abbreviation for Connecticut.
- **`DC`**: Abbreviation for District of Columbia.
- **`DE`**: Abbreviation for Delaware.
- **`FL`**: Abbreviation for Florida.
- **`GA`**: Abbreviation for Georgia.
- **`HI`**: Abbreviation for Hawaii.
- **`IA`**: Abbreviation for Iowa.
- **`ID`**: Abbreviation for Idaho.
- **`IL`**: Abbreviation for Illinois.
- **`IN`**: Abbreviation for Indiana.
- **`KS`**: Abbreviation for Kansas.
- **`KY`**: Abbreviation for Kentucky.
- **`LA`**: Abbreviation for Louisiana.
- **`MA`**: Abbreviation for Massachusetts.
- **`MD`**: Abbreviation for Maryland.
- **`ME`**: Abbreviation for Maine.
- **`MI`**: Abbreviation for Michigan.
- **`MN`**: Abbreviation for Minnesota.
- **`MO`**: Abbreviation for Missouri.
- **`MS`**: Abbreviation for Mississippi.
- **`MT`**: Abbreviation for Montana.
- **`NC`**: Abbreviation for North Carolina.
- **`ND`**: Abbreviation for North Dakota.
- **`NE`**: Abbreviation for Nebraska.
- **`NH`**: Abbreviation for New Hampshire.
- **`NJ`**: Abbreviation for New Jersey.
- **`NM`**: Abbreviation for New Mexico.
- **`NV`**: Abbreviation for Nevada.
- **`NY`**: Abbreviation for New York.
- **`OH`**: Abbreviation for Ohio.
- **`OK`**: Abbreviation for Oklahoma.
- **`OR`**: Abbreviation for Oregon.
- **`PA`**: Abbreviation for Pennsylvania.
- **`PR`**: Abbreviation for Puerto Rico.
- **`RI`**: Abbreviation for Rhode Island.
- **`SC`**: Abbreviation for South Carolina.
- **`SD`**: Abbreviation for South Dakota.
- **`TN`**: Abbreviation for Tennessee.
- **`TX`**: Abbreviation for Texas.
- **`UT`**: Abbreviation for Utah.
- **`VA`**: Abbreviation for Virginia.
- **`VT`**: Abbreviation for Vermont.
- **`WA`**: Abbreviation for Washington.
- **`WI`**: Abbreviation for Wisconsin.
- **`WV`**: Abbreviation for West Virginia.
- **`WY`**: Abbreviation for Wyoming.

### Utility Functions

- **`ABBREVIATIONS_FROM_IDS`**: A dictionary mapping state IDs to their abbreviations.
- **`IDS_FROM_ABBREVIATIONS`**: A dictionary mapping state abbreviations to their IDs.
- **`IDS_FROM_NAMES`**: A dictionary mapping state names to their IDs.
- **`NAMES_FROM_IDS`**: A dictionary mapping state IDs to their names.

### Usage Example

```python
import censusdis.states

# Get the abbreviation for California
california_abbr = censusdis.states.CA
print(f"California abbreviation: {california_abbr}")

# Get all state abbreviations and their IDs
state_id_map = censusdis.states.IDS_FROM_ABBREVIATIONS
print(f"ID for Texas: {state_id_map['TX']}")

# Get all state names and their IDs
state_name_map = censusdis.states.NAMES_FROM_IDS
print(f"Name for state ID 06: {state_name_map['06']}")
```
```

--------------------------------

### Prefetch Variable Types and Download Data

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Prefetches variable types to fail fast for unknown fields and checks for the presence of row keys. Converts kwargs to strings before downloading.

```python
# Prefetch all the types before we load the data.
    # That way we fail fast if a field is not known.
    _prefetch_variable_types(dataset, vintage, download_variables, variable_cache)
    # Also check that the row_keys, if supplied, are present in the dataset
    if row_keys:
        _prefetch_variable_types(dataset, vintage, row_keys, variable_cache)

    # If we were given a list, join it together into
    # a comma-separated string.
    string_kwargs = {k: _gf2s(v) for k, v in kwargs.items()}

    return _download_remote(
        dataset,
        vintage,
        download_variables=download_variables,
        set_to_nan=set_to_nan,
        query_filter=query_filter,
        with_geometry=with_geometry,
        with_geometry_columns=with_geometry_columns,
        tiger_shapefiles_only=tiger_shapefiles_only,
        remove_water=remove_water,
        api_key=api_key,
        variable_cache=variable_cache,
        **string_kwargs,
    )
```

--------------------------------

### PlotSpec Initialization

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Initializes a PlotSpec object, which defines how to plot downloaded data. It raises a ValueError if neither `variable` nor `boundary` is specified, or if both are specified.

```python
class PlotSpec:
    """
    A specification for how to plot data we downloaded.

    Parameters
    ----------
    variable
        What variable to plot. Specify this to shade geographies
        based on the value of the variable. Leave out and set `boundary=True`
        to plot boundaries instead.
    boundary
        Should we plot boundaries instead of filled geographies?
        If `True`, `variable` should not be specified.
    title
        A title for the plot.
    with_background
        If `True`, plot over a background map.
    legend
        If `True` and plotting a variable (not a boundary) then add a legend.
    legend_format
        How to format the numbers on the legend. The options are
        '"float"', '"int"', '"dollar"', '"percent"', or a format string like `"${x:.2f}"`
        to choose any Python string format you want.
    projection
        What projection to use. `"US"` means move AK, HI, and PR. `None` means
        use what the map is already in. Anything else is interpreted as an EPSG.
    plot_kwargs
        Additional keyword args for matplotlib to use in plotting.
    """

    def __init__(
        self,
        *,
        variable: Optional[str] = None,
        boundary: bool = False,
        title: Optional[str] = None,
        with_background: bool = False,
        plot_kwargs: Optional[Dict[str, Any]] = None,
        projection: Optional[str] = None,
        legend: bool = True,
        legend_format: Optional[str] = None,
    ):
        if variable is None and not boundary:
            raise ValueError("Must specify either `variable=` or `boundary=True`")
        if variable is not None and boundary:
            raise ValueError("Must specify only one of `variable=` or `boundary=True`")

        if projection is None:
            projection = "US"
```

--------------------------------

### Load DataSpec from YAML

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Loads a DataSpec object from a specified YAML file path. Requires a custom YAML loader that recognizes the '!DataSpec' tag.

```python
    @classmethod
    def load_yaml(cls, path: Union[str, Path]):
        """Load a YAML file containing a `DataSpec`. """
        loader = cls._yaml_loader()

        loaded = yaml.load(open(path, "rb"), Loader=loader)

        return loaded
```

--------------------------------

### Initialize VariableSpecCollection

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Initializes a VariableSpecCollection with a list of other VariableSpec objects. Sets the denominator to None as it aggregates specs.

```python
def __init__(self, variable_specs: Iterable[VariableSpec]):
        super().__init__(denominator=None)
        self._variable_specs = list(variable_specs)
```

--------------------------------

### Download Census Data with Geometry

Source: https://censusdis.readthedocs.io/en/latest/intro.html

Use the `with_geometry=True` flag to include geographical shapes with your census data. This is useful for plotting geographical distributions. Specify state and county as '*' to download data for all regions.

```python
gdf_counties = ced.download(
    DATASET,
    YEAR,
    VARIABLES,
    state="*",
    county="*",
    with_geometry=True
)

```

--------------------------------

### Auto-fetch File

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Conditionally fetches a file if the auto-fetch mechanism is enabled. This is a helper method for managing file downloads.

```python
def _auto_fetch_file(self, name: str, base_url: str, *, timeout: int):
        if not self._auto_fetch:
            return

        self._fetch_file(name, base_url, timeout=timeout)
```

--------------------------------

### censusdis.cli.yamlspec.VariableSpec.download()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Downloads data for specified variables.

```APIDOC
## VariableSpec.download()

### Description
Downloads data for a specific set of variables as defined in the `VariableSpec`.

### Method
`VariableSpec.download()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage (assuming VariableSpec object is initialized)
variable_spec_instance.download()
```

### Response
None explicitly documented. Likely returns downloaded data for the specified variables.
```

--------------------------------

### censusdis.cli.yamlspec.VariableSpec.variables_to_download()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Identifies individual variables ready for download.

```APIDOC
## VariableSpec.variables_to_download()

### Description
Identifies and returns individual variables that are prepared and ready for download based on the `VariableSpec` configuration.

### Method
`VariableSpec.variables_to_download()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage
variables = variable_spec_instance.variables_to_download()
```

### Response
Returns a list or structure of individual variables designated for download.
```

--------------------------------

### censusdis.cli.yamlspec.DataSpec.download()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Downloads data based on the DataSpec configuration.

```APIDOC
## DataSpec.download()

### Description
Downloads data according to the specifications defined in the `DataSpec` object, which can include geography, vintage, and variables.

### Method
`DataSpec.download()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage (assuming DataSpec object is initialized)
data_spec_instance.download()
```

### Response
None explicitly documented. Likely returns downloaded data or a status.
```

--------------------------------

### Wrap and Relocate Geometries

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/maps.html

Applies wrapping for polygons that cross the antimeridian and then relocates geometries within Alaska, Hawaii, or Puerto Rico.

```python
def _wrap_and_relocate_geos(geo: BaseGeometry):
    geo = _wrap_polys(geo)
    return _relocate_parts_in_ak_hi_pr(geo)
```

--------------------------------

### DataSpec Download Method

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

Downloads data based on the DataSpec configuration. It accepts an optional API key and returns either a pandas DataFrame or a geopandas GeoDataFrame.

```python
    def download(
        self,
        api_key: Optional[str] = None,
    ) -> Union[pd.DataFrame, gpd.GeoDataFrame]:
        """
        Download the data we want from the U.S. Census API.

        Parameters
        ----------
        api_key
            An optional API key. If you don't have or don't use a key, the number
            of calls you can make will be limited to 500 per day.

        Returns
        -------
            A :py:class:`~pd.DataFrame` or `~gpd.GeoDataFrame` containing the requested US Census data.
        """
        return self._variable_spec.download(
            dataset=self.dataset,
            vintage=self._vintage,
            with_geometry=self._with_geometry,
            contained_within=self._contained_within,
            remove_water=self._remove_water,
            api_key=api_key,
            **self._geography,
        )
```

--------------------------------

### download()

Source: https://censusdis.readthedocs.io/en/latest/data.html

The main function for downloading US Census data. It allows specifying the dataset, vintage, variables, geographic filters, and geometry options.

```APIDOC
## download()

### Description
This function is the primary interface for downloading US Census data. It supports various parameters to customize the data retrieval, including dataset selection, vintage, specific variables or groups, geographic filtering, and geometry inclusion.

### Parameters
#### dataset (string) - Required - The dataset to download from. Examples: ”acs/acs5”, ”dec/pl”, or ”timeseries/poverty/saipe/schdist”. Symbolic names like ACS5 are also supported.
#### vintage (string or integer) - Required - The vintage to download data for. Use an integer year (e.g., 2020) or the string ‘timeseries’ for time-series datasets.
#### download_variables (list of strings) - Optional - A list of specific census variables to download (e.g., ["NAME", "B01001_001E"]).
#### group (string or list of strings) - Optional - One or more groups (as defined by the U.S. Census) whose variable values should be downloaded. These are in addition to any specified in download_variables.
#### leaves_of_group (string or list of strings) - Optional - One or more groups whose leaf variable values should be downloaded. These are in addition to any specified in download_variables or group.
#### set_to_nan (boolean or list of values) - Optional - If True, all values in censusdis.values.ALL_SPECIAL_VALUES will be replaced with NaN. If a list of values is provided, only those specific values will be set to NaN. If False, no replacements are made.
#### skip_annotations (boolean) - Optional - If True, attempts to filter out annotation variables from group or leaves_of_group. Variables in download_variables are unaffected.
#### query_filter (dict) - Optional - A dictionary of values to filter on server-side. Example: {‘NAICS2017’: ‘72251’}.
#### with_geometry (boolean) - Optional - If True, returns a `gpd.GeoDataFrame` with geometry for mapping.
#### with_geometry_columns (boolean) - Optional - If True, keeps additional columns from shapefiles when geometry is included.
#### tiger_shapefiles_only (boolean) - Optional - If True, only looks for TIGER shapefiles. If False, prioritizes CB shapefiles then falls back to TIGER files.
#### remove_water (boolean) - Optional - If True and with_geometry is True, removes water areas from the returned geometry by querying TIGER for AREAWATER shapefiles.
#### download_contained_within (dict) - Optional - A dictionary specifying the geography or geographies that results should be contained within.
#### area_threshold (float) - Optional - The fraction of the area of other geographies that must be contained in our geography to be included. Ignored if download_contained_within is None.
#### api_key (string) - Optional - An API key for increased call limits. Without a key, the limit is 500 calls per day.
#### variable_cache (object) - Optional - A cache object for metadata about variables.

### Response
#### Success Response (200)
Returns a pandas DataFrame or a GeoDataFrame (if with_geometry is True) containing the requested census data.

#### Response Example
(DataFrame or GeoDataFrame structure depends on parameters)
```

--------------------------------

### Parse Download Variables

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Parses download variables, handling grouping, annotations, and variable caching. Converts kwargs to the correct path component format.

```python
# In case they came to us in py format, as kwargs often do.
    kwargs = {
        cgeo.path_component_from_snake(dataset, vintage, k): v
        for k, v in kwargs.items()
    }

    # Parse out the download variables
    download_variables = _parse_download_variables(
        dataset,
        vintage,
        download_variables=download_variables,
        group=group,
        leaves_of_group=leaves_of_group,
        skip_annotations=skip_annotations,
        variable_cache=variable_cache,
    )
```

--------------------------------

### Download Census Data with Geometry

Source: https://censusdis.readthedocs.io/en/latest/_sources/intro.rst.txt

Use the `ced.download` function to retrieve census data for all counties in all states, including their geographical shapes. This is useful for mapping and spatial analysis.

```python
gdf_counties = ced.download(
        DATASET,
        YEAR,
        VARIABLES,
        state="*",
        county="*",
        with_geometry=True
    )
```

--------------------------------

### censusdis.cli.yamlspec.VariableSpec.groups_to_download()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Identifies groups of variables ready for download.

```APIDOC
## VariableSpec.groups_to_download()

### Description
Identifies and returns groups of variables that are prepared and ready for download based on the `VariableSpec` configuration.

### Method
`VariableSpec.groups_to_download()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage
groups = variable_spec_instance.groups_to_download()
```

### Response
Returns a list or structure of variable groups designated for download.
```

--------------------------------

### YAML Constructor Helper Function

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/cli/yamlspec.html

A factory function to create YAML constructors for classes. Use this to automatically instantiate Python objects from YAML mappings.

```python
def _class_constructor(clazz: ClassVar):
    def constructor(
        loader: yaml.SafeLoader, node: yaml.nodes.MappingNode
    ) -> VariableSpec:
        """Construct a new object of the given class."""
        kwargs = loader.construct_mapping(node, deep=True)
        return clazz(**kwargs)

    return constructor
```

--------------------------------

### censusdis.data.download_lodes()

Source: https://censusdis.readthedocs.io/en/latest/api.html

Downloads LEHD Origin-Destination Employment Statistics (LODES) data.

```APIDOC
## download_lodes()

### Description
Downloads LEHD Origin-Destination Employment Statistics (LODES) data, which provides information on job flows.

### Method
`download_lodes()`

### Parameters
None explicitly documented.

### Request Example
```python
# Example usage
lodes_data = download_lodes(year, state_code)
```

### Response
None explicitly documented. Likely returns LODES data.
```

--------------------------------

### Download Census Data with Geometry

Source: https://censusdis.readthedocs.io/en/latest/_modules/censusdis/data.html

Downloads census data and optionally merges it with geographic boundary information. Use this when you need to visualize or spatially analyze the data. Requires specifying dataset, vintage, and desired variables.

```python
url, params, bound_path = census_table_url(
        dataset,
        vintage,
        download_variables,
        query_filter=query_filter,
        api_key=api_key,
        **kwargs,
    )
    df_data = data_from_url(url, params)

    # Coerce the types based on metadata about the variables.
    _coerce_downloaded_variable_types(
        dataset, vintage, download_variables, df_data, variable_cache
    )

    download_variables_upper = [dv.upper() for dv in download_variables]

    # Put the geo fields (STATE, COUNTY, etc...) that came back up front.
    df_data = df_data[
        [col for col in df_data.columns if col not in download_variables_upper]
        + download_variables_upper
    ]

    # NaN out as requested.
    if set_to_nan is True:
        set_to_nan = ALL_SPECIAL_VALUES
    if set_to_nan:
        df_data = df_data.replace(list(set_to_nan), np.nan)

    if with_geometry:
        # We need to get the geometry and merge it in.
        geo_level = bound_path.path_spec.path[-1]
        shapefile_scope = bound_path.bindings[bound_path.path_spec.path[0]]

        gdf_data = add_geography(
            df_data,
            vintage,
            shapefile_scope,
            geo_level,
            with_geometry_columns=with_geometry_columns,
            tiger_shapefiles_only=tiger_shapefiles_only,
        )

        if remove_water:
            gdf_data = clip_water(gdf_data, vintage)

        return gdf_data

    return df_data
```