catalog: Build a look up table (catalog)
In EhrmannS/rasterTools: Obtain and process earth observation data

Description Usage Arguments Details Value Examples

catalog aims to make working with a wide variety of complex names simpler. Complex terms such as species, administrative units, earth observation file names, etc are related to systematic abbreviations thereof.

1 2	catalog(path = ".", abbreviateBy = NULL, type = NULL, recursive = FALSE, inclType = FALSE, silent = FALSE)

`path`	[`character(1)`] the path to a folder that contains files for which you want to build a catalog.
`abbreviateBy`	[`function`] to translate the original names to abbreviations thereof; see Examples.
`type`	[`character(1)`] the file type for which should be filtered.
`recursive`	[`logical(1)`] should the listing recurse into sub directories (`TRUE`) or should only the specified directory be searched (`FALSE`, default)?
`inclType`	[`logical(1)`] should the file-extension be included in the recorded original names (`TRUE`), or should the file name be included without extension (`FALSE`, default)?
`silent`	[`logical(1)`] should all messages but errors be suppressed (`TRUE`), or should all messages be printed (`FALSE`, default)?

Often data-files come with complicated names, characterising in large detail the content. For a quick workflow, this is often a hindrance and not required, because a shorter yet systematic name can also sufficiently reference files. Typical examples would be:

three or four-letter code for species (apo_fla, myo_gla, ...).
two-letter NUTS code of territorial units (EE, DE, ...).
a short name of some repeated experiment, originally labelled by date_region_researcher_treatment_etc (S11, S12, ...).
...

If you want to work with a relatively large amount of such files on our hard drive, it would be desirable to have some sort of index available, which makes it possible to readily access everything without having to load it to the global environment beforehand. This function tries to help here, by iteratively going through all directories which are specified in path, registering the files (incl. path) of the specified type and deriving a name based on the function defined in abbreviateBy. These information are stored in the data.frame myCatalog in the gloabl environment so that the objects in path can be quickly loaded by referring to their abbreviations.

The recorded original names are internally saved as character vector with the name files and i is used as iterator through its elements. The only limitation for this function hence is that the abbreviation must be some derivative of the original filenames, employing character manipulation functions such as substr, strsplit, toupper, paste0 or any other.

A data.frame with a column of original names and of the associated abreviations.

## Not run: 

# build a catalog for all species for which there are maps in the 'Atlas of
# European mammals'

# 1. create character variable which corresponds to your file names
x <- "Vulpes vulpes.svg"

# 2. combine with character manipulation functions until the pattern matches
strsplit(x, ' ')
unlist(strsplit(x, ' '))
substr(unlist(strsplit(x, ' ')), 1, 3)
paste(substr(unlist(strsplit(x, ' ')), 1, 3), collapse = '_')
tolower(paste(substr(unlist(strsplit(x, ' ')), 1, 3), collapse = '_'))

# 3. turn this into a function and use as value in abbreviateBy.
abbr_species <- function(x){
  tolower(paste(substr(unlist(strsplit(x, ' ')), 1, 3), collapse = '_'))
}

require(magrittr)
catalog(path = rtPaths$emma$local, type = 'svg', inclType = TRUE,
    abbreviateBy = abbr_species) %>%
  subset(abbr %in% c("apo_agr", "apo_fla", "vul_vul"))

## End(Not run)