Skip to contents

Get or set configuration options that control galah behaviour

Source: R/galah_config.R
galah_config.Rd

The galah package supports large data downloads, and also interfaces with the ALA which requires that users of some services provide a registered email address and reason for downloading data. The galah_config function provides a way to manage these issues as simply as possible.

Usage

galah_config(..., profile_path = NULL)

Arguments

...

Options can be defined using the form name = value. Valid arguments are:

  • atlas string: Living Atlas to point to, Australia by default

  • caching logical: if TRUE, results will be cached, and any cached results will be re-used). If FALSE, data will be downloaded.

  • cache_directory string: the directory to use for the cache. By default this is a temporary directory, which means that results will only be cached within an R session and cleared automatically when the user exits R. The user may wish to set this to a non-temporary directory for caching across sessions. The directory must exist on the file system.

  • download_reason_id numeric or string: the "download reason" required. by some ALA services, either as a numeric ID (currently 0--13) or a string (see show_all_reasons() for a list of valid ID codes and names). By default this is NA. Some ALA services require a valid download_reason_id code, either specified here or directly to the associated R function.

  • email string: An email address that has been registered with ALA at this address. A registered email is required for some functions in galah.

  • send_email logical: should you receive an email for each query to atlas_occurrences()? Defaults to FALSE; but can be useful in some instances, for example for tracking DOIs assigned to specific downloads for later citation.

  • verbose logical: should galah give verbose output to assist debugging? Defaults to FALSE.

  • run_checks logical: should galah run checks for filters and columns. If making lots of requests sequentially, checks can slow down the process and lead to HTTP 500 errors, so should be turned off. Defaults to TRUE.

profile_path

string: (optional), path to a directory to store config values in. If provided, config values will be written to a new or existing .Rprofile file for future sessions. NULL by default.

Value

For galah_config(), a list of all options. When galah_config(...) is called with arguments, nothing is returned but the configuration is set.

Examples

To configure your session to allow you to download occurrence records, enter your email in galah_config(). This email should be registered with the ALA, which you can do here

galah_config(email = "your-email@email.com")

Turn on caching in your session

galah_config(caching = FALSE)

It is required by some ALA services that you add a reason for downloading data. To look up all valid reasons to enter, use show_all_reasons()

show_all_reasons()
#> # A tibble: 13 x 2
#>       id name                            
#>    <int> <chr>                           
#>  1     0 conservation management/planning
#>  2     1 biosecurity management/planning 
#>  3     2 environmental assessment        
#>  4     3 education                       
#>  5     4 scientific research             
#>  6     5 collection management           
#>  7     6 other                           
#>  8     7 ecological research             
#>  9     8 systematic research/taxonomy    
#> 10    10 testing                         
#> 11    11 citizen science                 
#> 12    12 restoration/remediation         
#> 13    13 species modelling

Add your selected reason using the option download_reason_id

galah_config(download_reason_id = 0)

You can also make debugging in your session easier by setting verbose = TRUE

galah_config(download_reason_id = 0,
             verbose = TRUE)