diff --git a/documentation/model_io.rst b/documentation/model_io.rst index f7702791..bcd5b763 100644 --- a/documentation/model_io.rst +++ b/documentation/model_io.rst @@ -206,10 +206,11 @@ GeoJSON files GeoJSON files are commonly used to store geographic data structures. More information on GeoJSON files can be found at https://geojson.org. -To use GeoJSON files in WNTR, a set of valid base column names are required. -Valid base GeoJSON column names can be obtained using the -:class:`~wntr.network.io.valid_gis_names` function. -The following example returns valid base GeoJSON column names for junctions. +When reading GeoJSON files into WNTR, only a set of valid column names can be used. +Valid GeoJSON column names can be obtained using the +:class:`~wntr.network.io.valid_gis_names` function. By default, the function +returns all column names, both required and optional. +The following example returns valid GeoJSON column names for junctions. .. doctest:: :skipif: gpd is None @@ -218,8 +219,9 @@ The following example returns valid base GeoJSON column names for junctions. >>> print(geojson_column_names['junctions']) ['name', 'elevation', 'geometry', 'emitter_coefficient', 'initial_quality', 'minimum_pressure', 'required_pressure', 'pressure_exponent', 'tag'] -A minimal list of valid column names can also be obtained by setting ``complete_list`` to False. -Column names that are optional (i.e., ``initial_quality``) and not included in the GeoJSON file are defined using default values. +A minimal list of required column names can also be obtained by setting ``complete_list`` to False. +Column names that are optional (i.e., ``initial_quality``) and not included in the GeoJSON file are +defined using default values. .. doctest:: :skipif: gpd is None @@ -253,7 +255,7 @@ Note that patterns, curves, sources, controls, and options are not stored in the The :class:`~wntr.network.io.read_geojson` function creates a WaterNetworkModel from a dictionary of GeoJSON files. -Valid base column names and additional custom attributes are added to the model. +Valid column names and additional custom attributes are added to the model. The function can also be used to append information from GeoJSON files into an existing WaterNetworkModel. .. doctest:: @@ -300,11 +302,12 @@ To use Esri Shapefiles in WNTR, several formatting requirements are enforced: assumed that the first 10 characters of each attribute are unique. * To create WaterNetworkModel from Shapefiles, a set of valid field names are required. - Valid base Shapefiles field names can be obtained using the - :class:`~wntr.network.io.valid_gis_names` function. - For Shapefiles, the `truncate` input parameter should be set to 10 (characters). - The following example returns valid base Shapefile field names for junctions. - Note that attributes like ``base_demand`` are truncated to ``base_deman``. + Valid Shapefiles field names can be obtained using the + :class:`~wntr.network.io.valid_gis_names` function. By default, the function + returns all column names, both required and optional. + For Shapefiles, the `truncate_names` input parameter should be set to 10 (characters). + The following example returns valid Shapefile field names for junctions. + Note that attributes like ``minimum_pressure`` are truncated to ``minimum_pr``. .. doctest:: :skipif: gpd is None @@ -313,7 +316,7 @@ To use Esri Shapefiles in WNTR, several formatting requirements are enforced: >>> print(shapefile_field_names['junctions']) ['name', 'elevation', 'geometry', 'emitter_co', 'initial_qu', 'minimum_pr', 'required_p', 'pressure_e', 'tag'] - A minimal list of valid field names can also be obtained by setting ``complete_list`` to False. + A minimal list of required field names can also be obtained by setting ``complete_list`` to False. Field names that are optional (i.e., ``initial_quality``) and not included in the Shapefile are defined using default values. .. doctest:: @@ -349,7 +352,7 @@ Note that patterns, curves, sources, controls, and options are not stored in the The :class:`~wntr.network.io.read_shapefile` function creates a WaterNetworkModel from a dictionary of Shapefile directories. -Valid base field names and additional custom field names are added to the model. +Valid field names and additional custom field names are added to the model. The function can also be used to append information from Shapefiles into an existing WaterNetworkModel. .. doctest:: diff --git a/wntr/gis/network.py b/wntr/gis/network.py index 29e6bc7f..dd1a633e 100644 --- a/wntr/gis/network.py +++ b/wntr/gis/network.py @@ -99,8 +99,11 @@ def _create_gis(self, wn, crs: str = None, pumps_as_points: bool = False, Represent valves as points (True) or lines (False), by default False """ - def _extract_geodataframe(df, crs=None, valid_base_names=[], + def _extract_geodataframe(df, crs=None, valid_base_names=None, links_as_points=False): + if valid_base_names is None: + valid_base_names = [] + # Drop any column with all NaN, this removes excess attributes # Valid base attributes that have all None values are added back # at the end of this routine diff --git a/wntr/network/io.py b/wntr/network/io.py index e4ceac8d..a299e459 100644 --- a/wntr/network/io.py +++ b/wntr/network/io.py @@ -644,12 +644,13 @@ def valid_gis_names(complete_list=True, truncate_names=None): Valid column/field names for GeoJSON or Shapefiles Note that Shapefile field names are truncated to 10 characters - (set truncate=10) + (set truncate_names=10) Parameters ---------- complete_list : bool - Include a complete list of column/field names (beyond basic attributes) + When true, returns both optional and required column/field names. + When false, only returns required column/field names. truncate_names : None or int Truncate column/field names to specified number of characters, set truncate=10 for Shapefiles. None indicates no truncation.