Exporting Data

Exports write model tables and, when available, selected result snapshots to GIS, CSV, or Excel formats.

m.export.gis()

m.export.gis(
    path="exports/gis",
    elements=["nodes", "links", "subcatchments"],
)

m.export.csv(
    path="exports/csv",
    elements="all",
    time_step=-1,
)

m.export.excel(
    path="exports",
    file_name="model_export.xlsx",
)

Common Options

Option	Description
`path`	Output folder. If omitted, exports go beside the model file or into the current working directory.
`elements`	Named tables, groups such as hydrology/quality, or `"all"`.
`file_name`	Workbook name or prefix for multi-file exports.
`time_step`	Attach result values for a selected output period, commonly `-1` for the last step.
`strict_results`	Treat missing results as an error instead of exporting parameter-only tables.
`overwrite`	Replace existing outputs when supported.

Coordinate fields are included where geometry is available: point objects use [x, y], links use the full coordinate chain, and subcatchments use polygon coordinates when available. Point tables also include plain x and y fields.

Complete Export and Round-Trip Reference

Rendered from 16_all_import_export_functions.ipynb.

19. Export overview

The export API already follows the same model namespace style:

m.export.csv(...)
m.export.gis(...)
m.export.excel(...)

Common export options:

Option	Meaning
`path`	Output folder. If omitted, export beside the model file or in the current working directory.
`file_name`	Single workbook name or prefix for multi-file exports.
`elements`	Named tables, groups such as `hydrology`, or `"all"`.
`time_step`	Result snapshot index; `-1` means the final simulated time step.
`strict_results`	Treat missing results as an error instead of exporting parameter-only tables.
`overwrite`	Replace existing export files when supported.

All CSV, Excel, and GIS exports include a coordinates attribute column. Point objects use [x,y], links use the full coordinate chain, and subcatchments use polygon coordinates when available. Node-based and point-based export tables also include plain x and y columns: all node types use [COORDINATES], rain gages use [SYMBOLS], node-attached rows inherit their node coordinates, and subcatchments use the polygon centre point.

GIS export also requires geopandas and shapely.

Code cell 1

# Save the current in-memory model first so exports have a model context.
model_path = WORK / "import_export_demo.inp"
m.save(model_path)
print(f"Saved model to: {model_path}")

# CSV export: one CSV file per selected table. Exported tables include a coordinates field when map geometry is available; node-based tables also include x/y fields.
csv_result = m.export.csv(path=WORK / "csv_export", elements=["nodes", "links", "subcatchments"])
print(csv_result)

# Excel export requires openpyxl.
# excel_result = m.export.excel(path=WORK / "excel_export", file_name="model_export.xlsx", elements="all")
# print(excel_result)

# GIS export requires geopandas and shapely.
# gis_result = m.export.gis(path=WORK / "gis_export", elements=["nodes", "links"], overwrite=True)
# print(gis_result)

20. Re-importing exported CSV files

CSV tables created by m.export.csv() are intended to be easy to import into a new model or a QA copy. Version 0.0.36 gives exact input fields priority over result or derived fields with similar names. For example, an exported junction table may contain both max_depth and result depth; the importer uses max_depth for the junction and ignores result depth unless you explicitly map it.

Export helper columns are also understood where practical: element_type dispatches group-level node/link imports, stage_data is translated for outfalls, source_data is translated for rain gages, and serialized coordinates can restore subcatchment polygons or link vertices.

Code cell 2

# Round-trip example for CSV files produced by swmmx itself.
# Import dependent tables in dependency order: time series/rain gages/nodes before subcatchments and links.
example_path = Path("example.inp")
if not example_path.exists():
    example_path = Path("examples/example.inp")
source_model = swmm(example_path)
source_model.run()
exported = source_model.export.csv(path=WORK / "round_trip_csv", elements=["time_series", "rain_gages", "nodes", "subcatchments", "links"], time_step=-1, overwrite=True)

copy_model = swmm()
copy_model.import_csv.time.time_series(exported["time_series"])
copy_model.import_csv.node(exported["nodes"])
copy_model.import_csv.hydrology.rain_gage(exported["rain_gages"])
copy_model.import_csv.hydrology.subcatchment(exported["subcatchments"])
copy_model.import_csv.link(exported["links"])

validation = copy_model.validate()
print("Imported exported CSV files successfully:", not validation.errors)

20. Recommended workflow

A robust import/export session usually follows this pattern:

1. Start with dry_run=True and on_unknown_fields="warn" to inspect field matching. 2. Use field_map for any project-specific or ambiguous names. 3. Import reference objects first: nodes, rain gages, curves, and time series. 4. Import dependent objects next: links and subcatchments. 5. Validate the model with m.validate(). 6. Save to a new .inp path. 7. Export CSV/GIS/Excel snapshots for QA.

nodes = m.import_csv.node("nodes.csv", dry_run=True, on_unknown_fields="warn")
print(nodes.summary())
print(nodes.to_frame())

Code cell 3

validation = m.validate()
print("Validation errors:", len(validation.errors))
print("Validation warnings:", len(validation.warnings))

21. Troubleshooting quick reference

Symptom	Likely fix
Missing required field	Check aliases or pass `field_map`. Required fields depend on endpoint.
Ambiguous field error	Two columns matched one canonical field; resolve with `field_map`.
Unknown field error	Use `on_unknown_fields="ignore"` or remove/rename extra columns.
Duplicate ID in add mode	Use `mode="upsert"` or remove existing object first.
Missing ID in update mode	Use `mode="upsert"` or import the object before updating.
GIS dependency error	Install `geopandas` and `shapely`.
Link reference error	Import nodes before links and check `from_node` / `to_node` values.
Subcatchment reference error	Import rain gages and outlet nodes/subcatchments before subcatchments.

When in doubt, start with:

result = m.import_csv.node.junction("junctions.csv", dry_run=True, on_unknown_fields="warn")
print(result.summary())
print(result.to_frame())