add docs to Profile Plotter

[bemcdonnell]

This can be completed after #174 and #155 (planning)

[wraseman]

I can create an example to include in the docs, I just need to figure out how to deal with an error in build_profile_plot() first. When I try to use the from swmmio import build_profile_plot, find_network_trace code referenced in the pyswmm/pyswmm#531 ticket, I get an error. The issue is that there is no Type attribute associated with links.loc[link_id] and there are several locations where the logic in build_profile_plot() and private methods associated with it use links.loc[link_id].Type to determine whether the link is a conduit, weir, orifice, pump, or outlet. Based on the type of link, it extracts the length information differently.

[bemcdonnell]

@wraseman are you using one of the examples on the PySWMM website?

[wraseman]

@bemcdonnell, I used the jersey .inp file from swmmio.examples. Here's my code:

import matplotlib.pyplot as plt
import copy
from swmmio import find_network_trace, build_profile_plot
from swmmio.examples import jersey

# Load in simple model
model = copy.deepcopy(jersey)
fig, ax = plt.subplots(figsize=(8, 4))
path_selection = find_network_trace(model, 'J1', 'J3')
profile_config = build_profile_plot(ax, model, path_selection)

add_node_labels_plot(ax, model, profile_config)
leg = ax.legend()
ax.grid(False)

The caveat is that I am using a modified version of build_profile_plot() that avoids the error with links.loc[link_id].Type

[bemcdonnell]

@wraseman any chance you be keen to submit a PR to fix this problem?

[wraseman]

@bemcdonnell, digging into this and organizing my thoughts. Right now, the build_profile_plot() method uses the following information to create the plots in profiler.py:

Link	Length	Depth	Upstream Link Offset	Downstream Link Offset
Conduits	Length	Geom1	InOffset	OutOffset
Orifices	N/A	Geom1	InOffset	OutOffset
Pumps	N/A	N/A	N/A	N/A
Outlets	N/A	N/A	N/A	N/A
Weir	N/A	Geom1	CrestHeight	N/A

Entries in the table with N/A are filled in by the code with hard-coded defaults to render the plot.

Again, this logic relies on a Type column being present in the link dataframe. I have found that sometimes the Type column is missing and this will fail in an unexpected way. I need to figure out how the type information is stored in .inp, and if it isn't pulled into the dataframe, what the best way to get it would be.

[aerispaha]

@wraseman, regarding the Type column idea, I've opened #244. I think this is a good idea.
And we should likely do the same thing for the swmmio.Model.nodes dataframes.

What do you think?

[wraseman]

@aerispaha, I totally agree. I'll add a more detailed response to #244.