Overview of nc functionality

2023-08-31

Overview of nc functionality

Here is an index of topics which are explained in the different vignettes, along with an overview of functionality using simple examples.

Capture first match in several subjects

Capture first is for the situation when your input is a character vector (each element is a different subject), you want find the first match of a regex to each subject, and your desired output is a data table (one row per subject, one column per capture group in the regex).

subject.vec <- c(
  "chr10:213054000-213,055,000",
  "chrM:111000",
  "chr1:110-111 chr2:220-222")
nc::capture_first_vec(
  subject.vec, chrom="chr.*?", ":", chromStart="[0-9,]+", as.integer)
#>    chrom chromStart
#> 1: chr10  213054000
#> 2:  chrM     111000
#> 3:  chr1        110

A variant is doing the same thing, but with input subjects coming from a data table/frame with character columns.

subject.dt <- data.table::data.table(
  JobID = c("13937810_25", "14022192_1"),
  Elapsed = c("07:04:42", "07:04:49"))
int.pat <- list("[0-9]+", as.integer)
nc::capture_first_df(
  subject.dt,
  JobID=list(job=int.pat, "_", task=int.pat),
  Elapsed=list(hours=int.pat, ":", minutes=int.pat, ":", seconds=int.pat))
#>          JobID  Elapsed      job task hours minutes seconds
#> 1: 13937810_25 07:04:42 13937810   25     7       4      42
#> 2:  14022192_1 07:04:49 14022192    1     7       4      49

Capture all matches in a single subject

Capture all is for the situation when your input is a single character string or text file subject, you want to find all matches of a regex to that subject, and your desired output is a data table (one row per match, one column per capture group in the regex).

nc::capture_all_str(
  subject.vec, chrom="chr.*?", ":", chromStart="[0-9,]+", as.integer)
#>    chrom chromStart
#> 1: chr10  213054000
#> 2:  chrM     111000
#> 3:  chr1        110
#> 4:  chr2        220

Reshape a data table with regularly named columns

Capture melt is for the situation when your input is a data table/frame that has regularly named columns, and your desired output is a data table with those columns reshaped into a taller/longer form. In that case you can use a regex to identify the columns to reshape.

(one.iris <- data.frame(iris[1,]))
#>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> 1          5.1         3.5          1.4         0.2  setosa
nc::capture_melt_single  (one.iris, part  =".*", "[.]", dim   =".*")
#>    Species  part    dim value
#> 1:  setosa Sepal Length   5.1
#> 2:  setosa Sepal  Width   3.5
#> 3:  setosa Petal Length   1.4
#> 4:  setosa Petal  Width   0.2
nc::capture_melt_multiple(one.iris, column=".*", "[.]", dim   =".*")
#>    Species    dim Petal Sepal
#> 1:  setosa Length   1.4   5.1
#> 2:  setosa  Width   0.2   3.5
nc::capture_melt_multiple(one.iris, part  =".*", "[.]", column=".*")
#>    Species  part Length Width
#> 1:  setosa Petal    1.4   0.2
#> 2:  setosa Sepal    5.1   3.5

Helper functions for defining complex pattterns

Helpers describes various functions that simplify the definition of complex regex patterns. For example nc::field helps avoid repetition below,

subject.vec <- c("sex_child1", "age_child1", "sex_child2")
pattern <- list(
  variable="age|sex", "_",
  nc::field("child", "", "[12]", as.integer))
nc::capture_first_vec(subject.vec, pattern)
#>    variable child
#> 1:      sex     1
#> 2:      age     1
#> 3:      sex     2

It also explains how to define common sub-patterns which are used in several different alternatives.

subject.vec <- c("mar 17, 1983", "26 sep 2017", "17 mar 1984")
pattern <- nc::alternatives_with_shared_groups(
  month="[a-z]{3}", day="[0-9]{2}", year="[0-9]{4}",
  list(month, " ", day, ", ", year),
  list(day, " ", month, " ", year))
nc::capture_first_vec(subject.vec, pattern)
#>    month day year
#> 1:   mar  17 1983
#> 2:   sep  26 2017
#> 3:   mar  17 1984