pyincore_data

censusutil

class censusutil.CensusUtil

Utility methods for Census data and API

static demographic_factors(state_code, county_code, year, geo_type='tract:*')

Create Geopandas DataFrame for population demographics for a particular county from census dataset.

Parameters:

  • state_code (int) – state FIPS code.

  • county_code (int) – county FIPS code.

  • year (str) – Census Year.

  • geo_type (str) – Name of geo area. e.g, ‘tract:’ or ‘block%20group:’

Returns:

A dataframe of population demographics for a particular county

Return type:

obj

static download_couty_shapefile(state_county_list, download_dir)

Download and extract shapefiles for selected counties.

Parameters:
Returns:

A list of GeoPandas GeoDataFrames containing block groups for all of the selected counties.

Return type:

list

static generate_census_api_url(state: str = None, county: str = None, year: str = None, data_source: str = None, columns: str = None, geo_type: str = None, data_name: str = None)

Create url string to access census data api.

Parameters:

  • state (str) – A string of state FIPS with comma separated format. e.g, ‘41, 42’ or ‘*’

  • county (str) – A string of county FIPS with comma separated format. e.g, ‘017,029,045,091,101’ or ‘*’

  • year (str) – Census Year.

  • data_source (str) – Census dataset name. Can be found from https://api.census.gov/data.html

  • columns (str) – Column names for request data with comma separated format. e.g, ‘GEO_ID,NAME,P005001,P005003,P005004,P005010’

  • geo_type (str) – Name of geo area. e.g, ‘tract:’ or ‘block%20group:’

  • data_name (str) – Optional for getting different dataset. e.g, ‘component’

Returns:

A string for representing census api url

Return type:

string

static get_blockgroupdata_for_dislocation(state_counties: list, vintage: str = '2010', dataset_name: str = 'dec/sf1', out_csv: bool = False, out_shapefile: bool = False, out_geopackage: bool = False, out_html: bool = False, geo_name: str = 'geo_name', program_name: str = 'program_name')

Create Geopandas DataFrame for population dislocation analysis from census dataset.

Parameters:

  • state_counties (list) – A List of concatenated State and County FIPS Codes. see full list https://www.nrcs.usda.gov/wps/portal/nrcs/detail/national/home/?cid=nrcs143_013697

  • vintage (str) – Census Year.

  • dataset_name (str) – Census dataset name.

  • out_csv (bool) – Save output dataframe as csv.

  • out_shapefile (bool) – Save processed census geodataframe as shapefile.

  • out_geopackage (bool) – Save processed census geodataframe as geopackage

  • out_html (bool) – Save processed folium map to html.

  • geo_name (str) – Name of geo area - used for naming output files.

  • program_name (str) – Name of directory used to save output files.

Returns:

A dataframe for dislocation analysis, a dictionary containing geodataframe and folium map, and a dataset object created by downloaded geo data

Return type:

obj, dict, obj

static get_census_data(state: str = None, county: str = None, year: str = None, data_source: str = None, columns: str = None, geo_type: str = None, data_name: str = None)

Create json and pandas DataFrame for census api request result.

Parameters:

  • state (str) – A string of state FIPS with comma separated format. e.g, ‘41, 42’ or ‘*’

  • county (str) – A string of county FIPS with comma separated format. e.g, ‘017,029,045,091,101’ or ‘*’

  • year (str) – Census Year.

  • data_source (str) – Census dataset name. Can be found from https://api.census.gov/data.html

  • columns (str) – Column names for request data with comma separated format. e.g, ‘GEO_ID,NAME,P005001,P005003,P005004,P005010’

  • geo_type (str) – Name of geo area. e.g, ‘tract:’ or ‘block%20group:’

  • data_name (str) – Optional for getting different dataset. e.g, ‘component’

Returns:

A json list, a dataframe for census api result,

and pyincore dataset

Return type:

dict, obj, obj

static get_fips_by_state(state: str, year: str = 2010)

Create Geopandas DataFrame for population dislocation analysis from census dataset.

Parameters:

state (str) – State name. e.g, ‘illinois’

Returns:

A json list of county FIPS code in the given state

Return type:

obj

static get_fips_by_state_county(state: str, county: str, year: str = 2010)

Get FIPS code by using state and county name.

Parameters:

  • state (str) – State name. e.g, ‘illinois’

  • county (str) – County name. e.g, ‘champaign’

Returns:

A string of FIPS code

Return type:

str

static national_ave_values(year, data_source='acs/acs5')

Create Geopandas DataFrame for national population demographics from census dataset.

Parameters:
Returns:

A list of dictionaries denoting population demographics for the nation

Return type:

list

static request_census_api(data_url)

Request census data to api and gets the output data

Parameters:

data_url (str) – url for obtaining the data from census api

Returns:

A json list and a dataframe for census api result

Return type:

dict, object

censusviz

class censusviz.CensusViz

Utility methods for Census data and visualization

static create_choro_data_from_pd(pd, key)

Create choropleth choro-data from dataframe.

Parameters:

  • pd (object) – an Input dataframe.

  • key (str) – a string for dictionary key

Returns:

A dictionary of dataframe

Return type:

obj

static create_choropleth_layer(geo_data, choro_data, name)

Create ipyleaflet layer for choropleth map.

Parameters:

  • geo_data (object) – dictionary from geodataframe

  • choro_data (object) – choropleth data from geodataframe

  • name (str) – name for the layer

Returns:

An ipyleaflet layer

Return type:

obj

static create_dislocation_folium_map_from_gpd(in_gpd)

Create folium dislocation map for geodataframe.

Parameters:

in_gpd (object) – Geodataframe of the dislocation.

Returns:

A folium map for dislocation

Return type:

obj

static create_dislocation_ipyleaflet_map_from_gpd(in_gpd, zoom_level=10)

Create ipyleaflet dislocation map for geodataframe.

Parameters:

  • in_gpd (object) – Geodataframe of the dislocation.

  • zoom_level (int) – default zoom level for the map

Returns:

An ipyleaflet map for dislocation

Return type:

obj

static create_ipyleafletmap_from_geodataframe(gpd, zoom_level=100)

Create base ipyleaflet map from geodataframe.

Parameters:

  • gpd (object) – Geodataframe of the dislocation.

  • zoom_level (int) – default zoom level for the map

Returns:

An ipyleaflet map for dislocation

Return type:

obj

static save_dislocation_map_to_html(folium_map, programname, savefile)

Save folium dislocation map to html.

Parameters:

  • folium_map (object) – Folium map object.

  • programname (str) – Name of the program.

  • savefile (str) – Name of the file to save.

datautil

class utils.datautil.DataUtil
static add_columns_to_gdf(gdf, fips)

Adds FIPS-related columns (FIPS, state FIPS, and county FIPS) to the GeoDataFrame.

Parameters:

  • gdf (gpd.GeoDataFrame) – Input GeoDataFrame.

  • fips (str) – Combined state and county FIPS code.

Returns:

GeoDataFrame with new FIPS-related columns.

Return type:

gpd.GeoDataFrame

static add_guid_to_gdf(gdf)

Adds a globally unique identifier (GUID) column to the GeoDataFrame.

Parameters:

gdf (gpd.GeoDataFrame) – Input GeoDataFrame.

Returns:

GeoDataFrame with a new ‘guid’ column.

Return type:

gpd.GeoDataFrame

static convert_dislocation_gpd_to_geopackage(in_gpd, programname, savefile)

Create shapefile of dislocation geodataframe.

Parameters:

  • in_gpd (object) – Geodataframe of the dislocation.

  • programname (str) – Output directory name.

  • savefile (str) – Output shapefile name.

static convert_dislocation_gpd_to_shapefile(in_gpd, programname, savefile)

Create shapefile of dislocation geodataframe.

Parameters:

  • in_gpd (object) – Geodataframe of the dislocation.

  • programname (str) – Output directory name.

  • savefile (str) – Output shapefile name.

static convert_dislocation_pd_to_csv(in_pd, save_columns, programname, savefile)

Create csv of dislocation dataframe using the column names.

Parameters:

  • in_pd (object) – Geodataframe of the dislocation.

  • save_columns (list) – A list of column names to use.

  • programname (str) – Output directory name.

  • savefile (str) – Output csv file name.

static download_nsi_data_state_file(state_fips)

Downloads a zipped GeoPackage file for the given state FIPS code from the NSI endpoint.

Parameters:

state_fips (str) – The state FIPS code (e.g., ‘29’ for Missouri).

Returns:

None

static gdf_to_geopkg(gdf, outfile)

Saves a GeoDataFrame as a GeoPackage file.

Parameters:

  • gdf (gpd.GeoDataFrame) – Input GeoDataFrame.

  • outfile (str) – Path to the output GeoPackage file.

Returns:

None

static get_features_by_fips(state_county_fips)

Downloads a GeoJSON feature collection from the NSI endpoint using the provided county FIPS code and returns it as a GeoDataFrame with additional columns for FIPS, state FIPS, and county FIPS.

Parameters:

state_county_fips (str) – The combined state and county FIPS code (e.g., ‘15005’).

Returns:

A GeoDataFrame containing the features with additional columns.

Return type:

gpd.GeoDataFrame

static read_geopkg_to_gdf(infile)

Reads a GeoPackage file and converts it into a GeoDataFrame.

Parameters:

infile (str) – Path to the GeoPackage file.

Returns:

A GeoDataFrame containing data from the GeoPackage file.

Return type:

gpd.GeoDataFrame

static upload_postgres_from_gpkg(infile)

Reads data from a GeoPackage file and uploads it to a PostgreSQL database.

Parameters:

infile (str) – Path to the GeoPackage file.

Returns:

None

static upload_postgres_gdf(gdf)

Uploads a GeoDataFrame to a PostgreSQL database.

Parameters:

gdf (gpd.GeoDataFrame) – Input GeoDataFrame.

Returns:

True if upload is successful, False otherwise.

Return type:

bool