list.files.lsd: List results files from a set of LSD runs
In LSDinterface: Interface Tools for LSD Simulation Results Files

list.files.lsd

R Documentation

List results files from a set of LSD runs

Description

This function produce a character vector of the names of results files produced after the execution of LSD simulation runs. The list can be used with all function in this package requiring the argument files.

Usage

list.files.lsd( path = ".", conf.name = "",
                type = c( "res", "tot", "csv" ),
                compressed = NULL, recursive = FALSE,
                join = FALSE, full.names = FALSE,
                sensitivity = FALSE )

Arguments

`path`	a character vector of full or relative path name to the base directory from where to search the files; the default corresponds to the working directory, `getwd()`. Tilde expansion is performed. Alternatively, the full path and name of the corresponding LSD configuration file (including the `.lsd` extension) can be provided.
`conf.name`	the LSD configuration file name (optionally including the `.lsd` extension) used to generate the desired results files; the default is to return all results files, irrespective of the configuration file used. Alternatively, a regular expression can be supplied. This argument takes precedence of any configuration file name provided together with the `path` argument.
`type`	the type (format/extension) of LSD results files to use among the options `c( "res", "tot", "csv" )`, used to define the extension of the files to be considered. `"res"` is the default. This option can be abbreviated.
`compressed`	a logical value indicating if (`TRUE`) to look only for compressed files with `.gz` extension, or uncompressed ones otherwise (`FALSE`). The default (`NULL`) is to list files irrespective if compressed or not.
`recursive`	a logical value indicating if the listing should recurse into sub-directories of `path`. The default (`FALSE`) is to scan just the sub-directory with the same name as `conf.name` (without the `.lsd` extension or numeric tags), if present (regular expression in `conf.name` is not considered), and `path`. If `TRUE`, the entire sub-directory tree, starting at `path`, is scanned for files.
`join`	a logical value indicating if results files from multiple sub-directories should be joined together in the return list. The default (`FALSE`) is to list files from just a single sub-directory, the first one found during the search starting from `path`.
`full.names`	a logical value specifying if (`TRUE`) the file names should be expanded to absolute path names. The default (`FALSE`) is to use relative (to `path`) file names.
`sensitivity`	a logical value specifying if (`TRUE`) the target results files are part of a sensitivity analysis design of experiment (DoE), which are double numbered in a particular format (`conf.name_XXX_YYY.res[.gz]`). The default (`FALSE`) is to assume files are just single numbered, which is usually inappropriate for DoE results files. See LSDsensitivity package documentation for details.

Details

The order by which sub-directories are explored may be relevant. By default, the function scans for results files in a sub-directory named as conf.name, if present, in the given initial directory path. Next, if conf.name has a numeric suffix in the format name_XXX, where XXX is any number of algarisms, it searches the sub-directory name, if present. Finally, it scans the initial path itself. If results files are present in more than one sub-directory, function returns only the files found in first one (except if join = TRUE), and issues a warning message. If recursive = TRUE, file search starts from path and proceeds until it encompasses the entire sub-directory tree. In this case, if multiple sub-directories contain the desired files, only the initial path takes precedence, and the rest of the tree is recurred in alphabetical order.

Please note that joining files from different sub-directories (join = TRUE) may combine results with incompatible data which cannot be processed together by the read.xxx.lsd() family of functions.

Value

A character vector containing the names of the found results files in the specified (sub) directories (empty if there were no files). If a path does not exist or is not a directory or is unreadable it is skipped.

Note

File naming conventions are platform dependent. The pattern matching works with the case of file names as returned by the OS.

path must specify paths which can be represented in the current codepage, and files/directories below path whose names cannot be represented in that codepage will most likely not be found.

Author(s)

Marcelo C. Pereira

Examples

# get the names of all files the example directory
list.files.lsd( system.file( "extdata", package = "LSDinterface" ) )

# expand search to the entire example directory tree
# for results from a configuration file named "Sim1.lsd"
# and join files found in all sub-directories conatining data
list.files.lsd( system.file( "extdata", package = "LSDinterface" ),
                "Sim1.lsd", recursive = TRUE, join = TRUE )

LSDinterface documentation built on Sept. 11, 2024, 8:22 p.m.