Author: William K. Morris

# Selecting and ordering variables

#### William K. Morris

When requesting data using `{finbif}` you can select from among (or order by) many variables (properties of the occurrence records). The default set of variables returned is a small subset of those available. Note that not all variables are available for all records. See `?variables` for details.

## Selecting variables

### Limiting variables

To retrieve a limited set of variables from FinBIF simply specify the desired variables in the `select` argument.

    finbif_occurrence(
      genus  = "Falco",
      select = c("scientific_name", "life_stage", "sex")
    )

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 342668
    #> A data.frame [10 x 3]
    #>         scientific_name life_stage sex
    #> 1  Falco columbarius L…         NA  NA
    #> 2  Falco tinnunculus L…         NA  NA
    #> 3  Falco tinnunculus L…         NA  NA
    #> 4  Falco subbuteo Linn…         NA  NA
    #> 5  Falco tinnunculus L…         NA  NA
    #> 6  Falco subbuteo Linn…         NA  NA
    #> 7  Falco tinnunculus L…         NA  NA
    #> 8  Falco tinnunculus L…         NA  NA
    #> 9  Falco tinnunculus L…         NA  NA
    #> 10 Falco subbuteo Linn…         NA  NA

### Extra variables

To get extra variables as well as the default set, specify the extra variables in addition to the keyword `"default_vars"`.

    finbif_occurrence(select = c("default_vars", "life_stage"))

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 47159747
    #> A data.frame [10 x 13]
    #>                                 record_id      scientific_name abundance lat_wgs84 lon_wgs84
    #> 1                           …JX.1594385#3 Sciurus vulgaris Li…  1         60.23584  25.05693
    #> 2  …KE.176/64895825d5de884fa20e297d#Unit1 Heracleum persicum …        NA  61.08302  22.38983
    #> 3                           …JX.1594382#9 Hirundo rustica Lin…        NA  64.12716  23.99111
    #> 4                          …JX.1594382#37 Pica pica (Linnaeus…        NA  64.12716  23.99111
    #> 5                          …JX.1594382#49 Muscicapa striata (…        NA  64.12716  23.99111
    #> 6                          …JX.1594382#39 Larus canus Linnaeu…        NA  64.12716  23.99111
    #> 7                           …JX.1594382#5 Emberiza citrinella…        NA  64.12716  23.99111
    #> 8                          …JX.1594382#31 Ficedula hypoleuca …        NA  64.12716  23.99111
    #> 9                          …JX.1594382#41 Alauda arvensis Lin…        NA  64.12716  23.99111
    #> 10                         …JX.1594382#21 Numenius arquata (L…        NA  64.12716  23.99111
    #> ...with 0 more record and 8 more variables:
    #> date_time, coordinates_uncertainty, any_issues, requires_verification, requires_identification,
    #> record_reliability, record_quality, life_stage

## Ordering

You can change the order of occurrence records before they are fetched from the server by using the `order_by` argument. The default ordering is `date_start` descending, then `load_date` descending, then `reported_name`.

### Ascending order

By default occurrence records are ordered by variables in ascending order.

    finbif_occurrence("Cygnus cygnus", order_by = "abundance")

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 95730
    #> A data.frame [10 x 12]
    #>                     record_id      scientific_name abundance lat_wgs84 lon_wgs84
    #> 1         …KE.67/9403350#Unit Cygnus cygnus (Linn…  1         60.41667  16
    #> 2  …HR.3691/OBS810893905_Unit Cygnus cygnus (Linn…        NA  61.56563  29.56771
    #> 3             …JX.1026351#259 Cygnus cygnus (Linn…  1         65.89416  28.90961
    #> 4               …JX.1025175#3 Cygnus cygnus (Linn…  1         61.83248  23.40816
    #> 5         …KE.67/9069501#Unit Cygnus cygnus (Linn…  1         52.71667  1.55
    #> 6               …JX.1252188#3 Cygnus cygnus (Linn…        NA  60.17258  24.27095
    #> 7         …KE.67/9465507#Unit Cygnus cygnus (Linn…  1         61.8      22.76667
    #> 8         …KE.67/9607357#Unit Cygnus cygnus (Linn…  1         63.13333  22.43333
    #> 9               …MHU.10961285 Cygnus cygnus (Linn…        NA  64.97813  24.74932
    #> 10 …HR.3691/OBS886590077_Unit Cygnus cygnus (Linn…        NA  61.27566  22.557
    #>              date_time
    #> 1  1997-04-01 13:00:00
    #> 2  2007-05-18 12:00:00
    #> 3  2013-06-24 03:12:00
    #> 4  2014-06-08 03:45:00
    #> 5  1997-01-03 14:00:00
    #> 6  2021-05-23 06:15:00
    #> 7  2000-03-22 12:00:00
    #> 8  2003-06-07 12:00:00
    #> 9  2008-07-12 12:00:00
    #> 10 2020-03-31 12:00:00
    #> ...with 0 more record and 6 more variables:
    #> coordinates_uncertainty, any_issues, requires_verification, requires_identification,
    #> record_reliability, record_quality

### Descending order

You can switch to descending order by prefixing the variable with a dash.

    finbif_occurrence("Cygnus cygnus", order_by = "-abundance")

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 95730
    #> A data.frame [10 x 12]
    #>                      record_id      scientific_name abundance lat_wgs84 lon_wgs84
    #> 1                 …MHU.2981587 Cygnus cygnus (Linn…  6000      64.4     -14.54
    #> 2  …HR.3691/OBS1101526155_Unit Cygnus cygnus (Linn…  1760      62.16389  21.45786
    #> 3   …HR.3691/OBS604642304_Unit Cygnus cygnus (Linn…  1753      64.50736  24.27894
    #> 4   …HR.3691/OBS663568887_Unit Cygnus cygnus (Linn…  1600      65.98787  24.06341
    #> 5                …MHU.28815250 Cygnus cygnus (Linn…  1500            NA        NA
    #> 6   …HR.3691/OBS671353848_Unit Cygnus cygnus (Linn…  1361      64.71656  24.53188
    #> 7                …JX.1357345#5 Cygnus cygnus (Linn…  1300      64.8465   25.2883
    #> 8                …JX.1398409#3 Cygnus cygnus (Linn…  1280      64.8448   25.2816
    #> 9                …MHU.28815110 Cygnus cygnus (Linn…  1200            NA        NA
    #> 10 …HR.3691/OBS1119137190_Unit Cygnus cygnus (Linn…  1163      64.71656  24.53188
    #> ...with 0 more record and 7 more variables:
    #> date_time, coordinates_uncertainty, any_issues, requires_verification, requires_identification,
    #> record_reliability, record_quality

### Multiple variables

You can specify multiple variables to order by. Sorting primacy is from left to right.

    finbif_occurrence(
      "Cygnus olor", order_by = c("finnish_municipality_id", "-abundance")
    )

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 56359
    #> A data.frame [10 x 12]
    #>    record_id      scientific_name abundance lat_wgs84 lon_wgs84           date_time
    #> 1  …12015253 Cygnus olor (J.F. G…  2500            NA        NA 2008-08-17 12:00:00
    #> 2  …13633876 Cygnus olor (J.F. G…  1500            NA        NA 2008-10-03 12:00:00
    #> 3    …780984 Cygnus olor (J.F. G…  1300            NA        NA 2006-02-14 12:00:00
    #> 4    …781416 Cygnus olor (J.F. G…  1300            NA        NA 2006-02-14 12:00:00
    #> 5   …2062563 Cygnus olor (J.F. G…  1200            NA        NA 2006-12-19 12:00:00
    #> 6  …10352894 Cygnus olor (J.F. G…  1100            NA        NA 2008-06-28 12:00:00
    #> 7    …927797 Cygnus olor (J.F. G…  1050            NA        NA 2006-04-05 12:00:00
    #> 8   …3110953 Cygnus olor (J.F. G…  960             NA        NA 2007-10-06 12:00:00
    #> 9  …26309317 Cygnus olor (J.F. G…  900             NA        NA 2009-07-08 12:00:00
    #> 10  …1260385 Cygnus olor (J.F. G…  800       58.66     23.57    2006-04-26 18:00:00
    #> ...with 0 more record and 6 more variables:
    #> coordinates_uncertainty, any_issues, requires_verification, requires_identification,
    #> record_reliability, record_quality

### Random sample

You can also request a random sample (random order) of occurrence records by setting the `sample` argument to `TRUE`.

    finbif_occurrence(sample = TRUE)

Click to show/hide output.

    #> Records downloaded: 10
    #> Records available: 47159747
    #> A data.frame [10 x 12]
    #>                      record_id      scientific_name abundance lat_wgs84 lon_wgs84
    #> 1          …KE.67/5632630#Unit Ficedula hypoleuca …  1         61.74637  22.77479
    #> 2                   …MHU.40397      Prunus padus L.        NA  60.28016  20.25637
    #> 3                 …JX.775148#3 Yezognophos vittari…  1         60.44245  27.006
    #> 4         …KE.67/11580538#Unit Cyanistes caeruleus…  1         60.32754  24.64944
    #> 5                …JX.328070#23 Pechipogo strigilat…        NA  61.54883  21.64192
    #> 6   …HR.3691/OBS889952298_Unit Parus major Linnaeu…  5         66.6165   24.68816
    #> 7               …JX.1025818#50 Garrulus glandarius…  1         63.43302  27.74526
    #> 8  …HR.3691/OBS1104249688_Unit Alauda arvensis Lin…        NA  60.05577  24.06798
    #> 9          …KE.67/8616657#Unit Cyanistes caeruleus…  1         61.5      24.83333
    #> 10                …JX.101375#9 Poecile montanus (C…  7         63.09517  23.1341
    #> ...with 0 more record and 7 more variables:
    #> date_time, coordinates_uncertainty, any_issues, requires_verification, requires_identification,
    #> record_reliability, record_quality