> ## Documentation Index > Fetch the complete documentation index at: https://pyfia.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # FIA Database # `pyfia.core.fia` Core FIA database class and functionality for pyFIA. This module provides the main FIA class that handles database connections, EVALID-based filtering, and common FIA data operations. ## Functions ### `resolve_eval_typ_codes` ```python theme={null} resolve_eval_typ_codes(eval_type: str) -> list[str] ``` Resolve an `eval_type` token to its FIA `EVAL_TYP` code(s). Accepts both friendly tokens (`"VOL"`, `"GRM"`, `"GROW"` ...) and raw `EVAL_TYP` codes (`"EXPVOL"` ...). `"GRM"` expands to the full growth/removal/mortality family. **Args:** * `eval_type`: Evaluation type token or raw `EVAL_TYP` code (case-insensitive). **Returns:** * One or more `EVAL_TYP` codes to match against `POP_EVAL_TYP`. ## Classes ### `FIA` Main FIA database class for working with Forest Inventory and Analysis data. This class provides methods for loading FIA data from DuckDB databases, filtering by EVALID, and preparing data for estimation functions. **Attributes:** * `db_path`: Path to the DuckDB database or MotherDuck connection string. * `tables`: Loaded FIA tables as lazy frames. * `evalid`: Active EVALID filter. * `most_recent`: Whether to use most recent evaluations. **Methods:** #### `from_download` ```python theme={null} from_download(cls, states: str | list[str], dir: str | Path | None = None, common: bool = True, tables: list[str] | None = None, force: bool = False, show_progress: bool = True) -> FIA ``` Download FIA data and return a connected FIA instance. This is a convenience method that combines downloading data from the FIA DataMart with opening a database connection. **Args:** * `states`: State abbreviations (e.g., 'GA', 'NC') or 'REF' for reference tables. Supports multiple states: \['GA', 'FL', 'SC'] * `dir`: Directory to save downloaded data. Defaults to \~/.pyfia/data/ * `common`: If True, download only tables required for pyFIA functions. * `tables`: Specific tables to download. Overrides `common` parameter. * `force`: If True, re-download even if files exist locally. * `show_progress`: Show download progress bars. **Returns:** * Connected FIA database instance. **Examples:** > > > # Download and open Georgia data > > > > > > db = FIA.from\_download("GA") > > > db.clip\_most\_recent() > > > result = db.area() > > > > > > # Download multiple states > > > > > > db = FIA.from\_download(\["GA", "FL", "SC"]) #### `query` ```python theme={null} query(self, sql: str) -> pl.DataFrame ``` Execute a read-only SQL query against the FIA database. Runs a raw SQL query against the underlying database connection. Only SELECT statements are allowed. **Args:** * `sql`: SQL SELECT query to execute. **Returns:** * Query results as a Polars DataFrame. **Examples:** > > > with FIA("data/georgia.duckdb") as db: > > > ... result = db.query("SELECT FORTYPCD, COUNT(\*) as n FROM COND GROUP BY FORTYPCD") #### `load_table` ```python theme={null} load_table(self, table_name: str, columns: list[str] | None = None, where: str | None = None) -> pl.LazyFrame ``` Load a table from the FIA database as a lazy frame. **Args:** * `table_name`: Name of the FIA table to load (e.g., 'PLOT', 'TREE', 'COND'). * `columns`: Columns to load. Loads all columns if None. * `where`: Additional SQL WHERE clause to apply (without 'WHERE' keyword). Used for database-side filtering to reduce memory usage. **Returns:** * Polars LazyFrame of the requested table. #### `find_evalid` ```python theme={null} find_evalid(self, most_recent: bool = True, state: int | list[int] | None = None, year: int | list[int] | None = None, eval_type: str | None = None) -> list[int] ``` Find EVALID values matching criteria. Identify evaluation IDs for filtering FIA data based on specific criteria. **Args:** * `most_recent`: If True, return only most recent evaluations per state. * `state`: State FIPS code(s) to filter by. * `year`: End inventory year(s) to filter by. * `eval_type`: Evaluation type token. One of 'ALL', 'VOL', 'GRM', 'GROW', 'MORT', 'REMV', 'CHNG', 'DWM', 'REGEN', 'INV', 'CURR', or a raw EVAL\_TYP code (e.g. 'EXPVOL'). 'GRM' is an alias for the growth/removal/ mortality family. Unknown tokens raise ValueError. **Returns:** * EVALID values matching the specified criteria. #### `clip_by_evalid` ```python theme={null} clip_by_evalid(self, evalid: int | list[int]) -> FIA ``` Filter FIA data by EVALID (evaluation ID). This is the core filtering method that ensures statistically valid plot groupings by evaluation. **Args:** * `evalid`: Single EVALID or list of EVALIDs to filter by. **Returns:** * Self for method chaining. #### `clip_by_state` ```python theme={null} clip_by_state(self, state: int | list[int], most_recent: bool = True, eval_type: str | None = 'ALL') -> FIA ``` Filter FIA data by state code(s). This method efficiently filters data at the database level by: 1. Setting a state filter for direct table queries 2. Finding appropriate EVALIDs for the state(s) 3. Combining both filters for optimal performance **Args:** * `state`: Single state FIPS code or list of codes. * `most_recent`: If True, use only most recent evaluations. * `eval_type`: Evaluation type to use. Default 'ALL' for EXPALL which is appropriate for area estimation. Use None to get all types. **Returns:** * Self for method chaining. #### `clip_most_recent` ```python theme={null} clip_most_recent(self, eval_type: str = 'VOL') -> FIA ``` Filter to most recent evaluation of specified type. **Args:** * `eval_type`: Evaluation type token. 'VOL' for volume/biomass/TPA/area; 'GRM' for growth, removals, and mortality together (or the component-specific 'GROW', 'MORT', 'REMV'); 'CHNG' for change. See find\_evalid for the full list of accepted tokens. **Returns:** * Self for method chaining. #### `clip_by_polygon` ```python theme={null} clip_by_polygon(self, polygon: str | Path, predicate: str = 'intersects') -> FIA ``` Filter FIA plots to those within or intersecting a polygon boundary. Uses DuckDB spatial extension for efficient point-in-polygon filtering. Supports Shapefiles, GeoJSON, GeoPackage, and GeoParquet formats. **Args:** * `polygon`: Path to spatial file containing polygon(s). Supported formats: * Shapefile (.shp) * GeoJSON (.geojson, .json) * GeoPackage (.gpkg) * GeoParquet (.parquet with geometry) * Any format supported by GDAL/OGR * `predicate`: Spatial predicate for filtering: * 'intersects': Plots that intersect the polygon (recommended) * 'within': Plots completely within the polygon **Returns:** * Self for method chaining. **Examples:** > > > with FIA("southeast.duckdb") as db: > > > ... db.clip\_by\_state(37) # North Carolina > > > ... db.clip\_by\_polygon("my\_region.geojson") > > > ... result = db.tpa() > > > > > > # Using a shapefile > > > > > > with FIA("data.duckdb") as db: > > > ... db.clip\_by\_polygon("counties.shp") > > > ... result = db.area() #### `intersect_polygons` ```python theme={null} intersect_polygons(self, polygon: str | Path, attributes: list[str]) -> FIA ``` Perform spatial join between plots and polygons, adding polygon attributes to plots for use in grp\_by. This method joins polygon attributes to FIA plots based on spatial intersection. The resulting attributes can be used as grouping variables in estimator functions. **Args:** * `polygon`: Path to spatial file containing polygon(s). Supported formats: * Shapefile (.shp) * GeoJSON (.geojson, .json) * GeoPackage (.gpkg) * GeoParquet (.parquet with geometry) * Any format supported by GDAL/OGR * `attributes`: Polygon attribute columns to add to plots. These columns must exist in the polygon file and will be available for grp\_by. **Returns:** * Self for method chaining. **Examples:** > > > with FIA("southeast.duckdb") as db: > > > ... db.clip\_by\_state(37) # North Carolina > > > ... db.intersect\_polygons("counties.shp", attributes=\["NAME", "FIPS"]) > > > ... # Group TPA estimates by county > > > ... result = tpa(db, grp\_by=\["NAME"]) > > > > > > # Use multiple attributes for grouping > > > > > > with FIA("data.duckdb") as db: > > > ... db.intersect\_polygons("regions.geojson", \["REGION", "DISTRICT"]) > > > ... result = area(db, grp\_by=\["REGION", "DISTRICT"]) #### `get_plots` ```python theme={null} get_plots(self, columns: list[str] | None = None) -> pl.DataFrame ``` Get PLOT table filtered by current EVALID, state, and spatial settings. **Args:** * `columns`: Columns to return. Returns all columns if None. **Returns:** * Filtered PLOT dataframe. #### `get_trees` ```python theme={null} get_trees(self, columns: list[str] | None = None) -> pl.DataFrame ``` Get TREE table filtered by current EVALID and state settings. **Args:** * `columns`: Columns to return. Returns all columns if None. **Returns:** * Filtered TREE dataframe. #### `get_conditions` ```python theme={null} get_conditions(self, columns: list[str] | None = None) -> pl.DataFrame ``` Get COND table filtered by current EVALID and state settings. **Args:** * `columns`: Columns to return. Returns all columns if None. **Returns:** * Filtered COND dataframe. #### `prepare_estimation_data` ```python theme={null} prepare_estimation_data(self, include_trees: bool = True) -> dict[str, pl.DataFrame] ``` Prepare standard set of tables for estimation functions. This method loads and filters the core tables needed for most FIA estimation procedures, properly filtered by EVALID. **Args:** * `include_trees`: Whether to include the TREE table. Set to False for area estimation which doesn't need tree data (saves significant memory on constrained environments). **Returns:** * Dictionary with filtered dataframes for estimation containing: 'plot', 'tree', 'cond', 'pop\_plot\_stratum\_assgn', 'pop\_stratum', 'pop\_estn\_unit'. If include\_trees=False, 'tree' will be an empty DataFrame. #### `tpa` ```python theme={null} tpa(self, **kwargs) -> pl.DataFrame ``` Estimate trees per acre. See tpa() function for full parameter documentation. #### `biomass` ```python theme={null} biomass(self, **kwargs) -> pl.DataFrame ``` Estimate biomass. See biomass() function for full parameter documentation. #### `volume` ```python theme={null} volume(self, **kwargs) -> pl.DataFrame ``` Estimate volume. See volume() function for full parameter documentation. #### `mortality` ```python theme={null} mortality(self, **kwargs) -> pl.DataFrame ``` Estimate mortality. See mortality() function for full parameter documentation. #### `area` ```python theme={null} area(self, **kwargs) -> pl.DataFrame ``` Estimate forest area. See area() function for full parameter documentation. #### `growth` ```python theme={null} growth(self, **kwargs) -> pl.DataFrame ``` Estimate annual growth. See growth() function for full parameter documentation. #### `removals` ```python theme={null} removals(self, **kwargs) -> pl.DataFrame ``` Estimate annual removals/harvest. See removals() function for full parameter documentation. #### `area_change` ```python theme={null} area_change(self, **kwargs) -> pl.DataFrame ``` Estimate area change. See area\_change() function for full parameter documentation. ### `MotherDuckFIA` FIA database class for MotherDuck cloud-based access. This class provides the same interface as FIA but connects to MotherDuck instead of a local DuckDB file. MotherDuck is a serverless cloud data warehouse built on DuckDB. **Attributes:** * `database`: Name of the MotherDuck database (e.g., 'fia\_ga') * `motherduck_token`: MotherDuck authentication token **Examples:** > > > from pyfia import MotherDuckFIA > > > db = MotherDuckFIA("fia\_ga", motherduck\_token="your\_token") > > > db.clip\_most\_recent() > > > result = db.area() > > > > > > # Use with context manager > > > > > > with MotherDuckFIA("fia\_nc", motherduck\_token="token") as db: > > > ... db.clip\_most\_recent() > > > ... print(db.area()) **Methods:** #### `close` ```python theme={null} close(self) ``` Close MotherDuck connection.