Create and/or parse output directory paths

Source: R/name_env_out.R

Either create directory path for saving outputs or parse the meta data from an output directory path. The first elements in the list will form directories. The second elements in the list form the name of each directory, separated by "__".

name_env_out(
  set_list,
  base_dir = NULL,
  show_null = FALSE,
  return_contexts = TRUE,
  dir_with_context = FALSE,
  all_files = FALSE,
  search_dir = if (is.null(base_dir)) here::here() else NULL,
  reg_exp = NULL,
  ...
)

Arguments

set_list

Nested list, with two levels, of critical settings (only) for use in output path names. The first elements of the list will return directories. Elements within each of the first elements of the list are concatenated to form the name of each directory (see examples).

base_dir

Character. Directory prefix to the output path.

show_null

Logical. Display "NULL" or "NA" in names (or gsub it out with "").

return_contexts

Logical. If TRUE (default) contexts, directories and path are returned, otherwise just directories and path.

dir_with_context

Logical. If FALSE (default) the first elements in set_list are used as prefix to each context, otherwise no prefix is added. Set to TRUE if there are contexts repeated across any elements of set_list.

all_files

Logical or numeric. Return files within the path column provided in the resulting dataframe? If numeric, passed to the recurse argument of fs::dir_ls().

search_dir

Character. Path(s) to search for the path in the returned tibble. Ignored unless base_dir is null. Allows for searching several different paths for the same path in the returned tibble.

reg_exp

Character. Combined with path in the returned tibble to search for files.

...

Passed to fs::dir_ls(). Arguments path and regexp are already provided, so providing them here will cause an error.

Value

Tibble containing:

  • all contexts: named as per the second level elements of set_list

  • directories: a directory for each element in the first level of set_list

  • path: the output path, prepended with base_dir

Examples


# a list of settings
settings <- list(extent = list(polygons = "sa_ibrasub_xn"
                               , filt_col = NULL
                               , filt_level = NULL
                               , buffer = 0
                               , temp_ext = "P50Y"
                               )
                 , grain = list(x = 90
                                , y = 90
                                , z = "P50Y"
                                , taxonomic = "species"
                                )
                 , reliability = list(rel_geo = 10000
                                      , rel_temp = "P10Y"
                                      )
                 , aoi = list(polygons = "lsa"
                              , filt_col = "LSA"
                              , filt_level = "GA"
                              , buffer = 0
                              )
                 )

# generate an 'out directory' based on those settings
settings$out_dir <- name_env_out(set_list = settings#[1:4]
                                 , base_dir = here::here("inst", "examples")
                                 , dir_with_context = TRUE
                                 )$path
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`

settings$out_dir
#> H:/dev/nige/packages/envFunc/inst/examples/sa_ibrasub_xn______0__P50Y/90__90__P50Y__species/10000__P10Y/lsa__LSA__GA__0

# create the 'out directory'
fs::dir_create(settings$out_dir)

# put some junk files in the 'out directory'
purrr::map(1:10
           , \(x) tempfile(tmpdir = settings$out_dir)
           ) %>%
  fs::file_create()

# use name_env_out to return the list of files, based on the settings
files <- name_env_out(set_list = settings[1:4]
                      , base_dir = here::here("inst", "examples")
                      , dir_with_context = TRUE
                      , all_files = TRUE
                      # dots
                      , recurse = TRUE
                      ) %>%
  tidyr::unnest(cols = c(files)
                , keep_empty = TRUE
                )
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`
#> Joining with `by = join_by(path, extent, grain, reliability, aoi)`

files
#> # A tibble: 90 × 21
#>    extent        extent_polygons extent_filt_col extent_filt_level extent_buffer
#>    <chr>         <chr>           <chr>           <chr>             <chr>        
#>  1 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  2 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  3 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  4 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  5 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  6 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  7 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  8 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#>  9 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#> 10 sa_ibrasub_x… sa_ibrasub_xn   ""              ""                0            
#> # ℹ 80 more rows
#> # ℹ 16 more variables: extent_temp_ext <chr>, grain <chr>, grain_x <chr>,
#> #   grain_y <chr>, grain_z <chr>, grain_taxonomic <chr>, reliability <chr>,
#> #   reliability_rel_geo <chr>, reliability_rel_temp <chr>, aoi <chr>,
#> #   aoi_polygons <chr>, aoi_filt_col <chr>, aoi_filt_level <chr>,
#> #   aoi_buffer <chr>, path <fs::path>, files <fs::path>

# clean up
# fs::dir_delete(settings$out_dir) # only run this if you're sure it is safe
rm(settings, files)