Functions

We often need to create a same code structure more than once or twice. If so it may be time to create our own function. For all practical purposes a function is just R-code wrapped into a specific name. Here we are actually not going to deal with some generic introduction into function but dive directly into a practidal example that looks like it is useful for fisheries data.

An example of a function working on coordinates

In fisheries science we often have coordinates indicating the location of a sampling site. Coordinates are quite often written as e.g. “122°47’42.02’’” or some variant thero. Here we have degrees-minutes-second format each ending “standard” but wonky characters. Now if we were e.g. create a plot of sampling location we would first need to convert this to a numerical value, here decimal degrees.

Let’s get some example data with coordinates:

library(tidyverse)
ex1 <- read_csv("https://heima.hafro.is/~einarhj/data/coordinates_example1.csv")
ex1

# A tibble: 20 × 3
     .id Lon            Lat          
   <dbl> <chr>          <chr>        
 1     1 122°47'48.90'' 39°04'37.61''
 2     2 122°47'53.47'' 39°04'39.34''
 3     3 122°47'41.11'' 39°04'33.85''
 4     4 122°47'44.33'' 39°04'37.10''
 5     5 122°47'41.11'' 39°04'36.73''
 6     6 122°47'43.18'' 39°04'40.40''
 7     7 122°47'41.11'' 39°04'42.40''
 8     8 122°47'46.24'' 39°04'37.10''
 9     9 122°47'43.18'' 39°04'38.08''
10    10 122°47'43.40'' 39°04'37.61''
11    11 122°47'36.34'' 39°04'36.29''
12    12 122°47'41.11'' 39°04'42.40''
13    13 122°47'41.11'' 39°04'35.32''
14    14 122°47'48.90'' 39°04'40.40''
15    15 122°47'44.33'' 39°04'37.10''
16    16 122°47'42.02'' 39°04'33.85''
17    17 122°47'36.34'' 39°04'34.40' 
18    18 122°47'41.11'' 39°04'36.73''
19    19 122°47'53.47'' 39°04'33.85''
20    20 122°47'43.40'' 39°04'36.73''

So here we have longitude and latitude in degrees-minutes-seconds and we want to convert it to decimal degrees. Given this data we can think that the code need to:

• Remove all the wonky bits.
• Then work on converting the minutes and second parts into decimal degrees.
• Then add these elements to the decimal decimal part to get the final decimal degrees.

An example of a code sequence that could do such a thing, here wrapped into a function could be something like this:

#' Convert degrees-minutes-seconds to decimal degrees
#' 
#' This function removes all characters except numerics (0, 1, 2, ... 9) and 
#' the "." and puts a single space instead, then separates out the degrees, 
#' minutes and seconds and then calculates the decimal degrees
#' 
dms2decimmals <- function(x) {
  tibble::tibble(x = x) |> 
    dplyr::mutate(x = stringr::str_replace_all(x, "[^0-9.-]", " "),
           x = stringr::str_squish(x)) |> 
    tidyr::separate(x, into = c("dd", "mm", "ss"), convert = TRUE, sep = " ") |> 
    dplyr::mutate(lon = dd + mm / 60 + ss / 3600) |> 
    dplyr::pull(lon)
}

Now you do not need to worry about the code inside the function-part, you only need to know what the function does.

Let’s give this function a try:

ex1 |> 
  mutate(lon = dms2decimmals(Lon),
         lat = dms2decimmals(Lat)) |> 
  knitr::kable()

.id	Lon	Lat	lon	lat
1	122°47’48.90’’	39°04’37.61’’	122.7969	39.07711
2	122°47’53.47’’	39°04’39.34’’	122.7982	39.07759
3	122°47’41.11’’	39°04’33.85’’	122.7948	39.07607
4	122°47’44.33’’	39°04’37.10’’	122.7956	39.07697
5	122°47’41.11’’	39°04’36.73’’	122.7948	39.07687
6	122°47’43.18’’	39°04’40.40’’	122.7953	39.07789
7	122°47’41.11’’	39°04’42.40’’	122.7948	39.07844
8	122°47’46.24’’	39°04’37.10’’	122.7962	39.07697
9	122°47’43.18’’	39°04’38.08’’	122.7953	39.07724
10	122°47’43.40’’	39°04’37.61’’	122.7954	39.07711
11	122°47’36.34’’	39°04’36.29’’	122.7934	39.07675
12	122°47’41.11’’	39°04’42.40’’	122.7948	39.07844
13	122°47’41.11’’	39°04’35.32’’	122.7948	39.07648
14	122°47’48.90’’	39°04’40.40’’	122.7969	39.07789
15	122°47’44.33’’	39°04’37.10’’	122.7956	39.07697
16	122°47’42.02’’	39°04’33.85’’	122.7950	39.07607
17	122°47’36.34’’	39°04’34.40’	122.7934	39.07622
18	122°47’41.11’’	39°04’36.73’’	122.7948	39.07687
19	122°47’53.47’’	39°04’33.85’’	122.7982	39.07607
20	122°47’43.40’’	39°04’36.73’’	122.7954	39.07687

Take note that we have used the same function both for the longitude and the latitude. Now we should of course check if the code does the right thing, like by taking few records and do the calculation “by hand”. But let’s for now trust the person that generated this function.

Now let’s get another example which has coordinates:

ex2 <- read_csv("https://heima.hafro.is/~einarhj/data/some_messy_map_coordinates.csv")
ex2

# A tibble: 8 × 4
  `Name of Island`  Latitude             Longitude           Comment            
  <chr>             <chr>                <chr>               <chr>              
1 Makusu Island     "N 00 ° 09' 01.0\""  "E 32 ° 38' 10.5\"" Entire Island with…
2 Sanga Island      "N 00 ° 04' 34.0\""  "E 32 ° 39' 23.5\"" Entire Island with…
3 Kawaga Lighthouse "N 00 ° 02' 35.0\""  "E 32 ° 46' 34.5\"" Entire Island with…
4 Tavu Island       "S00 ° 02' 19.8\""   "E 32 ° 41' 50.8\"" Entire Island with…
5 Kimmi Island      "S 00  ° 05' 08.7\"" "E 32 ° 38' 55.5\"" Lines to and from …
6 Kizima Island     "S 00  ° 01' 08.7\"" "E 32 ° 37' 54.3\"" Entire Island LPA  
7 Miru Island       "N 00 ° 01' 588.5\"" "E 32 ° 35' 12.0\"" Entire Island LPA  
8 Mukusu Island     "N 00 ° 09' 01.0\""  "E 32 ° 38' 10.5\"" Entire Island with…

Here we have a little bit of different construct than we saw in the first example, it does not look as orderly but now we also have things like “N” and “E”. Let’s see if our function above works:

ex2 |> 
  select(Longitude, Latitude) |> 
  mutate(lon = dms2decimmals(Longitude),
         lat = dms2decimmals(Latitude))

# A tibble: 8 × 4
  Longitude           Latitude               lon    lat
  <chr>               <chr>                <dbl>  <dbl>
1 "E 32 ° 38' 10.5\"" "N 00 ° 09' 01.0\""   32.6 0.150 
2 "E 32 ° 39' 23.5\"" "N 00 ° 04' 34.0\""   32.7 0.0761
3 "E 32 ° 46' 34.5\"" "N 00 ° 02' 35.0\""   32.8 0.0431
4 "E 32 ° 41' 50.8\"" "S00 ° 02' 19.8\""    32.7 0.0388
5 "E 32 ° 38' 55.5\"" "S 00  ° 05' 08.7\""  32.6 0.0857
6 "E 32 ° 37' 54.3\"" "S 00  ° 01' 08.7\""  32.6 0.0191
7 "E 32 ° 35' 12.0\"" "N 00 ° 01' 588.5\""  32.6 0.180 
8 "E 32 ° 38' 10.5\"" "N 00 ° 09' 01.0\""   32.6 0.150 

So we got some decimal numbers. But look carefully the lat and the lon data. What do you notice is wrong given the orignal data??

The problem here is that the function always gives us positive numbers. But in decimal degrees if the latitude is in the southern hemisphere that should give us a negative decimal degrees. Same would be if the longitude is west of the Greenwich line.

Let’s fix the function above to take that into account:

#' Convert degrees-minutes-seconds to decimal degrees
#' 
#' This function removes all characters except numerics (0, 1, 2, ... 9) and 
#' the "." and puts a single space instead, then separates out the degrees, 
#' minutes and seconds and then calculates the decimal degrees
#' 
dms2decimmals <- function(x) {
  
  # get only letters
  quarter <- x |> stringr::str_extract("[A-Z]")
  x <- 
    tibble::tibble(x = x) |> 
    dplyr::mutate(x = stringr::str_replace_all(x, "[^0-9.-]", " "),
           x = stringr::str_squish(x)) |> 
    tidyr::separate(x, into = c("dd", "mm", "ss"), convert = TRUE, sep = " ") |> 
    dplyr::mutate(lon = dd + mm / 60 + ss / 3600) |> 
    dplyr::pull(lon)
  case_when(quarter == "S" | quarter == "W" ~ -x,
            .default = x)
}

Now let’s test again:

ex2 |> 
  select(Longitude, Latitude) |> 
  mutate(lon = dms2decimmals(Longitude),
         lat = dms2decimmals(Latitude)) |> 
  knitr::kable()

Longitude	Latitude	lon	lat
E 32 ° 38’ 10.5”	N 00 ° 09’ 01.0”	32.63625	0.1502778
E 32 ° 39’ 23.5”	N 00 ° 04’ 34.0”	32.65653	0.0761111
E 32 ° 46’ 34.5”	N 00 ° 02’ 35.0”	32.77625	0.0430556
E 32 ° 41’ 50.8”	S00 ° 02’ 19.8”	32.69744	-0.0388333
E 32 ° 38’ 55.5”	S 00 ° 05’ 08.7”	32.64875	-0.0857500
E 32 ° 37’ 54.3”	S 00 ° 01’ 08.7”	32.63175	-0.0190833
E 32 ° 35’ 12.0”	N 00 ° 01’ 588.5”	32.58667	0.1801389
E 32 ° 38’ 10.5”	N 00 ° 09’ 01.0”	32.63625	0.1502778

Now since we changed the function we may want to test if it still works on first example:

ex1 |> 
  mutate(lon = dms2decimmals(Lon),
         lat = dms2decimmals(Lat))

# A tibble: 20 × 5
     .id Lon            Lat             lon   lat
   <dbl> <chr>          <chr>         <dbl> <dbl>
 1     1 122°47'48.90'' 39°04'37.61''  123.  39.1
 2     2 122°47'53.47'' 39°04'39.34''  123.  39.1
 3     3 122°47'41.11'' 39°04'33.85''  123.  39.1
 4     4 122°47'44.33'' 39°04'37.10''  123.  39.1
 5     5 122°47'41.11'' 39°04'36.73''  123.  39.1
 6     6 122°47'43.18'' 39°04'40.40''  123.  39.1
 7     7 122°47'41.11'' 39°04'42.40''  123.  39.1
 8     8 122°47'46.24'' 39°04'37.10''  123.  39.1
 9     9 122°47'43.18'' 39°04'38.08''  123.  39.1
10    10 122°47'43.40'' 39°04'37.61''  123.  39.1
11    11 122°47'36.34'' 39°04'36.29''  123.  39.1
12    12 122°47'41.11'' 39°04'42.40''  123.  39.1
13    13 122°47'41.11'' 39°04'35.32''  123.  39.1
14    14 122°47'48.90'' 39°04'40.40''  123.  39.1
15    15 122°47'44.33'' 39°04'37.10''  123.  39.1
16    16 122°47'42.02'' 39°04'33.85''  123.  39.1
17    17 122°47'36.34'' 39°04'34.40'   123.  39.1
18    18 122°47'41.11'' 39°04'36.73''  123.  39.1
19    19 122°47'53.47'' 39°04'33.85''  123.  39.1
20    20 122°47'43.40'' 39°04'36.73''  123.  39.1

“Look’s ok”, but remember do still some double checking

Another example we sometime see is the decimal, minute and second in one column but separated by space. Like:

ex3 <- 
  tibble(Long = c("82 38 58", "82 38 46", "82 38 34"),
         Lat =  c("22 00 08", "22 00 29", "21 56 41"))
ex3

# A tibble: 3 × 2
  Long     Lat     
  <chr>    <chr>   
1 82 38 58 22 00 08
2 82 38 46 22 00 29
3 82 38 34 21 56 41

Let’s use the function:

ex3 |> 
  mutate(lon = dms2decimmals(Long),
         lat = dms2decimmals(Lat)) |> 
  knitr::kable()

Long	Lat	lon	lat
82 38 58	22 00 08	82.64944	22.00222
82 38 46	22 00 29	82.64611	22.00806
82 38 34	21 56 41	82.64278	21.94472

Again, seems ok.

We are happy that the function works on the above examples. One more test of the function, using this fictitious data, each row having different format for coordinate representation:

tibble(Lon = c("82 37 26", "E 32 ° 38' 10.5''", "122°47'42.02''"),
       Lat = c("21 49 35", "S 00 ° 02' 35.0''", "39°04'33.85''"),
       country = c("Cuba", "Uganda", "China")) |> 
  mutate(lon = dms2decimmals(Lon),
         lat = dms2decimmals(Lat)) |> 
  knitr::kable()

Lon	Lat	country	lon	lat
82 37 26	21 49 35	Cuba	82.62389	21.8263889
E 32 ° 38’ 10.5’’	S 00 ° 02’ 35.0’’	Uganda	32.63625	-0.0430556
122°47’42.02’’	39°04’33.85’’	China	122.79501	39.0760694

So I get decimal degrees in all cases, so it seems that it also works on mixture of cases within the same variable.

Smallprint: The function works only works if your data is in degrees-minutes-seconds. If your data is e.g. in degrees-minutes-decimalminutes you may get a numeric value but it may be incorrect!