API Reference

This page provides detailed API documentation for the WRF NLCD LULC converter package.

Main Classes

NLCDProcessor

class wrf_nlcd_lulc_converter.NLCDProcessor(lulc_mapping=None)[source]

Bases: object

Main class for processing NLCD data and updating WRF files.

get_processing_info()[source]

Get information about the current processor configuration.

Returns:: Dictionary with processor information.
Return type:: dict

process_nlcd_and_update_wrf(nlcd_file, wrf_file, output_file, year, margin=1.0, force_recalculate=False, tmp_folder='~/tmp/nlcd_processed/')[source]

Main method to process NLCD data and update WRF file.

Parameters:

nlcd_file (str) – Path to the NLCD GeoTIFF file.
wrf_file (str) – Path to the WRF geo_em file.
output_file (str) – Path for the output updated WRF file.
year (str or int) – Year of the NLCD data.
margin (float) – Margin to add around the WRF domain in degrees.
force_recalculate (bool) – Force recalculation even if files exist.
tmp_folder (str) – Temporary folder for processed files.

Returns:

Path to the updated WRF file.

Return type:

str

process_urban_only(nlcd_file, wrf_file, output_file, year, margin=1.0, force_recalculate=False, tmp_folder='~/tmp/nlcd_processed/')[source]

Process only urban classes from NLCD data.

Parameters:

nlcd_file (str) – Path to the NLCD GeoTIFF file.
wrf_file (str) – Path to the WRF geo_em file.
output_file (str) – Path for the output updated WRF file.
year (str or int) – Year of the NLCD data.
margin (float) – Margin to add around the WRF domain in degrees.
force_recalculate (bool) – Force recalculation even if files exist.
tmp_folder (str) – Temporary folder for processed files.

Returns:

Path to the updated WRF file.

Return type:

str

set_custom_mapping(mapping_dict)[source]

Set a custom NLCD to WRF/GEOG mapping.

Parameters:: mapping_dict (dict) – Custom mapping dictionary.

LULCMapping

class wrf_nlcd_lulc_converter.LULCMapping[source]

Bases: object

Class containing land use/land cover class definitions and color mappings.

get_class_info(class_number)[source]

Get information for a specific LULC class.

Parameters:: class_number (int) – LULC class number (1-40)
Returns:: Dictionary with ‘label’ and ‘color’ keys
Return type:: dict

get_nlcd_to_geog_mapping()[source]

Get the NLCD to WRF/GEOG urban class mapping.

Returns:: Mapping dictionary
Return type:: dict

get_urban_classes()[source]

Get list of urban development classes.

Returns:: List of urban class numbers
Return type:: list

set_custom_mapping(mapping_dict)[source]

Set a custom NLCD to WRF/GEOG mapping.

Parameters:: mapping_dict (dict) – Custom mapping dictionary

Plotting Functions

Plotting utilities for WRF NLCD LULC converter.

wrf_nlcd_lulc_converter.plotting.create_sample_plot()[source]

Create a sample plot for demonstration purposes.

Returns:: Path to the saved plot
Return type:: str

wrf_nlcd_lulc_converter.plotting.plot_coast(ax, houston=True, houston_color='k', houston_linewidth=0.5)[source]

Add coastlines and state boundaries to a cartopy plot.

Parameters:

ax – Cartopy axes object
houston (bool) – Whether to add Houston area outline
houston_color (str) – Color for Houston outline
houston_linewidth (float) – Line width for Houston outline

wrf_nlcd_lulc_converter.plotting.plot_domain_info(wrf_info, title='WRF Domain Information', save_path=None, dpi=150)[source]

Plot WRF domain information with LULC data.

Parameters:

wrf_info (dict) – WRF domain information from extract_wrf_domain_info
title (str) – Plot title
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image

wrf_nlcd_lulc_converter.plotting.plot_lulc_data(longitudes, latitudes, lulc_data, title='LULC Data', extent=None, save_path=None, dpi=150, show_plot=True)[source]

Plot LULC data with proper color mapping and labels.

Parameters:

longitudes (np.ndarray) – Longitude coordinates
latitudes (np.ndarray) – Latitude coordinates
lulc_data (np.ndarray) – LULC class data
title (str) – Plot title
extent (list) – Map extent [lon_min, lon_max, lat_min, lat_max]
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image
show_plot (bool) – Whether to display the plot

wrf_nlcd_lulc_converter.plotting.plot_urban_comparison(original_lulc, updated_lulc, longitudes, latitudes, title='Urban Area Comparison', save_path=None, dpi=150)[source]

Plot comparison of original vs updated urban areas.

Parameters:

original_lulc (np.ndarray) – Original LULC data
updated_lulc (np.ndarray) – Updated LULC data
longitudes (np.ndarray) – Longitude coordinates
latitudes (np.ndarray) – Latitude coordinates
title (str) – Plot title
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image

Colormap Module

Colormap and normalization utilities for WRF NLCD LULC converter.

wrf_nlcd_lulc_converter.colormap.create_colorbar(ax, mappable, orientation='vertical', fraction=0.046, pad=0.04)[source]

Create a standardized colorbar for LULC plots.

Parameters:

ax – Matplotlib axes object
mappable – Mappable object (e.g., pcolormesh result)
orientation (str) – Colorbar orientation
fraction (float) – Colorbar fraction
pad (float) – Colorbar padding

Returns:

The created colorbar

Return type:

matplotlib.colorbar.Colorbar

wrf_nlcd_lulc_converter.colormap.create_urban_colorbar(ax, mappable, orientation='vertical', fraction=0.046, pad=0.04)[source]

Create a standardized colorbar for urban plots.

Parameters:

ax – Matplotlib axes object
mappable – Mappable object (e.g., pcolormesh result)
orientation (str) – Colorbar orientation
fraction (float) – Colorbar fraction
pad (float) – Colorbar padding

Returns:

The created colorbar

Return type:

matplotlib.colorbar.Colorbar

wrf_nlcd_lulc_converter.colormap.get_class_info(class_number)[source]

Get information for a specific LULC class.

Parameters:: class_number (int or float) – LULC class number (1-40)
Returns:: Dictionary with ‘label’ and ‘color’ keys
Return type:: dict

wrf_nlcd_lulc_converter.colormap.get_lulc_colormap()[source]

Get the 40-class LULC colormap from the original notebook.

Returns:: (colormap, labels, colors, vmin, vmax)
Return type:: tuple

wrf_nlcd_lulc_converter.colormap.get_lulc_normalization()[source]

Get the normalization for LULC data plotting.

Returns:: (vmin, vmax, ticks, tick_labels)
Return type:: tuple

wrf_nlcd_lulc_converter.colormap.get_urban_classes()[source]

Get list of urban development classes.

Returns:: List of urban class numbers
Return type:: list

wrf_nlcd_lulc_converter.colormap.get_urban_colormap()[source]

Get a colormap specifically for urban classes (21-26).

Returns:: (colormap, labels, colors, vmin, vmax)
Return type:: tuple

wrf_nlcd_lulc_converter.colormap.get_urban_normalization()[source]

Get the normalization for urban data plotting.

Returns:: (vmin, vmax, ticks, tick_labels)
Return type:: tuple

wrf_nlcd_lulc_converter.colormap.plot_colormap_legend(save_path=None, dpi=150)[source]

Create a legend showing all LULC classes and their colors.

Parameters:

save_path (str) – Path to save the legend (optional)
dpi (int) – DPI for saved image

Utility Functions

Utility functions for WRF NLCD LULC converter.

wrf_nlcd_lulc_converter.utils.calculate_nlcd_crop_domain(wrf_domain, margin=1.0)[source]

Calculate the NLCD crop domain based on WRF domain with margin.

Parameters:

wrf_domain (dict) – WRF domain dictionary.
margin (float) – Margin to add around the domain in degrees.

Returns:

NLCD crop domain dictionary.

Return type:

dict

wrf_nlcd_lulc_converter.utils.create_output_directory(output_path)[source]

Create output directory if it doesn’t exist.

Parameters:: output_path (str) – Path to the output directory or file.

wrf_nlcd_lulc_converter.utils.crop_nlcd_with_gdalwarp(raw_NLCD_map, year, nlcd_domain, nlcd_processed_tmp_folder='~/tmp/nlcd_processed/', output_NLCD_crop_filename=None, force_recalculate=False)[source]

Crop the NLCD GeoTIFF using gdalwarp for a given year and domain.

Parameters:

raw_NLCD_map (str) – Path to the raw NLCD GeoTIFF file.
year (int or str) – Year of the NLCD data (used in output filename).
nlcd_domain (dict) – Dictionary with keys ‘lon_min’, ‘lon_max’, ‘lat_min’, ‘lat_max’.
nlcd_processed_tmp_folder (str) – Temporary folder for processed files.
output_NLCD_crop_filename (str) – Output filename for cropped file.
force_recalculate (bool) – Force recalculation even if file exists.

Returns:

Path to the cropped NLCD GeoTIFF.

Return type:

str

wrf_nlcd_lulc_converter.utils.extract_wrf_domain_info(wrf_file)[source]

Extract domain information from a WRF geo_em file.

Parameters:: wrf_file (str) – Path to the WRF geo_em file.
Returns:: Dictionary containing domain information.
Return type:: dict

wrf_nlcd_lulc_converter.utils.generate_landusef_from_lu_index(lu_index, nclass=None, dtype=<class 'numpy.float32'>)[source]

Generate a LANDUSEF-style array from a LU_INDEX array.

Parameters:

lu_index (np.ndarray) – 2D array of land use class indices (ny, nx).
nclass (int) – Number of land use classes.
dtype (np.dtype) – Data type for the output array.

Returns:

Array of shape (1, nclass, ny, nx) with one-hot encoding for each class.

Return type:

np.ndarray

wrf_nlcd_lulc_converter.utils.update_lu_index_and_landusef_in_netcdf(ncfile, new_lu_index, new_landusef)[source]

Update LU_INDEX and LANDUSEF variables in a NetCDF file.

Parameters:

ncfile (str) – Path to the NetCDF file.
new_lu_index (np.ndarray) – New LU_INDEX data.
new_landusef (np.ndarray) – New LANDUSEF data.

wrf_nlcd_lulc_converter.utils.validate_file_paths(*file_paths)[source]

Validate that all file paths exist.

Parameters:: *file_paths – Variable number of file paths to validate.
Raises:: FileNotFoundError – If any file path doesn’t exist.

Command Line Interface

Command-line interface for WRF NLCD LULC converter.

wrf_nlcd_lulc_converter.cli.main()[source]: Main command-line interface function.

Package Information

WRF NLCD LULC Converter

A Python package for converting National Land Cover Database (NLCD) land use data and updating WRF (Weather Research and Forecasting) geo_em files with new land use information.

class wrf_nlcd_lulc_converter.LULCMapping[source]

Bases: object

Class containing land use/land cover class definitions and color mappings.

get_class_info(class_number)[source]

Get information for a specific LULC class.

Parameters:: class_number (int) – LULC class number (1-40)
Returns:: Dictionary with ‘label’ and ‘color’ keys
Return type:: dict

get_nlcd_to_geog_mapping()[source]

Get the NLCD to WRF/GEOG urban class mapping.

Returns:: Mapping dictionary
Return type:: dict

get_urban_classes()[source]

Get list of urban development classes.

Returns:: List of urban class numbers
Return type:: list

set_custom_mapping(mapping_dict)[source]

Set a custom NLCD to WRF/GEOG mapping.

Parameters:: mapping_dict (dict) – Custom mapping dictionary

class wrf_nlcd_lulc_converter.NLCDProcessor(lulc_mapping=None)[source]

Bases: object

Main class for processing NLCD data and updating WRF files.

get_processing_info()[source]

Get information about the current processor configuration.

Returns:: Dictionary with processor information.
Return type:: dict

process_nlcd_and_update_wrf(nlcd_file, wrf_file, output_file, year, margin=1.0, force_recalculate=False, tmp_folder='~/tmp/nlcd_processed/')[source]

Main method to process NLCD data and update WRF file.

Parameters:

nlcd_file (str) – Path to the NLCD GeoTIFF file.
wrf_file (str) – Path to the WRF geo_em file.
output_file (str) – Path for the output updated WRF file.
year (str or int) – Year of the NLCD data.
margin (float) – Margin to add around the WRF domain in degrees.
force_recalculate (bool) – Force recalculation even if files exist.
tmp_folder (str) – Temporary folder for processed files.

Returns:

Path to the updated WRF file.

Return type:

str

process_urban_only(nlcd_file, wrf_file, output_file, year, margin=1.0, force_recalculate=False, tmp_folder='~/tmp/nlcd_processed/')[source]

Process only urban classes from NLCD data.

Parameters:

nlcd_file (str) – Path to the NLCD GeoTIFF file.
wrf_file (str) – Path to the WRF geo_em file.
output_file (str) – Path for the output updated WRF file.
year (str or int) – Year of the NLCD data.
margin (float) – Margin to add around the WRF domain in degrees.
force_recalculate (bool) – Force recalculation even if files exist.
tmp_folder (str) – Temporary folder for processed files.

Returns:

Path to the updated WRF file.

Return type:

str

set_custom_mapping(mapping_dict)[source]

Set a custom NLCD to WRF/GEOG mapping.

Parameters:: mapping_dict (dict) – Custom mapping dictionary.

wrf_nlcd_lulc_converter.create_colorbar(ax, mappable, orientation='vertical', fraction=0.046, pad=0.04)[source]

Create a standardized colorbar for LULC plots.

Parameters:

ax – Matplotlib axes object
mappable – Mappable object (e.g., pcolormesh result)
orientation (str) – Colorbar orientation
fraction (float) – Colorbar fraction
pad (float) – Colorbar padding

Returns:

The created colorbar

Return type:

matplotlib.colorbar.Colorbar

wrf_nlcd_lulc_converter.create_sample_plot()[source]

Create a sample plot for demonstration purposes.

Returns:: Path to the saved plot
Return type:: str

wrf_nlcd_lulc_converter.create_urban_colorbar(ax, mappable, orientation='vertical', fraction=0.046, pad=0.04)[source]

Create a standardized colorbar for urban plots.

Parameters:

ax – Matplotlib axes object
mappable – Mappable object (e.g., pcolormesh result)
orientation (str) – Colorbar orientation
fraction (float) – Colorbar fraction
pad (float) – Colorbar padding

Returns:

The created colorbar

Return type:

matplotlib.colorbar.Colorbar

wrf_nlcd_lulc_converter.generate_landusef_from_lu_index(lu_index, nclass=None, dtype=<class 'numpy.float32'>)[source]

Generate a LANDUSEF-style array from a LU_INDEX array.

Parameters:

lu_index (np.ndarray) – 2D array of land use class indices (ny, nx).
nclass (int) – Number of land use classes.
dtype (np.dtype) – Data type for the output array.

Returns:

Array of shape (1, nclass, ny, nx) with one-hot encoding for each class.

Return type:

np.ndarray

wrf_nlcd_lulc_converter.get_class_info(class_number)[source]

Get information for a specific LULC class.

Parameters:: class_number (int or float) – LULC class number (1-40)
Returns:: Dictionary with ‘label’ and ‘color’ keys
Return type:: dict

wrf_nlcd_lulc_converter.get_lulc_colormap()[source]

Get the 40-class LULC colormap from the original notebook.

Returns:: (colormap, labels, colors, vmin, vmax)
Return type:: tuple

wrf_nlcd_lulc_converter.get_lulc_normalization()[source]

Get the normalization for LULC data plotting.

Returns:: (vmin, vmax, ticks, tick_labels)
Return type:: tuple

wrf_nlcd_lulc_converter.get_urban_classes()[source]

Get list of urban development classes.

Returns:: List of urban class numbers
Return type:: list

wrf_nlcd_lulc_converter.get_urban_colormap()[source]

Get a colormap specifically for urban classes (21-26).

Returns:: (colormap, labels, colors, vmin, vmax)
Return type:: tuple

wrf_nlcd_lulc_converter.get_urban_normalization()[source]

Get the normalization for urban data plotting.

Returns:: (vmin, vmax, ticks, tick_labels)
Return type:: tuple

wrf_nlcd_lulc_converter.plot_colormap_legend(save_path=None, dpi=150)[source]

Create a legend showing all LULC classes and their colors.

Parameters:

save_path (str) – Path to save the legend (optional)
dpi (int) – DPI for saved image

wrf_nlcd_lulc_converter.plot_domain_info(wrf_info, title='WRF Domain Information', save_path=None, dpi=150)[source]

Plot WRF domain information with LULC data.

Parameters:

wrf_info (dict) – WRF domain information from extract_wrf_domain_info
title (str) – Plot title
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image

wrf_nlcd_lulc_converter.plot_lulc_data(longitudes, latitudes, lulc_data, title='LULC Data', extent=None, save_path=None, dpi=150, show_plot=True)[source]

Plot LULC data with proper color mapping and labels.

Parameters:

longitudes (np.ndarray) – Longitude coordinates
latitudes (np.ndarray) – Latitude coordinates
lulc_data (np.ndarray) – LULC class data
title (str) – Plot title
extent (list) – Map extent [lon_min, lon_max, lat_min, lat_max]
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image
show_plot (bool) – Whether to display the plot

wrf_nlcd_lulc_converter.plot_urban_comparison(original_lulc, updated_lulc, longitudes, latitudes, title='Urban Area Comparison', save_path=None, dpi=150)[source]

Plot comparison of original vs updated urban areas.

Parameters:

original_lulc (np.ndarray) – Original LULC data
updated_lulc (np.ndarray) – Updated LULC data
longitudes (np.ndarray) – Longitude coordinates
latitudes (np.ndarray) – Latitude coordinates
title (str) – Plot title
save_path (str) – Path to save the plot (optional)
dpi (int) – DPI for saved image