We need to write up documentation and make it available as system help

[timlinux]

Problem

We need to have good end-user and technical documentation so that users can understand how to use the system, and developers can understand how to extend it.

Proposed solution

Write up documentation in sphinx explaining how to use the system and link it to a context help button at appropriate places in the UI.

Expected outcome

The user should have clear instructions on how to use the system.

[timlinux]

Here are some graphics to go with documentation. Note that watershed delineation is still unresolved.

@ismailsunni FYI

[ismailsunni]

Some questions:

1. Based on the image, there is possibility that branch == confluence. For example, if upstream node = downstream node = 5. Is it ok?
2. How we define two nodes are same?
3. What's the different between watershed and well ? By looking at the image only, watershed has more than one downstream node. But, we define that well can have more than one downstream node.

[timlinux]

Some questions:

1. Based on the image, there is possibility that branch == confluence. For example, if upstream node = downstream node = 5. Is it ok?

No the logic is based on node counts, not on node id's

1. How we define two nodes are same?

They are the same by having the same geographic position within a user defined tolerance.

1. What's the different between watershed and well ? By looking at the image only, watershed has more than one downstream node. But, we define that well can have more than one downstream node.

I still have to figure out a decent rule for a watershed - could you do a little research on this?

[ismailsunni]

No the logic is based on node counts, not on node id's

Sorry, it should be count(upstream node) = count(downstream node) = 5

I still have to figure out a decent rule for a watershed - could you do a little research on this?

Ok

[timlinux]

Sorry, it should be count(upstream node) = count(downstream node) = 5

Ok in this case if a single node has > 1 upstream nodes and > 1 downstream nodes, it is both a branch and a confluence, which is no problem.

[timlinux]

Adding this table from #12 as it will be useful to add something like this in the docs:

id	line_id	node_type	node_list	node_count	well	sink	confluence	branch	has_pseudonodes	watershed
1	1	upstream	5, 10 , 15	4	1	0	0	0	0	0
2	1	downstream	12, 14, 44	4	0	0	0	0	0	0

[ismailsunni]

By the way: Watershed : An area or ridge of land that separates waters flowing to different rivers, basins, or seas.

I think, watershed refers to the final part of the stream river (and go to the sea)

[timlinux]

Yeah sorry I already know what it is, I meant for you to do some research for an algorithm that delineates a watershed (as opposed to a well). I think that there isn't an easy way to discern between well and watershed.

I think, watershed refers to the final part of the stream river (and go to the sea)

That is normally referred to as a water catchment area.

@tilladams Do you have some feedback on this - what is the client expecting for watershed determination? i.e. how should we discern between wells (no upstream nodes) and watersheds (no upstream nodes).

[ismailsunni]

Update the rules based on @timlinux 's email

1. Crossing / Kreuzung (two features cross each other)
2. Pseudonode / Pseudonode (1 upstream and one downstream) the node is superflous as it can be represented by one line instead of two
3. Well / Quelle (1 upstream node, no downstream nodes)
4. Sink / Senke (no upstream, 1 downstream)
5. Watershed / Top (> 1 upstream, no downstream)
6. Unseparated / Ungetrennter (only 1 upstream or only 1 downstream and intersects with one or more other lines ). Note that in the lines below, there is only one node under the star, the other line has no node at the position of the star.
7. Unclear bifurcation / Unklare Bifukation (>1 upstream, > 1 downstream)
8. Tributary / Verzweigung (branch) (1 downstream, 2 or more upstream)
9. Confluence / Zusammenfluss (1 upstream and 2 or more downstream)

[ismailsunni]

Another notes:

There is one other thing to consider - I believe a confluence can be valid in in streams > outstreams and a tributary can be valid if outstreams > instreams. So for example a node with 3 upstream and 2 downstream would be considered a confluence. And a node with 2 upstream and 3 downstream would be considered a tributary.

So, I can conclude that:

1. Unclear bifurcation has the same number of upstream nodes and downstream nodes and both of them are more than one. So 1 < number of upstream nodes = number downstream nodes
2. Branch 1 <= number of upstream nodes < number downstream nodes
3. Confluence 1 <= number of downstream nodes < number upstream nodes

Am I right?

[timlinux]

Hi

Sent from my mobile phone On 16 May 2014 9:10 AM, "Ismail Sunni" notifications@github.com wrote:

Another notes:

There is one other thing to consider - I believe a confluence can be valid in in streams > outstreams and a tributary can be valid if outstreams instreams. So for example a node with 3 upstream and 2 downstream would be considered a confluence. And a node with 2 upstream and 3 downstream would be considered a tributary.

So, I can conclude that:

1. Unclear bifurcation has the same number of upstream nodes and downstream nodes and both of them are more than one. So 1 < number of upstream nodes = number downstream nodes
2. Branch 1 <= number of upstream nodes < number downstream nodes
3. Confluence 1 <= number of downstream nodes < number upstream nodes

Am I right?

Yes with addition that branch has at least 1 upstream and 2 downstream. Confluence has at least 2 upstream and 1 downstream.

Thanks

Tim

— Reply to this email directly or view it on GitHub.