Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
@amforte
amforte authored Jul 9, 2018
1 parent cd822fb commit 8fad562
Showing 1 changed file with 8 additions and 27 deletions.
35 changes: 8 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,31 +1,12 @@
## Topographic Analyis Kit for TopoToolbox ##
## A major rewrite of the code is (mostly) complete in preparation for release ##
These are a series of matlab functions written by Adam M. Forte [aforte8 'at' lsu.edu] that build upon the functionality of TopoToolbox [https://github.com/wschwanghart/topotoolbox]. Each function contains a header with basic functionality info along with expected inputs and possible outputs. There is now a detailed user guide included in the repository (TAKmanual_reduce.pdf).

These are a series of matlab functions written by Adam M. Forte [aforte8 'at' lsu.edu] that build upon the functionality of TopoToolbox [https://github.com/wschwanghart/topotoolbox]. Each function contains a header with basic functionality info along with expected inputs and possible outputs. This readme compiles some of that information and lays out possible workflows, see also 'Suggested_Workflows.pdf' for complete flowchart. Discussions of workflows and tools assume a basic familiarity with the TopoToolbox data classes and Matlab functions. At present there are two semi-permanent branches of the code, the 'master' which contains versions of the code that I'm (reasonably) sure are stable and work properly and the 'development' which are the bleeding edge versions that I'm tinkering with (or it may be exactly the same as the master). These may have new functionality, but they also may be broken, so use with caution.
# Release
v.1.0.0 has been released! The release includes all files in the repository along with a tarball bundling the example data sets referenced in the manual.

# 1. Getting Started
The first step in most processing workflows is going to the 'MakeStreams' function, which takes a georeferenced DEM file as either a GeoTiff or ascii and produces the basic TopoToolbox datasets (DEM as a GRIDobj, flow direction as FLOWobj, flow accumulation as GRIDobj, and stream network as STREAMobj). There are various options to modify the DEM based on user input. All other functions require at least some of the outputs from this function. There are several helper functions to hydrologically condition the DEM ('ConditionDEM'), remove flat areas ('RemoveFlats'), or determine a suitable threshold drainage area ('FitThreshold')
# Attribution
The manuscript associated with these tools is under review at ESurf, please cite as:
A.M. Forte, K.X. Whipple. Short communication: The Topographic Analysis Kit (TAK) for TopoToolbox. Earth Surface Dynamics, in review, doi: 10.5194/esurf-2018-57.


# 2. Ksn and Chi Maps (Batch Mode)
If you want to make maps of normalized channel steepness (ksn) or chi for all streams identified in 'MakeStreams', use the 'KsnChiBatch' function. This function can be used to produce streams colored by ksn or chi (sensu Willett al al, 2014, Science) or alternatively a continuous grid of chi or ksn. Note that for ksn, this function produce shapefiles suitable for use in ArcGIS, where as the chi options produce ascii files importable as rasters into ArcGIS. This is because of the way Matlab deals with shapefiles, so to produce a shapefile of a chi map, import your ascii into ArcGIS and then use the raster to polyline tool. Grid options are output as ascii grids.

# 3. Interactive Stream Fitting and Ksn Maps
The function 'KsnProfiler' is designed to mimic Profiler_51 (Wobus et al, 2006) but without any required interaction with ArcGIS and lots of added features. The user selects channel heads on a map and after the selection of each channel head is able to pick segments of the stream. There are a variety of alternative methods to select streams (e.g. shapefile of channel heads, x-y locations of channel heads, iterate through all streams in a provided network, etc). The user can choose to either choose segments on the basis of chi-z plots, longitudinal stream profiles, or slope-area. There are options to determine suitable threshold area by individual stream segments, remove incomplete portions of stream networks, choose whether to avoid fitting the same portion of a trunk stream multiple times (i.e. any overlapping portion of a stream network that has already been fit is excluded from the rest of the analysis), etc. The code will output a series of arrays containing the channel information and will also export a shapefile containing the relevant streams and data. There is a separate function ('ClassifyKnicks') to classify the knickpoints/breakpoints defined during stream fitting.

# 4. Watershed Statistics and Clipping
One of the powerful aspects of TopoToolbox is to automate otherwise tedious processes (i.e. things that are annoying to do in Arc). One of those groups of tasks is to select a series of watersheds, clip them out, and calculate statistics. The 'ProcessRiverBasins' function is designed to do just this. To use this tool, you will need to have run 'MakeStreams' but also have a list of basin mouths (i.e. pour points) for your basins of interest (x-y coordinates, shapefile of river mouths). It is strongly recommended that you use the output shapefile of the stream network from 'MakeStreams' to pick basin mouths in Arc. DO NOT use a shapefile made from the hydrologic processing in Arc because the flow routing between Arc and TopoToolbox is slightly different, thus coordinates will not necessarily be the same. Once you have your matrix of river mouths, the 'ProcessRiverBasins' function will iteratively go through and clip out the DEM above this pour point and recalculate the stream network and produce various maps (e.g. chi map, ksn, etc) along with basin averaged statistics (e.g. ksn, gradient, etc). There are options to include additional GRIDobjs and by using the 'CatPoly2GRIDobj' function, also add categorical polygon data (e.g. a geologic map).

A companion function 'SubDivideBigBasins' is designed to be run after successfully running 'ProcessRiverBasins'. This function will find any resulting basin from the first function with a drainage area over a user defined threshold (e.g. 100 km^2) and subdivide it down to smaller basins. There are a variety of methods for subdividing. Outputs from both 'ProcessRiverBasins' and 'SubDivideBigBasins' are written as individual mat files for each watershed, identified by the river number within the original pour points matrix. The code can be run with an option to also generate shapefiles and grids for each subdivided basins that can be viewed in Arc.

# 5. Further Processing of Outputs from Watershed Clipping
'Basin2Shape' and 'Basin2Raster' allows the production of composite polygon shapefiles and ascii grids, respectively, containing various user defined statistics calculated during ProcessRiverBasins and SubDivideBigBasins. 'FindBasinKnicks' an interactive tool to choose knickpoint locations within clipped basins. 'PlotIndividualBasins' =will iterate through all results from 'ProcessRiverBasins' and 'SubDivideBigBasins' and plot a three panel figure with the longitudinal profile, chi-elevation, and slope-area plots saving figure will be saved as a separate pdf. 'CompileBasinStats' will compile statistics from the 'ProcessRiverBasins' and 'SubDivideBigBasins' but will also calculate additional statistics (e.g. filtered statistics based on categorical data originally provided to 'ProcessRiverBasins'). The output of 'CompileBasinStats' can be used to generate a series of plots summarizing the statistics of all clipped based with 'BasinStatsPlots'. The table output of 'CompileBasinStats' can also be used in conjuction with 'MakeCombinedSwath' (see 7. Swath Functions).

# 6. Interactive Selection
Several functions are designed to allow interactive selection of river profiles or basins. 'BasinPicker' allows the user to select an arbitrarily large number of basins. This function is designed to aid a user in selecting watersheds that meet certain criteria, e.g. if you are looking for basins that are a certain size and are well adjusted for sampling for cosmo. For each basin selected, the function will dislplay a chi-z relationship along with the stream profile and allow you to either accept (i.e. save) or reject (i.e. don't save) the basin you picked and will save the river mouth locations (suitable for providing to 'ProcessRiverBasins' to clip out and calculate statistics for all basins). 'SegmentPicker' allows the user to choose multiple individual drainage networks (above selected pour points) or multiple individual channels (down from selected channel heads). 'SegmentPlotter' will plot the specified results of using the 'SegmentPicker' function. 'SegmentProjector' is for projecting segments of streams (e.g. estimating the amount of surface uplift by projecting the upper portion of a low steepness stream).

# 7. Swath Profiles and Projected Data
There are two functions that take advantage of the utility of the SWATHobj class in TopoToolbox. 'MakeTopoSwath' is a simple wrapper around SWATHobj that provides some alternative methods of plotting swath profiles compared to SWATHobj and more direct control on vertical exaggeration. 'MakeCombinedSwath' is for producing topographic swaths along with a variety of data projected onto the swath line. There are a variety of different data types that can be projected, generic x-y-z data, generic x-y-z data with an additional value to color points by, earthquake data, stream profiles (provided as STREAmobj), channel steepness data (from old profiler51 chandata files, or outputs of 'KsnChiBatch' or 'KsnProfiler'), basin averaged statistics from 'CompileBasinStats', or knickpoint distributions from 'FindBasinKnicks'.

# 8. Error Reporting, Feature Request, and Attribution
If you encounter a bug or have a suggestion for a new feature / improvement the preferred method of communication is to use the 'Issues' function built into GitHub. You can also email Adam [aforte8 'at' lsu.edu] if you're uncomfortable with GitHub. If you encounter an issue that you know how to fix and are comfortable with how git works, please feel free to fork the code and submit a pull request with fixes and improvements, collaboration is welcome! I am actively working on a manuscript submission that will document these codes and will be the appropriate citation for using these codes. In the mean time, please let Adam know if you're using them and check back often for an update on a citation!
# Error Reporting and Feature Request
If you encounter a bug or have a suggestion for a new feature / improvement the preferred method of communication is to use the 'Issues' function built into GitHub. You can also email Adam [aforte8 'at' lsu.edu]. If you encounter an issue that you know how to fix and are comfortable with how git works, please feel free to fork the code and submit a pull request with fixes and improvements, collaboration is welcome!

0 comments on commit 8fad562

Please sign in to comment.