### Get All Sample Info

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Obtains a dictionary of sample codes for microdata collections.

```APIDOC
## Get All Sample Info

### Description
Obtains a dictionary of sample codes for microdata collections.

### Method
`.get_all_sample_info()`

### Request Example
```python
sample_info = ipums.get_all_sample_info()
```
```

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

### Install IPUMS-py

Source: https://github.com/ipums/ipumspy/blob/master/README.md

Install the IPUMS-py package using pip. Requires Python 3.8 or higher.

```bash
pip install ipumspy
```

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

### Create Extract for Case Selection Example

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Instantiate a MicrodataExtract for IPUMS USA data, specifying collection, sample, variables, and a description for a case selection example.

```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2021a"],
    variables=["AGE", "SEX", "RACE"],
    description="Case selection example"
)
```

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

### NHGIS Dataset Example

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Example of specifying an NHGIS dataset with data tables, geographic levels, and optional breakdown values.

```APIDOC
## NHGIS Dataset Example

### Description
This snippet illustrates how to configure an NHGIS dataset within an ``AggregateDataExtract``, specifying the dataset name, desired data tables, geographic levels, and optionally, specific breakdown values.

### Method
Python Class Instantiation

### Endpoint
N/A (SDK Usage)

### Parameters
#### Class: NhgisDataset
- **name** (string) - Required - The name of the NHGIS dataset (e.g., "2000_SF1a").
- **data_tables** (list) - Required - A list of data table names (e.g., ["NP001A", "NP031A"]).
- **geog_levels** (list) - Required - A list of geographic levels (e.g., ["state"]).
- **breakdown_values** (list) - Optional - Specific breakdown values to request (e.g., ["bs21.ge01", "bs21.ge43"]).

### Request Example
```python
from ipumspy import AggregateDataExtract, NhgisDataset

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(
            name="2000_SF1a",
            data_tables=["NP001A", "NP031A"],
            geog_levels=["state"],
            breakdown_values=["bs21.ge01", "bs21.ge43"],  # Urban + Rural breakdowns
      )
   ],
)
```

### Response
N/A (Object Instantiation)
```

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

### Creating a Microdata Extract with Sample Members

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

This example demonstrates how to create an ATUS microdata extract, including both household members of respondents and non-respondents, alongside custom time use variables.

```APIDOC
## Creating a Microdata Extract with Sample Members

### Description
This code snippet shows how to instantiate a `MicrodataExtract` object for the ATUS collection. It includes specifying variables, custom time use variables with ownership, and options to include non-respondents and household members.

### Method
```python
MicrodataExtract(
    collection="atus",
    samples=["at2016"],
    variables=["AGE", "SEX"],
    time_use_variables=[
        TimeUseVariable(name="BLS_PCARE"), 
        TimeUseVariable(name="MY_CUSTOM_TUV", owner="newipumsuser@gmail.com")
    ],
    sample_members={
        "include_non_respondents": True,
        "include_household_members": True
    },
    description="Sample members example"
)
```

### Parameters
- `collection` (string): The IPUMS data collection (e.g., "atus").
- `samples` (list of strings): The specific samples to extract (e.g., ["at2016"]).
- `variables` (list of strings): A list of desired variables (e.g., ["AGE", "SEX"]).
- `time_use_variables` (list of `TimeUseVariable` objects): Custom time use variables. Each `TimeUseVariable` can have a `name` and an optional `owner`.
- `sample_members` (dictionary): Options for including sample members. Can include `"include_non_respondents"` (boolean) and `"include_household_members"` (boolean).
- `description` (string): A description for the extract.
```

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

### Install ipumspy with conda

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/getting_started.rst

Use this command to install the ipumspy package using conda from the conda-forge channel.

```bash
conda install -c conda-forge ipumspy
```

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

### Get Variable Information from DDI

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reading_data.rst

Retrieves metadata for a specific variable from a DDI codebook. Shows how to access codes and descriptions.

```python
from ipumspy import readers
import pandas as pd

# read ddi and data
ddi_codebook = readers.read_ipums_ddi(path/to/ddi/xml/file)
ipums_df = readers.read_microdata(ddi_codebook, path/to/data/file)

# get VariableDescription for SEX
sex_info = ddi_codebook.get_variable_info("SEX")

# see codes and labels for SEX
print(sex_info.codes)
#> {'Male': 1, 'Female': 2}

# see variable description for SEX
print(sex_info.description)
#> SEX reports whether the person was male or female.
```

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

### Request Individual Data Source Metadata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Create an IpumsMetadata object to specify the data source for which to retrieve detailed metadata. Example uses NHGIS time series table 'A00'.

```python
tst = TimeSeriesTableMetadata("nhgis", "A00")

ipums.get_metadata(tst)

tst.description
#> 'Total Population'
```

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

### NHGIS Dataset with Multiple Years

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Example of specifying an NHGIS dataset that spans multiple years, requiring explicit year selection.

```APIDOC
## NHGIS Dataset with Multiple Years

### Description
This example demonstrates how to specify a multi-year NHGIS dataset and select specific years for the extract.

### Method
Python Class Instantiation

### Endpoint
N/A (SDK Usage)

### Parameters
#### Class: NhgisDataset
- **name** (string) - Required - The name of the NHGIS dataset (e.g., "1988_1997_CBPa").
- **data_tables** (list) - Required - A list of data table names (e.g., ["NT004"]).
- **geog_levels** (list) - Required - A list of geographic levels (e.g., ["county"]).
- **years** (list) - Required - A list of specific years to include (e.g., [1988, 1989, 1990]). Use `["*"]` to select all available years.

### Request Example
```python
from ipumspy import AggregateDataExtract, NhgisDataset

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(
         name="1988_1997_CBPa",
         data_tables=["NT004"],
         geog_levels=["county"],
         years=[1988, 1989, 1990],
      )
   ],
)
```

### Response
N/A (Object Instantiation)
```

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

### IHGIS Aggregate Data Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Example of creating an IHGIS aggregate data extract, specifying the collection, a description, and the datasets with their associated data tables and tabulation geographies.

```APIDOC
## IHGIS Aggregate Data Extract

### Description
This code snippet demonstrates how to create an aggregate data extract for IHGIS.

### Method
`AggregateDataExtract`

### Parameters
- `collection`: (string) - Required - Specifies the collection type, e.g., "ihgis".
- `description`: (string) - Optional - A user-provided description for the extract.
- `datasets`: (list of `IhgisDataset`) - Required - A list of IHGIS datasets to include in the extract.

#### `IhgisDataset` Parameters
- `dataset_name`: (string) - Required - The name of the IHGIS dataset (e.g., "KZ2009pop").
- `data_tables`: (list of strings) - Required - A list of data tables to include for the dataset (e.g., ["KZ2009pop.AAA"]).
- `tabulation_geographies`: (list of strings) - Required - A list of tabulation geographies for the dataset (e.g., ["KZ2009pop.g0"]).

### Request Example
```python
from ipumspy import AggregateDataExtract, IhgisDataset

AggregateDataExtract(
   collection="ihgis",
   description="An IHGIS example extract",
   datasets=[
      IhgisDataset(
         "KZ2009pop", 
         data_tables=["KZ2009pop.AAA"],
         tabulation_geographies=["KZ2009pop.g0"]
      )
   ]
)
```

### Caution
IHGIS extract requests only accept input for `description` and `datasets`. Other `AggregateDataExtract` arguments do not apply to IHGIS extracts and will be omitted if included.
```

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

### IPUMS Extract Definition in YAML Format

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Example of an IPUMS extract definition stored in YAML format. This can be loaded into ipumspy.

```yaml
description: Sample USA extract
collection: usa
samples:
  - us2018a
  - us2019a
variables:
  - AGE
  - SEX
  - RACE
  - STATEFIP
  - MARST
```

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

### NHGIS Time Series Table Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Example of creating an NHGIS aggregate data extract that includes time series tables, specifying the collection, description, time series tables with geographic levels and years, and the time series layout.

```APIDOC
## NHGIS Time Series Table Extract

### Description
This code snippet demonstrates how to create an aggregate data extract for NHGIS that includes time series tables.

### Method
`AggregateDataExtract`

### Parameters
- `collection`: (string) - Required - Specifies the collection type, e.g., "nhgis".
- `description`: (string) - Optional - A user-provided description for the extract.
- `time_series_tables`: (list of `TimeSeriesTable`) - Optional - A list of time series tables to include in the extract.
- `tst_layout`: (string) - Optional - Specifies the layout for time series data (e.g., "time_by_row_layout").

#### `TimeSeriesTable` Parameters
- `table_name`: (string) - Required - The name of the time series table (e.g., "CW3").
- `geog_levels`: (list of strings) - Required - The geographic levels for the time series data (e.g., ["county", "state"]).
- `years`: (list of integers) - Optional - A subset of available years to include (e.g., [1990, 2000]). If not provided, all available years are included.

### Request Example (Basic)
```python
from ipumspy import AggregateDataExtract, TimeSeriesTable

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract: time series tables",
   time_series_tables=[TimeSeriesTable("CW3", geog_levels=["county", "state"])],
)
```

### Request Example (With Years)
```python
from ipumspy import AggregateDataExtract, TimeSeriesTable

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract: time series tables",
   time_series_tables=[
      TimeSeriesTable("CW3", geog_levels=["county", "state"], years=[1990, 2000])
   ],
)
```

### Request Example (With Layout)
```python
from ipumspy import AggregateDataExtract, TimeSeriesTable

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract: time series tables",
   time_series_tables=[
      TimeSeriesTable("CW3", geog_levels=["county", "state"], years=[1990, 2000])
   ],
   tst_layout="time_by_row_layout",
)
```
```

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

### Get Metadata for Individual Data Source

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Retrieves detailed metadata for a specific data source using an IpumsMetadata object.

```APIDOC
## Get Metadata for Individual Data Source

### Description
Retrieves detailed metadata for a specific data source using an IpumsMetadata object.

### Method
`.get_metadata(metadata_object)`

### Parameters
#### Path Parameters
- **metadata_object** (IpumsMetadata object) - Required - An object representing the specific data source for which to retrieve metadata (e.g., `TimeSeriesTableMetadata("nhgis", "A00")`).

### Request Example
```python
tst = TimeSeriesTableMetadata("nhgis", "A00")
ipums.get_metadata(tst)
print(tst.description)
#> 'Total Population'
```
```

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

### Get Metadata Catalog

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Retrieves a catalog of available data sources for a given collection and metadata type. This method returns a generator of metadata pages.

```APIDOC
## Get Metadata Catalog

### Description
Retrieves a catalog of available data sources for a given collection and metadata type. This method returns a generator of metadata pages.

### Method
`.get_metadata_catalog(collection, metadata_type)`

### Parameters
#### Path Parameters
- **collection** (string) - Required - The data collection to query (e.g., "nhgis").
- **metadata_type** (string) - Required - The type of metadata to retrieve (e.g., "data_tables").

### Request Example
```python
# Identify all data tables referring to "Urban Population"
for page in ipums.get_metadata_catalog("nhgis", metadata_type="data_tables"):
    for dt in page["data"]:
        if "Urban Population" in dt["description"]:
            urb_dts.append(dt)
```
```

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

### Read IPUMS Microdata in Chunks

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reading_data.rst

Reads a fixed-width rectangular IPUMS extract in chunks, allowing for filtering. Useful for large files. Filters rows from Minnesota in this example.

```python
from ipumspy import readers
import pandas as pd

iter_microdata = readers.read_microdata_chunked(ddi, chunksize=1000)
df = pd.concat([df[df["STATEFIP"] == 27] for df in iter_microdata])
```

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

### Get NHGIS Data Tables Metadata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Iterate through metadata pages to find NHGIS data tables containing specific keywords. Requires the 'nhgis' collection and 'data_tables' metadata type.

```python
urb_dts = []

# Identify all data tables referring to "Urban Population"
for page in ipums.get_metadata_catalog("nhgis", metadata_type="data_tables"):
    for dt in page["data"]:
        if "Urban Population" in dt["description"]:
            urb_dts.append(dt)
```

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

### Explore CLI Commands

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Run the --help option to see all available commands and their usage.

```bash
ipums --help
```

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

### Explore Command Help

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Access detailed help for specific commands, such as 'submit', to understand all available options and their usage.

```bash
ipums submit --help
```

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

### Instantiating a MicrodataExtract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Demonstrates the basic instantiation of a MicrodataExtract object with essential parameters like collection, samples, and variables.

```APIDOC
## Instantiating a MicrodataExtract

### Description
Construct an extract for an IPUMS microdata collection using the :class:`MicrodataExtract<ipumspy.api.extract.MicrodataExtract>` class. At a minimum, any ``MicrodataExtract`` must contain:

1. An IPUMS collection ID
2. A list of sample IDs
3. A list of variable names.

We also recommend providing an extract description to make it easier to identify and retrieve your extract in the future.

### Method
`ipumspy.api.extract.MicrodataExtract()`

### Parameters

#### Required Parameters
- **collection** (string) - The IPUMS collection ID (e.g., "usa").
- **samples** (list of strings) - A list of sample IDs (e.g., ["us2012b"]).
- **variables** (list of strings) - A list of variable names (e.g., ["AGE", "SEX"]).

#### Optional Parameters
- **description** (string) - A description for the extract.

### Request Example
```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example"
)
```
```

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

### Create ATUS Extract with Sample Members

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Demonstrates how to create an ATUS extract including both household members of respondents and non-respondents. This is useful for comprehensive analysis of household and respondent data.

```python
from ipumspy import MicrodataExtract
from ipumspy.time_use import TimeUseVariable

atus_extract = MicrodataExtract(
    collection="atus",
    samples=["at2016"],
    variables=["AGE", "SEX"],
    time_use_variables=[
        TimeUseVariable(name="BLS_PCARE"), 
        TimeUseVariable(name="MY_CUSTOM_TUV", owner="newipumsuser@gmail.com")
    ],
    sample_members={
        "include_non_respondents": True,
        "include_household_members": True
    },
    description="Sample members example"
)
```

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

### Download an Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Wait for an extract to complete processing and then download it to a specified directory. Ensure the DOWNLOAD_DIR path is correctly set.

```python
DOWNLOAD_DIR = Path("<your_download_dir>")
ipums.download_extract(extract, download_dir=DOWNLOAD_DIR)
```

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

### Instantiate MicrodataExtract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Instantiate a MicrodataExtract object with required parameters: collection, samples, and variables. Provide a description for easier identification.

```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example"
)
```

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

### Get IPUMS Citation

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/index.rst

Use this code to print the appropriate citation for a given IPUMS extract, which can be found in the accompanying DDI.

```python
print(ddi.ipums_citation)
```

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

### Initialize IpumsApiClient

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/getting_started.rst

Initialize the IpumsApiClient with your API key. It is recommended to store your API key in an environment variable named 'IPUMS_API_KEY'.

```python
import os
from pathlib import Path
from ipumspy import IpumsApiClient, MicrodataExtract, readers, ddi

# This assumes you have set up an environmental variable called 
# "IPUMS_API_KEY" to store your IPUMS API key
IPUMS_API_KEY = os.environ.get("IPUMS_API_KEY")

ipums = IpumsApiClient(IPUMS_API_KEY)
```

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

### Download Supplemental Data File

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Use the `ipums.get` method to download a supplemental data file. Ensure you have your API key set as an environment variable and replace `<your-download-path-here>` with the desired local path.

```python
ipums = IpumsApiClient(os.environ.get("IPUMS_API_KEY"))

file_name = "nhgis_blk2010_blk2020_10.zip"
url = f"{ipums.base_url}/supplemental-data/nhgis/crosswalks/nhgis_blk2010_blk2020_state/{file_name}"

download_path = "<your-download-path-here>"

with ipums.get(url, stream=True) as response:
   with open(download_path, "wb") as outfile:
      for chunk in response.iter_content(chunk_size=8192):
            outfile.write(chunk)
```

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

### Specify NHGIS Dataset with Default Parameters

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Instantiate an NhgisDataset with the required parameters: name, data_tables, and geog_levels. Other parameters like years and breakdown_values are optional.

```python
extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(name="2000_SF1a", data_tables=["NP001A", "NP031A"], geog_levels=["state"])
   ],
)
```

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

### Instantiate AggregateDataExtract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Demonstrates how to create an AggregateDataExtract object for NHGIS, specifying datasets, data tables, and geographic levels.

```APIDOC
## Instantiate AggregateDataExtract

### Description
This example shows how to instantiate an ``AggregateDataExtract`` object for the IPUMS NHGIS data collection, including specific data tables and geographic levels.

### Method
Python Class Instantiation

### Endpoint
N/A (SDK Usage)

### Parameters
#### Class: AggregateDataExtract
- **collection** (string) - Required - The IPUMS collection ID (e.g., "nhgis").
- **description** (string) - Optional - A description for the extract.
- **datasets** (list) - Required - A list of dataset objects.

#### Class: NhgisDataset
- **name** (string) - Required - The name of the NHGIS dataset.
- **data_tables** (list) - Required - A list of data table names to request.
- **geog_levels** (list) - Required - A list of geographic levels to aggregate.
- **years** (list) - Optional - A list of years to include. Use `["*"]` for all years.
- **breakdown_values** (list) - Optional - Specific breakdown values to request.

### Request Example
```python
from ipumspy import AggregateDataExtract, NhgisDataset

extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS extract example",
   datasets=[
      NhgisDataset(name="1990_STF1", data_tables=["NP1", "NP2"], geog_levels=["county"])
   ]
)
```

### Response
N/A (Object Instantiation)
```

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

### Initialize IPUMS API Client

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Initializes the API client using an API key. Ensure your API key is stored in the IPUMS_API_KEY environment variable.

```python
import os
from pathlib import Path
from ipumspy import IpumsApiClient, MicrodataExtract, save_extract_as_json

IPUMS_API_KEY = os.environ.get("IPUMS_API_KEY")

ipums = IpumsApiClient(IPUMS_API_KEY)
```

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

### Step-by-Step Extract Management

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Manage IPUMS extracts through individual steps: submit, check status, and download. This provides more control than the all-in-one command.

```bash
ipums submit -k <IPUMS_API_KEY> ipums.yaml
# Your extract for collection usa has been successfully submitted with number 10
```

```bash
ipums check -k <IPUMS_API_KEY> 10
# Extract 10 in collection usa has status started
```

```bash
ipums check -k <IPUMS_API_KEY> 10
# Extract 10 in collection usa has status completed
```

```bash
ipums download -k <IPUMS_API_KEY> 10
```

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

### Create Extract for Household Case Selection

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Instantiate a MicrodataExtract with case_select_who set to 'households' to include all individuals from households that meet the selection criteria.

```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2021a"],
    variables=["AGE", "SEX", "RACE"],
    description="Case selection example",
    case_select_who = "households"
)
```

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

### Load Downloaded Microdata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/getting_started.rst

After downloading an extract, load the DDI XML and the data file into a pandas DataFrame using ipumspy readers.

```python
# Get the DDI
ddi_file = list(DOWNLOAD_DIR.glob("*.xml"))[0]
ddi = readers.read_ipums_ddi(ddi_file)

# Get the data
ipums_df = readers.read_microdata(ddi, DOWNLOAD_DIR / ddi.file_description.filename)
```

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

### Specifying Data Format

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Illustrates how to set the desired file format for the microdata extract, such as CSV.

```APIDOC
## Specifying Data Format

### Description
Users have the option to specify a desired file format when creating an extract object by using the ``data_format`` argument.

### Method
`ipumspy.api.extract.MicrodataExtract(data_format=...)`

### Parameters

#### Request Body
- **data_format** (string) - The desired file format (e.g., "csv").

### Request Example
```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example",
    data_format="csv",
)
```
```

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

### Submit and Download Extract with Race Variable

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Submit and download an extract that includes the RACE variable, defined in a separate YAML file. This demonstrates specifying different extract configurations.

```yaml
description: Another extract
collection: usa
samples:
  - us2012b
variables:
  - AGE
  - SEX
  - RACE
```

```bash
ipums submit-and-download -k <IPUMS_API_KEY> ipums_with_race.yaml
```

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

### Create a Basic Microdata Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Instantiate a MicrodataExtract object for IPUMS CPS data, specifying the collection, sample, and desired variables.

```python
extract = MicrodataExtract(
    collection="cps",
    samples=["cps2022_03s"],
    variables=["AGE", "SEX", "RACE"],
    description="A CPS extract example"
)
```

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

### Submit and Download Multiple Extracts

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Submit and download multiple extracts simultaneously by defining them in a single YAML file under the 'extracts' key. This is useful for batch processing.

```yaml
extracts:
- description: Simple IPUMS extract
  collection: usa
  samples:
    - us2012b
  variables:
    - AGE
    - SEX
- description: Another extract
  collection: usa
  samples:
    - us2012b
  variables:
    - AGE
    - SEX
    - RACE
```

```bash
ipums submit-and-download -k <IPUMS_API_KEY> ipums_multiple.yaml
```

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

### Specifying Data Structure

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Shows how to configure different data structures for microdata extracts, including hierarchical and rectangular formats.

```APIDOC
## Specifying Data Structure

### Description
IPUMS microdata extracts can be requested in rectangular, hierarchical, or household-only structures. The ``data_structure`` argument controls this. The default is ``{"rectangular": {"on": "P"}}`` for a rectangular, person-level extract.

### Method
`ipumspy.api.extract.MicrodataExtract(data_structure=...)`

### Parameters

#### Request Body
- **data_structure** (dict) - Specifies the data structure. Examples:
  - ``{"hierarchical": {}}`` for hierarchical data.
  - ``{"rectangular": {"on": "R"}}`` for rectangular data on a specific record type (e.g., 'R' for Round in MEPS).
  - ``{"householdOnly": {}}`` for household-only data.

### Request Example (Hierarchical)
```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example",
    data_structure={"hierarchical": {}},
)
```

### Request Example (Rectangular on Round)
```python
extract = MicrodataExtract(
    collection="meps",
    samples=["mp2016"],
    variables=["AGE", "SEX", "PREGNTRD"],
    description="An IPUMS extract example",
    data_structure={"rectangular": {"on": "R"}},
)
```
```

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

### Dataset and Data Table Metadata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Demonstrates how to retrieve metadata for NHGIS and IHGIS datasets and data tables using the `IpumsApiClient` and metadata classes.

```APIDOC
## Dataset and Data Table Metadata

### Description
This section explains how to obtain metadata for IPUMS datasets and data tables using the `ipumspy` library.

### Method
`IpumsApiClient.get_metadata()`

### Parameters
- `metadata_class_instance`: An instance of a metadata class (e.g., `NhgisDatasetMetadata`, `IhgisDatasetMetadata`, `NhgisDataTableMetadata`, `IhgisDataTableMetadata`) initialized with the dataset or data table identifier.

### Request Example (NHGIS Dataset Metadata)
```python
import os
from ipumspy import IpumsApiClient, NhgisDatasetMetadata

ipums = IpumsApiClient(os.environ.get("IPUMS_API_KEY"))

ds = ipums.get_metadata(NhgisDatasetMetadata("2000_SF1a"))

# Accessing metadata attributes
print(ds.description)
print(ds.data_tables)
```

### Response Example (Dataset Metadata Attributes)
- `ds.description`: (string) - Description of the dataset.
- `ds.data_tables`: (dict) - Dictionary of data table codes for this dataset.
```

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

### ipumspy.ddi.FileDescription

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/ddi.rst

Represents the description of a file within a DDI Codebook.

```APIDOC
## Class: ipumspy.ddi.FileDescription

### Description
Represents the description of a file within a DDI Codebook. It details information about a specific data file, such as its name, format, and record structure.

### Usage
```python
# Example usage (typically accessed via a Codebook object)
from ipumspy.ddi import Codebook

# codebook = Codebook('path/to/your/ddi.xml')
# if codebook.files:
#     first_file = codebook.files[0]
#     print(f"File Name: {first_file.name}")
```

### Attributes
- **name**: The name of the data file.
- **format**: The format of the data file (e.g., 'logical', 'physical').
- **record_layout**: Information about the layout of records within the file.
```

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

### Submit and Download Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Submit, wait for, and download an IPUMS extract defined in a YAML file in a single command. Ensure your IPUMS_API_KEY is set as an environment variable or provided with the -k flag.

```yaml
description: Simple IPUMS extract
collection: usa
samples:
  - us2012b
variables:
  - AGE
  - SEX
```

```bash
ipums submit-and-download -k <IPUMS_API_KEY> ipums.yaml
```

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

### Create an IHGIS Aggregate Data Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Construct an IHGIS data extract request specifying the collection, a description, and the desired datasets with their data tables and tabulation geographies. Note that only 'description' and 'datasets' arguments are applicable for IHGIS extracts.

```python
AggregateDataExtract(
      collection="ihgis",
      description="An IHGIS example extract",
      datasets=[
         IhgisDataset(
            "KZ2009pop", 
            data_tables=["KZ2009pop.AAA"],
            tabulation_geographies=["KZ2009pop.g0"]
         )
      ]
   )
```

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

### Wait for and Download Extract by ID

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Wait for an extract to complete and then download it, using only the extract ID and collection name. This method is useful for retrieving extracts without the original object.

```python
ipums.wait_for_extract(extract=1, collection="usa")
ipums.download_extract(extract=1, collection="usa")
```

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

### Download Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Downloads a processed extract to a specified directory.

```APIDOC
## Download Extract

### Description
Downloads a processed extract to a specified directory.

### Method
`.download_extract(extract, download_dir, collection)`

### Parameters
#### Path Parameters
- **extract** (Extract object or integer) - Required - The extract object or its ID number.
- **download_dir** (string) - Required - The path to the directory where the extract will be downloaded.
- **collection** (string) - Optional - The name of the data collection (required if using extract ID).

### Request Example
```python
from pathlib import Path

DOWNLOAD_DIR = Path("<your_download_dir>")

# Using an extract object
ipums.download_extract(extract, download_dir=DOWNLOAD_DIR)

# Using extract ID and collection name
ipums.download_extract(extract=1, collection="usa", download_dir=DOWNLOAD_DIR)
```
```

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

### Request System Time Use Variables

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Include system time use variables in an extract by specifying them in the `time_use_variables` argument. These variables cannot be included in the standard `variables` list.

```python
atus_extract = MicrodataExtract(
    collection="atus",
    samples=["at2016"],
    variables=["AGE", "SEX"],
    time_use_variables=["BLS_PCARE"],
    description="An time use variable example"
)
```

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

### Download NoExtract Data

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/noextract.rst

Downloads the noextract data files.

```APIDOC
## download_noextract_data

### Description
Downloads the noextract data files.

### Method
`ipumspy.noextract.download_noextract_data()`

### Parameters
This function does not take any explicit parameters in its signature as presented.
```

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

### Define and Submit a Microdata Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/getting_started.rst

Create a MicrodataExtract object specifying the collection, description, samples, and variables, then submit it to the IPUMS API.

```python
# Create an extract definition
extract = MicrodataExtract(
    collection="usa",
    description="Sample USA extract",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
)

# Submit the extract request
ipums.submit_extract(extract)
print(f"Extract submitted with id {extract.extract_id}")
#> Extract submitted with id 1

# Wait for the extract to finish
ipums.wait_for_extract(extract)

# Download the extract
DOWNLOAD_DIR = Path(<your_download_dir>)
ipums.download_extract(extract, download_dir=DOWNLOAD_DIR)
```

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

### Importing or Exporting Extract Definitions

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/api.rst

Utilities for converting ipumspy extract objects to and from dictionary representations, and for saving/loading extract definitions from JSON.

```APIDOC
## ipumspy.api.extract_from_dict

### Description
Creates an ipumspy extract object from a dictionary representation.

## ipumspy.api.extract_to_dict

### Description
Converts an ipumspy extract object into a dictionary representation.

## ipumspy.api.extract.save_extract_as_json

### Description
Saves an ipumspy extract object definition to a JSON file.

## ipumspy.api.extract.define_extract_from_json

### Description
Creates an ipumspy extract object definition from a JSON file.
```

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

### Create Extract with All Data Quality Flags

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Instantiate a MicrodataExtract for IPUMS CPS data, setting data_quality_flags=True to include all available data quality flags for the extract's variables.

```python
extract = MicrodataExtract(
    collection="cps",
    samples=["cps2022_03s"],
    variables=["AGE", "SEX", "RACE"],
    data_quality_flags=True
)
```

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

### Convert IPUMS Data to Parquet

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/cli.rst

Convert downloaded IPUMS microdata (.dat) and its DDI (.xml) into a Parquet file for efficient data handling and analysis. The output filename is specified as the third argument.

```bash
ipums convert usa_00006.xml usa_00006.dat usa_00006.parquet
```

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

### Extract Wrappers

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/api.rst

Classes for creating and managing data extracts from different IPUMS collections.

```APIDOC
## ipumspy.api.BaseExtract

### Description
Base class for IPUMS extract objects. Specific collections inherit from this class.

## ipumspy.api.MicrodataExtract

### Description
Represents a microdata extract from IPUMS. Use this for collections like IPUMS USA, IPUMS International, etc.

## ipumspy.api.AggregateDataExtract

### Description
Represents an aggregate data extract from IPUMS. Use this for collections like NHGIS, IHGIS, etc.
```

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

### Configure Hierarchical Data Structure

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Configure the extract to use a hierarchical data structure instead of the default rectangular format.

```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example",
    data_structure={"hierarchical": {}},
)
```

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

### Specify NHGIS Dataset with Specific Years

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

When creating an NhgisDataset, you can specify a list of years to retrieve data for. Use years=["*"] to select all available years.

```python
extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(
         name="1988_1997_CBPa",
         data_tables=["NT004"],
         geog_levels=["county"],
         years=[1988, 1989, 1990],
     )
   ],
)
```

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

### Combine Datasets and Shapefiles in NHGIS Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Create a single extract request that includes both tabular data from datasets and geographic boundary data from shapefiles. This is useful for spatial analysis.

```python
# Total state-level population from 2000 and 2010 decennial census
extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(name="2000_SF1a", data_tables=["NP001A"], geog_levels=["state"]),
      NhgisDataset(name="2010_SF1a", data_tables=["P1"], geog_levels=["state"])
   ],
   shapefiles=["us_state_2000_tl2010", "us_state_2010_tl2010"]
)
```

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

### Load and Submit IPUMS Extract from JSON

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Load a shared JSON extract definition into ipumspy and submit it. Requires API key and necessary imports.

```python
import os
from ipumspy import IpumsApiClient, define_extract_from_json

IPUMS_API_KEY = os.environ.get("IPUMS_API_KEY")
ipums = IpumsApiClient(IPUMS_API_KEY)

extract = define_extract_from_json("my_extract.json")
ipums.submit_extract(extract)
```

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

### Specify Time Series Table Layout

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Control the layout of time series data in an NHGIS extract using the 'tst_layout' argument. Options include arranging timepoints in columns (default), rows, or splitting them into separate files.

```python
extract = AggregateDataExtract(
      collection="nhgis",
      description="An NHGIS example extract: time series tables",
      time_series_tables=[
         TimeSeriesTable("CW3", geog_levels=["county", "state"], years=[1990, 2000])
      ],
      tst_layout="time_by_row_layout",
   )
```

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

### Request User-Defined Time Use Variables

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Request user-defined time use variables using `TimeUseVariable` objects in the `time_use_variables` argument. For custom variables, the `owner` field (your IPUMS account email) must be specified.

```python
atus_extract = MicrodataExtract(
    collection="atus",
    samples=["at2016"],
    variables=["AGE", "SEX"],
    time_use_variables=[
        TimeUseVariable(name="BLS_PCARE"), 
        TimeUseVariable(name="MY_CUSTOM_TUV", owner="newipumsuser@gmail.com")
    ],
    description="User-defined time use variable example"
)
```

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

### Retrieve NHGIS Dataset Metadata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Instantiate an IpumsApiClient and use the get_metadata method with NhgisDatasetMetadata to fetch metadata for a specific NHGIS dataset. The returned object contains dataset descriptions and available data table codes.

```python
from ipumspy import IpumsApiClient, NhgisDatasetMetadata

ipums = IpumsApiClient(os.environ.get("IPUMS_API_KEY"))

ds = ipums.get_metadata(NhgisDatasetMetadata("2000_SF1a"))
```

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

### ipumspy.ddi.VariableDescription

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/ddi.rst

Represents the description of a variable within a DDI Codebook.

```APIDOC
## Class: ipumspy.ddi.VariableDescription

### Description
Represents the description of a variable within a DDI Codebook. This class holds detailed metadata for a single variable, including its name, label, type, and value information.

### Usage
```python
# Example usage (typically accessed via a Codebook object)
from ipumspy.ddi import Codebook

# codebook = Codebook('path/to/your/ddi.xml')
# if codebook.variables:
#     first_variable = codebook.variables['variable_name'] # Access by name
#     print(f"Variable Label: {first_variable.label}")
#     print(f"Variable Type: {first_variable.type}")
```

### Attributes
- **name**: The unique name of the variable.
- **label**: A descriptive label for the variable.
- **type**: The data type of the variable (e.g., 'numeric', 'character').
- **values**: Information about the possible values and their meanings (codes).
- **missing_values**: Information about missing value codes.
```

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

### List Files in Aggregate Data Zip Archive

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reading_data.rst

Lists the names of files contained within a compressed IPUMS aggregate data zip archive using Python's zipfile module.

```python
from zipfile import ZipFile
import pandas as pd

fname = "<path/to/zip/file>"

# a list of individual file names from inside the .zip file
names = ZipFile(fname).namelist()
#> ['nhgis0025_csv/nhgis0025_ds120_1990_county_codebook.txt', 'nhgis0025_csv/nhgis0025_ds120_1990_county.csv']
```

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

### Create Microdata Extract Request

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Defines a microdata extract request for specific samples and variables. The available extract definition options vary across collections.

```python
extract = MicrodataExtract(
    collection="usa",
    description="Sample USA extract",
    samples=["us2018a", "us2019a"],
    variables=["AGE", "SEX", "RACE", "STATEFIP", "MARST"],
)
```

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

### Select Detailed Race Codes

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Filter the extract using detailed race codes for specific combinations (e.g., White and Asian). Set general=False to use detailed codes.

```python
extract.select_cases("RACE", 
                         ["810", "811", "812", "813", "814", "815", "816", "818"], 
                         general=False)
```

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

### Specify CSV Data Format

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Specify the desired data format for the extract by setting the 'data_format' argument to 'csv'.

```python
extract = MicrodataExtract(
    collection="usa",
    samples=["us2012b"],
    variables=["AGE", "SEX"],
    description="An IPUMS extract example",
    data_format="csv",
)
```

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

### Load IPUMS Extract Definition from YAML Dictionary

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/index.rst

Load an IPUMS extract definition from a YAML file by parsing it into a dictionary and then converting it to a MicrodataExtract object.

```python
import yaml
from ipumspy import extract_from_dict

with open("ipums.yaml") as infile:
    extract = extract_from_dict(yaml.safe_load(infile))
```

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

### Time Series Table Metadata

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Demonstrates how to retrieve metadata for IPUMS NHGIS time series tables using the `IpumsApiClient` and `TimeSeriesTableMetadata` class.

```APIDOC
## Time Series Table Metadata

### Description
This section explains how to obtain metadata for IPUMS NHGIS time series tables using the `ipumspy` library.

### Method
`IpumsApiClient.get_metadata()`

### Parameters
- `metadata_class_instance`: An instance of `TimeSeriesTableMetadata` initialized with the time series table identifier.

### Request Example
```python
from ipumspy import IpumsApiClient, TimeSeriesTableMetadata

ipums = IpumsApiClient(os.environ.get("IPUMS_API_KEY"))

tst_metadata = ipums.get_metadata(TimeSeriesTableMetadata("CW3"))

# Accessing metadata attributes (example)
# print(tst_metadata.description)
# print(tst_metadata.years)
```
```

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

### Exceptions

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/api.rst

Custom exceptions raised when interacting with the IPUMS API.

```APIDOC
## ipumspy.api.exceptions.IpumsApiException

### Description
Base exception for all IPUMS API related errors.

## ipumspy.api.exceptions.TransientIpumsApiException

### Description
Exception for transient API errors that might be retried.

## ipumspy.api.exceptions.IpumsExtractNotReady

### Description
Exception raised when an extract is not yet ready for download.

## ipumspy.api.exceptions.IpumsTimeoutException

### Description
Exception raised when an API request times out.

## ipumspy.api.exceptions.IpumsAPIAuthenticationError

### Description
Exception raised for authentication errors with the IPUMS API.

## ipumspy.api.exceptions.BadIpumsApiRequest

### Description
Exception raised for malformed or invalid API requests.

## ipumspy.api.exceptions.IpumsExtractNotSubmitted

### Description
Exception raised when an extract has not been submitted.

## ipumspy.api.exceptions.IpumsApiRateLimitException

### Description
Exception raised when the API rate limit is exceeded.
```

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

### Specify NHGIS Dataset with Breakdown Values

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Optionally request specific breakdown values for an NhgisDataset using the breakdown_values keyword argument. If not specified, the first available breakdown is used.

```python
extract = AggregateDataExtract(
   collection="nhgis",
   description="An NHGIS example extract",
   datasets=[
      NhgisDataset(
            name="2000_SF1a",
            data_tables=["NP001A", "NP031A"],
            geog_levels=["state"],
            breakdown_values=["bs21.ge01", "bs21.ge43"],  # Urban + Rural breakdowns
      )
   ],
)
```

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

### Attach Spouse's Age Characteristic

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Use the attach_characteristics method to add the spouse's AGE to the extract, creating a new variable SEX_SP. This method requires the variable to attach and a list of household members (e.g., 'spouse', 'mother', 'father', 'head').

```python
extract.attach_characteristics("SEX", ["spouse"])
```

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

### Configure Extract Using Variable Objects

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_micro/index.rst

Define a complex extract by using `Variable` objects within the `variables` list. This allows specifying attached characteristics, case selections, data quality flags, and monetary value adjustments per variable.

```python
fancy_extract = MicrodataExtract(
    collection="cps",
    samples=["cps2022_03s"],
    variables=[
        Variable(name="AGE",
                 attached_characteristics=["spouse"]),
        Variable(name="SEX",
                 case_selections={"general": ["2"]}),
        Variable(name="RACE",
                 data_quality_flags=True),
        Variable(name="HOURWAGE",
                 adjust_monetary_values=True),
     ],
     description="A fancy CPS extract",
)
```

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

### Read NoExtract Codebook

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/reference/noextract.rst

Reads and returns the codebook for a noextract dataset.

```APIDOC
## read_noextract_codebook

### Description
Reads and returns the codebook for a noextract dataset.

### Method
`ipumspy.noextract.read_noextract_codebook()`

### Parameters
This function does not take any explicit parameters in its signature as presented.
```

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

### Add NHGIS Time Series Tables to Extract

Source: https://github.com/ipums/ipumspy/blob/master/docs/source/ipums_api/ipums_api_aggregate/index.rst

Create an NHGIS aggregate data extract request that includes time series tables. Specify the collection, description, and the time series tables with their geographic levels. Time series tables do not require a separate data table selection.

```python
from ipumspy import AggregateDataExtract, TimeSeriesTable

extract = AggregateDataExtract(
      collection="nhgis",
      description="An NHGIS example extract: time series tables",
      time_series_tables=[TimeSeriesTable("CW3", geog_levels=["county", "state"])],
   )
```