Additions to the chi analysis documentation and various typo fixes

Author: simon-m-mudd

Book_script.sh

@@ -5,7 +5,7 @@
 # You need to do this offline since bundler doesn't work on UEdin servers!
 
 # sync the files on the web server
-rsync -a ./images/ /web/smudd/public_html/LSDTT_book/Images
+rsync -a ./images/ /web/smudd/public_html/LSDTT_book/images
 rsync -a ./LSDTT_docs.html /web/smudd/public_html/LSDTT_book/LSDTT_docs.html
 rsync -a ./LSDTT_docs.pdf /web/smudd/public_html/LSDTT_book/LSDTT_docs.pdf
 

book/03-Preliminary-Steps/sections/GDAL.asc

@@ -69,7 +69,7 @@ The preferred coordinate system is WGS84 UTM coordinates. For convert to
 this coordinate system you use `gdalwarp`. The coordinate system of the
 source raster can be detected by gdal, so you use the flag `-t_srs` to
 assign the target coordinate system. Details about the target coordinate
-system are in quotes, you want::
+system are in quotes, you want:
 
 [source,consol]
 -----------------------------------
@@ -93,15 +93,15 @@ Put this together with a source and target filename:
 $ gdalwarp -t_srs '+proj=utm +zone=XX +datum=WGS84' source.ext target.ext
 -------------------------------------------------------------------------
 
-so one example would be::
+so one example would be:
 
 [source,consol]
 -------------------------------------------------------------------------------------------------------
 $ gdalwarp -t_srs '+proj=utm +zone=44 +datum=WGS84' diff0715_0612_clip.tif diff0715_0612_clip_UTM44.tif
 -------------------------------------------------------------------------------------------------------
 
 note that if you are using UTM and you are in the southern hemisphere,
-you should use the `+south` flag::
+you should use the `+south` flag:
 
 [source,consol]
 ------------------------------------------------------------------------------------------------------------------
@@ -159,7 +159,7 @@ contributing pixels. (GDAL >= 1.10.0)
 ** `mode`: mode resampling, selects the value which appears most often
 of all the sampled points. (GDAL >= 1.10.0)
 +
-So for example you could do a cubic resampling with::
+So for example you could do a cubic resampling with:
 +
 [source,consol]
 ----
@@ -170,7 +170,7 @@ diff0715_0612_clip.tif diff0715_0612_clip_UTM44_rs4.tif
 * `-te` `<x_min> <y_min> <x_max> <y_max>`: this clips the raster. You
 can see more about this below in :ref:`Clip-using-gdal`.
 * **UTM South**: If you are looking at maps in the southern hemisphere,
-you need to use the `+south` flag::
+you need to use the `+south` flag:
 +
 [source,consol]
 ----
@@ -204,14 +204,12 @@ $ gdal_translate -of ENVI diff0715_0612_clip_UTM44.tif diff0715_0612_clip_UTM44.
 Where the first `filename.ext` is the source file and the second is the
 output file.
 
-.. _Clip-using-gdal:
-
 [[potential-filename-errors]]
 ===== Potential filename errors
 
 It appears that GDAL considers filenames to be case-insensitive, which
 can cause data management problems in some cases. The following files
-are both considered the same::
+are both considered the same:
 
 [source,consol]
 -------------------------------

book/03-Preliminary-Steps/sections/data-sources.asc

@@ -40,7 +40,7 @@ and because it retains georeferencing information.
 .Why don't we use GeoTiff?
 ****
 https://trac.osgeo.org/geotiff/[GeoTIFF] is a widely used raster format that has the advantage of containing georeferencing and the raster data in a single file. 
-The disadvantage is that for pass:[c++] code you need to have two libraries (`libtiff` and `libgeotiff`) installed before you can read GeoTIFF files. 
+The disadvantage is that for pass:[C++] code you need to have two libraries (`libtiff` and `libgeotiff`) installed before you can read GeoTIFF files. 
 Because there are many open source, easily installed tools for converting GeoTIFF files 
 (for example, the http://www.gdal.org/gdal_utilities.html[GDAL utilities] and the https://pypi.python.org/pypi/GDAL/[python GDAL bindings])
 we have opted for portability and not included the GeoTIFF libraries in our software. If you have GeoTIFF files, you
@@ -109,16 +109,16 @@ There are several global topographic datasets. The oldest of these is https://lt
 which was completed in 1996 and contains ~1 km resolution global data. 
 This was followed by the https://en.wikipedia.org/wiki/Shuttle_Radar_Topography_Mission[Shuttle Radar Topography Mission (SRTM)]
 that produced a 90 meter resolution DEM in 2003; followed by the 
-https://asterweb.jpl.nasa.gov/gdem.asp[Advanced Spaceborne Thermal Emission and Rerflection Radiometer (ASTER)]
+https://asterweb.jpl.nasa.gov/gdem.asp[Advanced Spaceborne Thermal Emission and Reflection Radiometer (ASTER)]
 30 meter resolution global DEM in 2009. In 2014 
 http://www.cgiar-csi.org/data/srtm-90m-digital-elevation-database-v4-1[SRTM released a global 30 meter dataset]. 
 2015 has seen the release of the http://www.geo-airbusds.com/worlddem/[WorldDEM], a 12 meter resolution topographic dataset. 
 
 GTOPO30, SRTM and ASTER data are all freely available for download. The WorldDEM is a commercial product.
-If you are looking for a global dataset at reasonable resolution that is not commercial, you will most likeley choose between ASTER and SRTM. 
+If you are looking for a global dataset at reasonable resolution that is not commercial, you will most likely choose between ASTER and SRTM. 
 You can download ASTER and SRTM data at the same site and make your own comparisons, 
 but ASTER has widely publicised http://www.digital-geography.com/dem-comparison-srtm-3-vs-aster-gdem-v2/#.ViS2wX6rRaQ[data quality issues]
-so we reccomend the SRTM 30 meter data. 
+so we recommend the SRTM 30 meter data. 
 ****
 
 

book/Chi-Analysis/images/Thumbs.db

@@ -9,3 +9,8 @@ If you are familiar with chi analysis, you can skip ahead to the section <<Get a
 This section covers the background to the method, and why it is useful.
 
 ==== Topographic expression of climate, tectonics, and lithology
+
+Sorry the sicetion is under construction! But if you want to read more about chi analysis, have a look at these papers:
+http://web.mit.edu/perron/www/files/PerronRoyden13.pdf[Perron and Royden, 2013]; 
+http://web.mit.edu/perron/www/files/RoydenPerron13.pdf[Royden and Perron, 2013]; 
+http://onlinelibrary.wiley.com/doi/10.1002/2013JF002981/abstract[Mudd et al., 2014].

book/Chi-Analysis/sections/background.asc

@@ -54,4 +54,45 @@ $ cd driver_functions_MuddChi2014
 There are a number of makefiles (thse with extension `.make` in this folder).
 These do a number of different things that will be explained later in this chapter.
 We will compile them as we go through the various different types of chi analysis.
+
+==== Get some example data
+
+We are going to use example data from the Mandakini River in Northern India.
+This river was the focus of a study by Rahul Devrani and others, you can find it here:
+http://onlinelibrary.wiley.com/doi/10.1002/2015GL063784/full (the paper is open access). 
+
+Again, we want to make sure our data is arranged somewhere sensible. 
+Make a directory for datasets and perhaps a folder specific to India. 
+Again, you don't need to follow the same naming conventions as in these examples,
+but you will have to remember the directory names!
+
+I would open a second terminal window (one should already be open in the *driver_functions_MuddChi2014* folder)
+and navigate to the data folder:
+
+[source,console]
+----
+$ cd /home/LSDTT_Data/India/
+----
+
+The SRTM data from the catchment is stored on the data repository at GitHub:
+https://github.com/LSDtopotools/ExampleTopoDatasets.
+
+You probably don't want to clone this repository since it contains a lot of DEMs, 
+so why don't you just download the relevant files directly:
+
+[source,console]
+----
+$ wget https://github.com/LSDtopotools/ExampleTopoDatasets/raw/master/Mandakini.bil
+$ wget https://github.com/LSDtopotools/ExampleTopoDatasets/raw/master/Mandakini.hdr
+----
+
+We are also going to use a parameter file, which can be grabbed from Github:
+
+[source,console]
+----
+$ wget https://github.com/LSDtopotools/ExampleTopoDatasets/raw/master/example_parameter_files/Mandakini.driver
+----
+
+Okay, you are now ready to move on to the examples. 
+
 

book/Chi-Analysis/sections/get-the-code.asc

@@ -38,29 +38,26 @@ the toolkit takes the raw DEM and prints several derived datasets from it.
 The main dataset used for the next step is the junction index dataset.
 The second step involves selecting a junction from which the chi analysis proceeds.
 
-===== Writing junctions
 
+===== Compiling the source code for junctions and channels
 
-. First, create a folder for your DEM.
-+
-For this example I am working in the Mandakini river, a tributary of the Ganga in the Indian Himalaya.
-Make sure both the `.flt` and the `.hdr` file are in this folder.
-Then you need to create a file that tells the analysis the name of the DEM and a few parameters.
+. This example will use the files that we downloaded in the previous section. 
+If you have your own files, you will need to substitites the correct file and directory names. 
 +
-You can name this file anything you like but I have called mine ``chi_parameters.driver``:
+. Make sure the necessary files are in your directory:
 +
 [source,console]
 ----
 $ pwd
-/home/smudd/topographic_tools/test_suites/Mandakini
+/home/LSDTT_Data/India/
 
 $ ls
-chi_parameters.driver  mandakini.flt  mandakini.hdr
+Mandakini.driver  Mandakini.bil  Mandakini.hdr
 ----
 +
 . The driver file must contain three lines.
 The first line is the name of the DEM without the extension.
-In this example the name is `mandakini`. The next line is a minimum slope for the fill function.
+In this example the name is `Mandakini`. The next line is a minimum slope for the fill function.
 The default is 0.0001.
 The third line is the threshold number of pixels that contribute to another pixel before that pixel is considered a channel.
 You can play with these numbers a bit, in this example, I have set the threshold to 300
@@ -74,8 +71,59 @@ mandakini
 300
 ----
 +
-. Once you have done this, you need to run the driver program.
-The driver program is called `chi1_write_junctions.exe`.
+You can check this in Linux with the `less` command. Just type `less Mandakini.drver` to see the file and `q` to quit. 
++
+. Okay, if you have been following along, you should have two terminal windows open. One should be open in the folder containing your data, and the other should be open in the folder with the source code driver functions. 
++
+[cols="1,1", options="header"]
+.The two terminal windows
+|===
+|Data terminal window
+|Source code terminal window
+
+a|[source,paramfile]
+----
+$ pwd
+/home/LSDTT_data/India/
+$ ls
+Mandakini.driver  Mandakini.bil  Mandakini.hdr
+----
+
+a|
+[source,paramfile]
+----
+$ pwd
+/home/LSDTT_repositories/LSDTopoTools_ChiMudd2014/driver_functions_MuddChi2014/
+$ ls
+chi_get_profiles_driver.cpp
+chi_get_profiles.make
+chi_m_over_n_analysis_driver.cpp
+chi_m_over_n_analysis.make
+chi_step1_write_junctions_driver.cpp
+chi_step1_write_junctions.make
+chi_step2_write_channel_file_discharge.cpp
+chi_step2_write_channel_file_discharge.make
+chi_step2_write_channel_file_driver.cpp
+chi_step2_write_channel_file.make
+----
+
+|===
++
+. In the source code terminal window, you need to compile two programs (step1 and step2):
++
+[source,console]
+----
+$ make -f chi_step1_write_junctions.make
+<<Lots of warnings that you can ignore>>
+$ make -f chi_step2_write_channel_file.make
+----
++
+. This will make two programs, *chi1_write_junctions.exe* and *chi2_write_channel_file.exe*. 
+Once you have done this, you need to run the driver program.
+
+===== Writing junctions
+
+. For writing junctions, the driver program is called `chi1_write_junctions.exe`.
 It takes 2 arguments.
 The first is the path name into the folder where your data is stored, and the second is the name of the driver file.
 To run the program, just type the program name and then the path name and driver file name.
@@ -87,10 +135,10 @@ Here is a typical example:
 +
 [source,console]
 ----
-./chi1_write_junctions.exe /home/smudd/topographic_tools/test_suites/Mandakini/ chi_parameters.driver
+$ ./chi1_write_junctions.exe /home/LSDTT_data/India/ Mandakini.driver
 ----
 +
-IMPORTANT: To run the code you need to be in the folder containing the `.exe` file, **NOT** the folder with the data.
+IMPORTANT: To run the code you need to be in the source code folder containing the `.exe` file, **NOT** the folder with the data.
 +
 All the output from the software, however, will be printed to the data folder. *That is, the software and data are kept separately.*
 +
@@ -113,9 +161,13 @@ So your directory will be full of files like this:
 [source,console]
 ----
 $ ls
-chi_parameters.driver  mandakini.flt     mandakini_HS.hdr  mandakini_SO.flt
-mandakini_fill.flt     mandakini.hdr     mandakini_JI.flt  mandakini_SO.hdr
-mandakini_fill.hdr     mandakini_HS.flt  mandakini_JI.hdr
+Mandakini.hdr         Mandakini.driver
+Mandakini.bil         Mandakini_HS.bil  
+Mandakini_CP.bil      Mandakini_HS.hdr  
+Mandakini_CP.hdr      Mandakini_JI.bil  
+Mandakini_JI.hdr  
+Mandakini_fill.bil    Mandakini_SO.bil  
+Mandakini_fill.hdr    Mandakini_SO.hdr
 ----
 +
 . You will then need to load these files into ArcMap and look at them.
@@ -136,15 +188,17 @@ The stream order raster will display the channel network, with each channel havi
 In the image below, the channel network is in cool colours and the junctions are in warm colours.
 Each junction has a unique integer value, called the junction index.
 +
-.. image:: ./_images/Chi_profiles/Mandakini_stream_network.jpg
+.Stream network, with junctions in red and orange pixels
+image::images/Mandakini_stream_network.jpg[Stream network]
 +
 . Now, find the part of the map where you want to do the chi analysis.
 You need to choose the junction at the downstream end of the channels where you will do your analysis.
 Use the identify tool (it looks like an ```i``` in a blue circle on ArcMap)
 to get the number of the junction that you want to use as the lowest junction in the channel network.
 In the below image the arrow points to junction number 51.
 +
-       .. image:: ./_images/Chi_profiles/Mandakini_select_junction.jpg
+.Finding the junction number
+image::images/Mandakini_select_junction.jpg[Finding a junction]
 +
 . Each junction has one and only one receiver junction, whereas it can have multiple donor junctions.
 When you choose a junction, the extracted channel traces down to the node one before the receiver junction.
@@ -161,15 +215,15 @@ Before you run this program, you need to write a file that contains the paramete
 The code does not check this so you need to make sure on your own this is the case.
 
 . The next two rows of the driver file are the junction number from which you want to extract the network.
-and something that controls how the channel network is ```pruned```.
+and something that controls how the channel network is "pruned".
 This is the ratio in area between the main stem and a tributary that must be exceeded for a tributary to be included in the analysis.
 If this number is 1 you only get the main stem.
 The smaller the number the more tributaries you get. A reasonable number seems to be `~0.02`.
 Here is an example file:
 +
 [source,paramfile]
 ----
-mandakini
+Mandakini
 0.0001
 300
 51
@@ -182,7 +236,7 @@ it only looks at the first 5 lines of the driver function.
 +
 . From here you run the program `chi2_write_channel_file.exe`.
 You need to include the path name and the name of the chi parameter file.
-In Linux the program should be proceeded with `./`. Here is an example::
+In Linux the program should be proceeded with `./`. Here is an example:
 +
 [source,console]
 ----
@@ -200,17 +254,20 @@ drained by the extracted channel network.
 +
 ArcMap should be able to see the '.csv' file.
 +
-.. image:: ./_images/Chi_profiles/channel_csv.jpg
+.Adding a csv file in ArcMap
+image::images/channel_csv.jpg[Load a csv file]
 +
 If you load this layer and right click on it, you should be able to load the xy data
 +
-.. image:: ./_images/Chi_profiles/csv_show_xy.jpg
+.Showing x and y data in ArcMap
+image::images/csv_show_xy.jpg[Show xy data in ArcMap]
 +
 Loading the csv file will give you a shapefile with the channel nodes, and loading the `_basin_`
 file will give you the basin. Here is the basin and the channel for junction `51` of the
 Mandakini dataset
 +
-.. image:: ./_images/Chi_profiles/Mandakini_extracted_chan_and_basin.jpg
+.The extraced basin with its channels
+image::images/Mandakini_extracted_chan_and_basin.jpg[Channel and basin]
 +
 Note how the channel extends downstream from the selected junction. It stops one node before the
 next junction. This way you can get an entire tributary basin that stops one node short of its
@@ -219,10 +276,10 @@ confluence with the main stem channel.
 
 ===== Format of the .chan file
 
-The segment fitting algorithm (see part 2)  works on a ```channel``` file (we use the extension `.chan` to denote a channel file).
+The segment fitting algorithm (see part 2)  works on a "channel" file (we use the extension `.chan` to denote a channel file).
 The channel file starts with six lines of header information that is used to reference the channel to a DEM.
 f the channel is not generated from a DEM these six rows can contain placeholder values.
-The six rows are::
+The six rows are:
 
 [cols="1,3", options="header"]
 .File input and output options
@@ -281,9 +338,10 @@ Columns are separated by spaces so rows will have the format:
 Chan_number receiver_chan receiver_node node_index row col flow_dist elev drainage_area
 ----
 
-Here are the first few lines of the example file (`mandakini_ChanNet_51.chan`):
+Here are the first few lines of the example file (`Mandakini_ChanNet_51.chan`):
 
 [source,paramfile]
+----
 648
 587
 290249.625
@@ -299,7 +357,9 @@ Here are the first few lines of the example file (`mandakini_ChanNet_51.chan`):
 0 0 271 5799 76 323 70683.39844  4571 3936087.25
 0 0 271 5992 77 324 70557.79688  4565 3975527
 0 0 271 6190 78 325 70432.19531  4564 3983414.75
+----
 
-Now that you have the `.chan` file you are ready to move to part 2 of the chi analysis (:ref:`Chi-part-2`).
+Now that you have the `.chan` file you are ready to move to the next section of the chi analysis:
+<<Chi profile analysis, part 2: constraining m/n and transforming profiles>>.
 This may have seen like quite a few steps, but once you get familiar with the workflow the
 entire process should take no more than a few minutes.

book/Chi-Analysis/sections/getting-profiles.asc

@@ -1,4 +1,5 @@
 [preface]
+
 == Preface by Simon M. Mudd
 
 Welcome to the documentation of the https://lsdtopotools.github.io/[LSDTopoTools].