Implement klargestconncomps

[wkearn]

This is a StreamObject method that returns a new StreamObject, with only the edges corresponding to the k largest connected components of the stream network. The MATLAB implementation uses a built-in MATLAB linear algebra function dmperm. This operation might be worth implementing in libtopotoolbox.

This is used in the Getting Started guide section "Derive, modify and plot the stream network."

[wschwanghart]

There are probably easier ways to implement this function and avoid dmperm. Probably, it is more straightforward to (1) identify the outlets, (2) label them, (3) traverse the network in upstream direction and label other nodes, (4) create and sort a histogram of the label frequencies. and (5) extract the nodes. dmperm requires that the stream network is stored in a sparse adjacency matrix and is usually used to precondition matrices.

[wkearn]

(1), (2), and (3) are a connected components labeling algorithm and very similar to what is done in drainagebasins but using the stream network rather than the full flow network. With some refactoring we may be able to repurpose the drainagebasins traversal in libtopotoolbox (TopoToolbox/libtopotoolbox#121) to do that.

A histogram could be constructed during the labeling traversal (faster but requires modification of the traversal code), or could be done afterwards using numpy functions. Extracting nodes with a given label should probably be done in Python, because it requires dynamic memory allocation.