=========================================================================== Tutorial 4: Simple surface metrics (slope, curvature, aspect, etc) =========================================================================== By now you should have compiled the program ``LSDTT_analysis_from_paramfile.out``. If you haven't done this, go to the previous tutorial :ref:`get-and-compile-source`. Preliminary steps ===================================================== To run these analyses, you need to to da few preliminary steps that are described in previous tutorials. #. You need to get and compile the source code; see here: :ref:`get-and-compile-source`. #. You should make a folder for your data; see here: :ref:`make-folder`. #. If you don't have data, get the example data; see here: :ref:`get-example-data`. #. Move the parameter file to the data folder; see here: :ref:`param-to-data-folder`. #. Rename your parameter file (so you don't confuse this with other analyses). You can do this using the ``cp`` command:: cp Example.LSDTT_driver A_sensible_name.LSDTT_driver Note: the extension to the parameter file (in this case ``.LSDTT_driver``) doesn't matter. You could call the file ``Wacky.Monkey_Gumballs`` if you wanted. It is the **format** of this file that is important, not the filename. #. Open two terminal windows (Instructions here: :ref:`getting-onto-servers`). Modifying the parameter file ===================================================== #. You should be starting with a parameter file in your data folder that has been copied from somewhere else. You will now need to modify this file. #. Open the file in your favourite text editor. If this is from a previous analysis, you might see something a bit like this:: # This is a driver file for LSDTopoTools # Any lines with the # symbol in the first row will be ignored # File information dem read extension: bil dem write extension: bil read path: /home/smudd/topographic_tools/topographic_data/NextMap/Scotland read fname: WhiteadderDEM # Parameters for various topographic analysis min_slope_for_fill: 0.0001 # pixel_threshold_for_channel_net: 200 # The different analyses to be run write fill: true write hillshade: true # write channel_net: true #. If a line has a ``#`` symbol, that line is a comment and the program ``LSDTT_analysis_from_paramfile.out`` will ignore it. #. First, we need to deal with the file format and location. The file information in this case is:: # File information dem read extension: bil dem write extension: bil read path: /home/smudd/topographic_tools/topographic_data/NextMap/Scotland read fname: WhiteadderDEM This will work for me, but you will have to change this line:: read path: /home/smudd/topographic_tools/topographic_data/NextMap/Scotland to your path:: read path: /home/s01429521/my/sensible/path/Scotland/ To figure out what the path is you can type ``pwd`` in the terminal window when you are in your data folder. If you are not using the example data, you will need to change the read fname to the name of your data. So for example, if you are starting with a DEM called ``Sierra.bil``, the read fname will be ``Sierra``. * The parameter names are **NOT** case sensitive: ``dem read extension`` is the same as ``DEM rEaD extenSION`` as far as the program is concerned. * The parameter values **ARE** case sensitive: ``bil`` is **NOT** the same as ``BIL``. * The program will only understand the parameter name if you get it exactly correct. So if you misspell or put an underscore where a space should be, the program will not be able to understand. So be careful when editing these files!! #. Now lets move on to parameter values. At the moment these are:: # Parameters for various topographic analysis min_slope_for_fill: 0.0001 # pixel_threshold_for_channel_net: 200 The first and third lines above are comments, and are ignored by the program. We don't actually need the ``min_slope_for_fill`` parameter for this run, but if you leave that it it won't affect the program. #. To get our simple surface metrics, we are going to use a polyfit function. This fits a polynomial to the topographic surface over a fixed window, and then calculates toppographic metrics of this polynomial rather than calculating metrics on the data itself. This technique is employed to smooth high frequency noise, such as that from pits and mounds caused by falling trees. For LiDAR data, we have found that you want a polyfit window that is around 7 metres in radius. This is based on work by `Roering et al., 2010 `_ and `Hurst et al., 2012 `_. For coarser data, you probably want to smooth over at least 1 pixel radius, so if you havbe a 10m DEM your window radius should be >10m. In this example we are using old NextMap data (it was processed around 2007). Sadly this data isn't so great: it is full of lumps. The data resolution is 5 metres, but we are going to use a polyfit radius of 15.1 metres to make sure we get three pixels on each side of the centre pixel. The keyword is ``polyfit_window_radius``, so in your parameter file you should have these lines:: # Parameters for various topographic analysis min_slope_for_fill: 0.0001 # pixel_threshold_for_channel_net: 200 polyfit_window_radius: 15.1 #. We also want to add some lines to the parameter file to designate a method for calculating slope. The default method is called `d8`. It takes the slope between a pixel and its steepest downslope neighbor. We don't want this, we want a polyfit slope. So add two lines That state you have a methods block, and that you want the polyfit slope method:: # Methods used in analyses slope_method: polyfit The first line above (``# Methods used in analyses``) is a comment so ignored by the program, but it is useful to add these comments to the parameter files so that other people can tell what you are doing. #. Now you should tell the program what rasters to write. In this case we want curvature, aspect, and slope, so this section of the parameter file should look like:: # The different analyses to be run write slope: true write curvature: true write aspect: true #. Okay, save your changes to the parameter file; we will now move on to performing the analyses. It shold look like this:: # This is a driver file for LSDTopoTools # Any lines with the # symbol in the first row will be ignored # File information dem read extension: bil dem write extension: bil read path: /home/smudd/topographic_tools/topographic_data/NextMap/Scotland read fname: WhiteadderDEM # Parameters for various topographic analysis min_slope_for_fill: 0.0001 # pixel_threshold_for_channel_net: 200 slope_method: polyfit polyfit_window_radius: 15.1 # The different analyses to be run write slope: true write aspect: true write curvature: true Running the analyses (in this case, writing fill and hillshade rasters) --------------------------------------------------------------------------- #. You will now need to run the program ``LSDTT_analysis_from_paramfile.out``. Some details about running this program are in the first tutorial (:ref:`runningrun-analysis`) in case you have forgotten. #. I renamed my parameter file ``Whiteadder_Surf.LSDTT_driver``, so to run the code you need to type the following into the command line:: ./LSDTT_analysis_from_paramfile.out /home/smudd/topographic_tools/topographic_data/NextMap/Scotland Whiteadder_Surf.LSDTT_driver #. The program will spit out text to screen as it works. Once it is finished, you can look at the data in your favourite GIS. You can check to see if all the files are there by going into your data folder and typing ``ls``. You should see something like:: smudd@burn Scotland $ ls Example.LSDTT_driver Whiteadder_fill.bil Whiteadder.LSDTT_driver Whiteadder_Surf_curvature.hdr WhiteadderDEM.bil Whiteadder_fill.hdr Whiteadder_Surf_aspect.bil Whiteadder_Surf.LSDTT_driver WhiteadderDEM.hdr Whiteadder_hs.bil Whiteadder_Surf_aspect.hdr Whiteadder_Surf_slope.bil WhiteadderDEM.tif Whiteadder_hs.hdr Whiteadder_Surf_curvature.bil Whiteadder_Surf_slope.hdr #. Something is actually a little funny here. Why are the ouput files all named ``Whiteadder_Surf...``? The default output file names are the name of the parameter file with the extension removed. If you want to change the output names you can either change the name of the parameter file, or, alternatively, you can include the write file name in the paramter file:: write fname: MyFileName #. Another thing to note: If you use `ArcMap` to calculate curvature, it will get the sign wrong! Ridgetops have negative curvature and valleys have positive curvature. This is reversed in `ArcMap`. Our software gives the correct curvature.