# Get started

#### 2023-03-23

## Design

All functions in `landscapemetrics` start with `lsm_` (for landscapemetrics). The second part of the name specifies the level (patch - `p`, class - `c` or landscape - `l`). The last part of the function name is the abbreviation of the corresponding metric (e.g. `enn`for the euclidean nearest-neighbor distance):

    # general structure
    lsm_"level"_"metric"

    # Patch level
    ## lsm_p_"metric"
    lsm_p_enn()

    # Class level
    ## lsm_c_"metric"
    lsm_c_enn()

    # Landscape level
    ## lsm_p_"metric"
    lsm_l_enn()

All functions return an identical structured tibble:

layer | level | class | id | metric | value
--- | --- | --- | --- | --- | ---
1 | patch | 1 | 1 | landscape metric | x
1 | class | 1 | NA | landscape metric | x
1 | landscape | NA | NA | landscape metric | x

## Checking your landscape

Before using `landscapemetrics` and calculating landscape metrics in general, it makes sense to check your landscape. If your landscape has some properties that restrict the calculation or interpretation of landscape metrics, that should be detected with `check_landscape`:

    # import raster
    # for local file: raster("pathtoyourraster/raster.asc")
    # ... or any other raster file type, geotiff, ...

    # Check your landscape
    check_landscape(landscapemetrics::landscape) # because CRS is unkown, not clear
    #> Warning: Caution: Coordinate reference system not metric - Units of results
    #> based on cellsizes and/or distances may be incorrect.
    #>   layer crs units   class n_classes OK
    #> 1     1  NA    NA integer         3  ?⃝

    check_landscape(landscapemetrics::podlasie_ccilc) # wrong units
    #> Warning: Caution: Coordinate reference system not metric - Units of results
    #> based on cellsizes and/or distances may be incorrect.
    #>   layer        crs   units   class n_classes OK
    #> 1     1 geographic degrees integer        14  ✖

    check_landscape(landscapemetrics::augusta_nlcd) # everything is ok
    #>   layer       crs units   class n_classes OK
    #> 1     1 projected     m integer        15  ✔

The requirements to calculate meaningful landscape metrics are:

1. The distance units of your projection are meter, as the package converts units internally and returns results in either meters, square meters or hectares. For more information see the help file of each function.

2. Your raster encodes landscape classes as integers (1, 2, 3, 4, …, n).

3. Landscape metrics describe categorical landscapes, that means that your landscape needs to be classified (we throw a warning if you have more than 30 classes to make sure you work with a classified landscape).

## Using `landscapemetrics`

If you are sure that your landscape is suitable for the calculation of landscape metrics, `landscapemetrics` makes this quite easy:

    # import raster
    # for local file: raster("pathtoyourraster/raster.asc")
    # ... or any other raster file type, geotiff, ...

    # Calculate e.g. perimeter of all patches
    lsm_p_perim(landscape)
    #> # A tibble: 27 × 6
    #>    layer level class    id metric value
    #>    <int> <chr> <int> <int> <chr>  <dbl>
    #>  1     1 patch     1     1 perim      4
    #>  2     1 patch     1     2 perim     12
    #>  3     1 patch     1     3 perim    130
    #>  4     1 patch     1     4 perim      4
    #>  5     1 patch     1     5 perim      4
    #>  6     1 patch     1     6 perim     20
    #>  7     1 patch     1     7 perim      8
    #>  8     1 patch     1     8 perim     10
    #>  9     1 patch     1     9 perim      4
    #> 10     1 patch     2    10 perim     38
    #> # … with 17 more rows

### Using `landscapemetrics` in a tidy workflow

Every function in landscapemetrics accept data as its first argument, which makes piping a natural workflow. A possible use case is that you would load your spatial data, calculate some landscape metrics and then use the resulting tibble in further analyses.

    # all patch IDs of class 2 with an ENN > 2.5
    subsample_patches <- landscape %>%
        lsm_p_enn() %>%
        dplyr::filter(class == 2 & value > 2.5) %>%
        dplyr::pull(id)

    # show results
    subsample_patches
    #>  [1] 10 11 12 14 16 17 18 19 20 22 23

### Use multiple metric functions

To list all available metrics, just use the `list_lsm()` function. Here, you can specify e.g. a level or type of metrics.

    # list all available metrics
    list_lsm()
    #> # A tibble: 133 × 5
    #>    metric name                                type                 level funct…¹
    #>    <chr>  <chr>                               <chr>                <chr> <chr>
    #>  1 area   patch area                          area and edge metric patch lsm_p_…
    #>  2 cai    core area index                     core area metric     patch lsm_p_…
    #>  3 circle related circumscribing circle       shape metric         patch lsm_p_…
    #>  4 contig contiguity index                    shape metric         patch lsm_p_…
    #>  5 core   core area                           core area metric     patch lsm_p_…
    #>  6 enn    euclidean nearest neighbor distance aggregation metric   patch lsm_p_…
    #>  7 frac   fractal dimension index             shape metric         patch lsm_p_…
    #>  8 gyrate radius of gyration                  area and edge metric patch lsm_p_…
    #>  9 ncore  number of core areas                core area metric     patch lsm_p_…
    #> 10 para   perimeter-area ratio                shape metric         patch lsm_p_…
    #> # … with 123 more rows, and abbreviated variable name ¹​function_name

    # list only aggregation metrics at landscape level and just return function name
    list_lsm(level = "landscape",
             type = "aggregation metric",
             simplify = TRUE)
    #>  [1] "lsm_l_ai"       "lsm_l_cohesion" "lsm_l_contag"   "lsm_l_division"
    #>  [5] "lsm_l_enn_cv"   "lsm_l_enn_mn"   "lsm_l_enn_sd"   "lsm_l_iji"
    #>  [9] "lsm_l_lsi"      "lsm_l_mesh"     "lsm_l_np"       "lsm_l_pd"
    #> [13] "lsm_l_pladj"    "lsm_l_split"

    # you can also combine arguments and only return the function names
    list_lsm(level = c("patch", "landscape"),
             type = "core area metric",
             simplify = TRUE)
    #>  [1] "lsm_p_cai"      "lsm_p_core"     "lsm_p_ncore"    "lsm_l_cai_cv"
    #>  [5] "lsm_l_cai_mn"   "lsm_l_cai_sd"   "lsm_l_core_cv"  "lsm_l_core_mn"
    #>  [9] "lsm_l_core_sd"  "lsm_l_dcad"     "lsm_l_dcore_cv" "lsm_l_dcore_mn"
    #> [13] "lsm_l_dcore_sd" "lsm_l_ndca"     "lsm_l_tca"

As the result of every function always returns a `tibble`, combining the metrics that were selected for your research question is straightforward:

    # bind results from different metric functions
    patch_metrics <- dplyr::bind_rows(
      lsm_p_cai(landscape),
      lsm_p_circle(landscape),
      lsm_p_enn(landscape)
    )

    # look at the results
    patch_metrics
    #> # A tibble: 81 × 6
    #>    layer level class    id metric value
    #>    <int> <chr> <int> <int> <chr>  <dbl>
    #>  1     1 patch     1     1 cai      0
    #>  2     1 patch     1     2 cai      0
    #>  3     1 patch     1     3 cai     48.0
    #>  4     1 patch     1     4 cai      0
    #>  5     1 patch     1     5 cai      0
    #>  6     1 patch     1     6 cai     14.3
    #>  7     1 patch     1     7 cai      0
    #>  8     1 patch     1     8 cai      0
    #>  9     1 patch     1     9 cai      0
    #> 10     1 patch     2    10 cai     31.4
    #> # … with 71 more rows

All metrics are abbreviated in the result `tibble`. Therefore, we provide a `tibble` containing the full metric names, as well as the class of each metric (`lsm_abbreviations_names`). Using e.g. the `left_join()` function of the `dplyr` package one could join a result `tibble` and the abbrevations `tibble`.

    # bind results from different metric functions
    patch_metrics <- dplyr::bind_rows(
      lsm_p_cai(landscape),
      lsm_p_circle(landscape),
      lsm_p_enn(landscape)
      )
    # look at the results
    patch_metrics_full_names <- dplyr::left_join(x = patch_metrics,
                                                 y = lsm_abbreviations_names,
                                                 by = "metric")
    patch_metrics_full_names
    #> # A tibble: 81 × 10
    #>    layer level.x class    id metric value name            type   level.y funct…¹
    #>    <int> <chr>   <int> <int> <chr>  <dbl> <chr>           <chr>  <chr>   <chr>
    #>  1     1 patch       1     1 cai      0   core area index core … patch   lsm_p_…
    #>  2     1 patch       1     2 cai      0   core area index core … patch   lsm_p_…
    #>  3     1 patch       1     3 cai     48.0 core area index core … patch   lsm_p_…
    #>  4     1 patch       1     4 cai      0   core area index core … patch   lsm_p_…
    #>  5     1 patch       1     5 cai      0   core area index core … patch   lsm_p_…
    #>  6     1 patch       1     6 cai     14.3 core area index core … patch   lsm_p_…
    #>  7     1 patch       1     7 cai      0   core area index core … patch   lsm_p_…
    #>  8     1 patch       1     8 cai      0   core area index core … patch   lsm_p_…
    #>  9     1 patch       1     9 cai      0   core area index core … patch   lsm_p_…
    #> 10     1 patch       2    10 cai     31.4 core area index core … patch   lsm_p_…
    #> # … with 71 more rows, and abbreviated variable name ¹​function_name

Additionally, we provide a wrapper where the desired metrics can be specified as a vector of strings. Because all metrics regardless of the level return an identical `tibble`, different levels can be mixed. It is also possible to calculate all available metrics at a certain level using e.g. `level = "patch"`. Additionally, similar to `list_lsm()` you can also specify e.g. a certain group of metrics. Of course, you can also include the full names and information of all metrics using `full_name = TRUE`.

    # calculate certain metrics
    calculate_lsm(landscape,
                  what = c("lsm_c_pland", "lsm_l_ta", "lsm_l_te"))
    #> Warning: Please use 'check_landscape()' to ensure the input data is valid.
    #> # A tibble: 5 × 6
    #>   layer level     class    id metric  value
    #>   <int> <chr>     <int> <int> <chr>   <dbl>
    #> 1     1 class         1    NA pland   19.9
    #> 2     1 class         2    NA pland   26.9
    #> 3     1 class         3    NA pland   53.2
    #> 4     1 landscape    NA    NA ta       0.09
    #> 5     1 landscape    NA    NA te     364

    # calculate all aggregation metrics on patch and landscape level
    calculate_lsm(landscape,
                  type = "aggregation metric",
                  level = c("patch", "landscape"))
    #> Warning: Please use 'check_landscape()' to ensure the input data is valid.
    #> # A tibble: 41 × 6
    #>    layer level     class    id metric     value
    #>    <int> <chr>     <int> <int> <chr>      <dbl>
    #>  1     1 landscape    NA    NA ai       81.1
    #>  2     1 landscape    NA    NA cohesion 95.4
    #>  3     1 landscape    NA    NA contag   25.2
    #>  4     1 landscape    NA    NA division  0.696
    #>  5     1 landscape    NA    NA enn_cv   39.8
    #>  6     1 landscape    NA    NA enn_mn    3.18
    #>  7     1 landscape    NA    NA enn_sd    1.27
    #>  8     1 landscape    NA    NA iji      87.8
    #>  9     1 landscape    NA    NA lsi       4.03
    #> 10     1 landscape    NA    NA mesh      0.0273
    #> # … with 31 more rows

    # show full information of all metrics
    calculate_lsm(landscape,
                  what = c("lsm_c_pland", "lsm_l_ta", "lsm_l_te"),
                  full_name = TRUE)
    #> Warning: Please use 'check_landscape()' to ensure the input data is valid.
    #> # A tibble: 5 × 9
    #>   layer level     class    id metric  value name                   type  funct…¹
    #>   <int> <chr>     <int> <int> <chr>   <dbl> <chr>                  <chr> <chr>
    #> 1     1 class         1    NA pland   19.9  percentage of landsca… area… lsm_c_…
    #> 2     1 class         2    NA pland   26.9  percentage of landsca… area… lsm_c_…
    #> 3     1 class         3    NA pland   53.2  percentage of landsca… area… lsm_c_…
    #> 4     1 landscape    NA    NA ta       0.09 total area             area… lsm_l_…
    #> 5     1 landscape    NA    NA te     364    total edge             area… lsm_l_…
    #> # … with abbreviated variable name ¹​function_name