Query a table of a project

Reads one table that processProject() published under path.tables and returns its rows whose where columns take any of the given values, with the selected columns. It writes nothing.

Usage

queryProjectTable(file, root, table, siteID, where, columns)

Arguments

file, root

As for listProjectTables().

table

Name of the table.

siteID

NULL for a global table, or the identifier of the site whose table is read.

where

Named list of non-empty character vectors, one per filtered column; list() keeps every row.

columns

Names of the columns returned, in that order; NULL returns every column, extrapolated last in a DnTable or kmaxTable.

Value

A data.table with the columns of the rows of the table that pass where, in their stored order and with their stored types.

Details

The table is named as in the effects record of processProject() and in listProjectTables(): with siteID = NULL, one of the global tables ShearTable, DnPlotTable, DnTable and kmaxTable at the root of path.tables; with a site identifier, one of the tables DnDraws, PGATable, DnTable and kmaxTable of that site under <ID.gmdp>/<siteID>/, which locates them with the ID.gmdp of the contract. The contract is read and checked, and its paths resolved against root, as processProject() does, and the table is read as listProjectTables() reads it.

Each element of where names a column and gives, as text, the values it may take; a row is returned when every named column takes one of its values. The text is converted to the type of the column, as the values arrive from the command line: a number as JSON spells it ("100", "1.35", "1e-3") for a double column and a whole number for an integer column, "NA" being a missing value in either, such as the TR of the MCE rows; a text column compares the text itself, so its levels are written as stored, "mean" or "0.50" for p. Numbers match exactly: a decimal names its nearest double, so the 17 significant digits of a stored value, as the JSON of a query writes it, select that value. An unknown table or site, a table whose file is absent, a column that the table does not have, a text that does not convert and a value that its column never takes stop the query naming them.

A DnTable or kmaxTable gains the column extrapolated, derived as it is read and never written: 1 when the ky of the row, or its kmax other than 0, lies outside the calibration range that buildKyLimits() gives its model at the mean PGA of the scenario (for DnTable, that of the PGATable of its site, whose absence stops the query naming the file) or, for a tree (ensemble, rigid, flexible), the range of any of its models stored for the same site, scenario, geometry and material, and 0 otherwise. The upper bound of AM88, the mean PGA, is compared with a relative tolerance of 1e-9: when that PGA exceeds 0.80 g the grid of buildKyGrid() ends at it, and its last point can exceed the PGA, as computed or as rounded in the CSV of PGATable, in the last significant digits. where filters the column and columns selects it as a stored column.

Examples

Root <- file.path(tempdir(), "newmarkQuery")
dir.create(Root)
writeLines('{"path": {"tables": "data/newmark"}, "Vref.gmdp": 760,
  "Hs": [10, 12], "lo.min": 0.35, "lo.max": 0.075, "s.min": 2.5, "s.max": 3.5,
  "uscs": {"U1": ["ML", "MH"]}, "IDm": ["U1"], "seed": 20260915}',
  file.path(Root, "newmark.json"))
# \donttest{
processProject(root = Root, steps = "ShearTable")
#> ShearTable wrote ShearTable (18 rows, seed 20260915)
queryProjectTable("newmark.json", root = Root, table = "ShearTable", siteID = NULL,
                  where = list(level = c("0.16", "mean", "0.84")),
                  columns = c("IDg", "level", "Ts", "VS30"))
#>       IDg  level    Ts  VS30
#>    <char> <char> <num> <num>
#> 1:    S10   0.16 0.191 314.7
#> 2:    S10   0.84 0.169 337.8
#> 3:    S10   mean 0.179 326.6
#> 4:    S12   0.16 0.187 289.9
#> 5:    S12   0.84 0.174 316.8
#> 6:    S12   mean 0.180 303.4
# }
unlink(Root, recursive = TRUE)