nrelUtilityExt

Fold function to apply logical AND to a set of Boolean values. Return null if no values.

Returns all rows from grid a where there are not matching values in grid b, keeping columns from a only.

antiJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Return the number of arguments function fun accepts.

Calculate the coefficient of variation of the root-mean-square error (CV[RMSE]) for vector yhat with respect to measurement vector y, following the CV(RMSE) formula given in ASHRAE Guideline 14.

• y: vector (numeric list) of measured data
• yhat: vector (numeric list) of modeled or predicted data
• p: number of parameters in the model (default = 1)

Transforms dict d into a string compatible with parseFilter. The resulting filter string matches records with tags that include all the name-value pairs in d.

Notes

1. Handles any axon data type supported by toAxonCode. However, data types without an Axon literal (e.g. dateTimes) may cause downstream functions such as parseFilter to fail.
2. Dicts that contain reserved keywords as names, such as "return", will not throw an error but may cause downstream functions such as parseFilter to fail.
3. Null values in d are removed.

Exports one or more functions to a docHaystack::Trio file at the specified handle. See also importFunctions.

Options

Export behavior can be modified by control options passed via opts:

• merge: Dict to merge onto functions prior to export
• preview: Boolean; if true previews the export (see below)
• sort: Tag name or function for sorting functions prior to export; see sort (default = "name")

If preview == true, returns the list of records that would have been written to handle. The preview option may be also be passed as a marker, with preview equivalent to preview:true and -preview equivalent to preview:false, or by passing handle = null.

If the sort option is missing (e.g. by passing -sort) or invalid, then the function records are not sorted prior to export. If sort is present but is not a string or a function, then it is ignored (with a warning).

Given a numeric year or date val, return a haystack::DateSpan representing the fiscal year associated with that year/date, optionally with an offset in whole years.

Fiscal years are numbered by the calendar year in which they end. Fiscal years begin on the 1st of the month returned by fiscalYearStart (October by default). If your project requires a different fiscal year start, override fiscalYearStart locally.

fiscalYear(2020)        >> DateSpan("2019-10-01,2020-09-30")
fiscalYear(2019-02-17)  >> DateSpan("2018-10-01,2019-09-30")
fiscalYear(today(), -1) >> Yields prior fiscal year

Returns the first month of the fiscal year as an integer.

The value returned by this function defines the fiscal year start date for fiscalYear and related functions. The default is 10 (October), corresponding to the U.S. Federal fiscal year start date of October 1. If your project requires a different fiscal year, override this function locally.

Returns all rows and columns from grids a and b. Rows in a with no match in b will have missing entries in the columns joined from b, and vice versa.

fullJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Returns true if x has all the elements in names.

• For dicts, search by key names
• For grids, search by column names

Returns true if x has any of the elements in names.

• For dicts, search by key names
• For grids, search by column names

Imports function records from source, and optionally commits them to the Folio. Supported data types for source are:

• sys::Str: Parsed as docHaystack::Trio using ioReadTrio
• sys::Uri: Parsed as docHaystack::Trio using ioReadTrio
• Anything supported by toRecList: The func records to be imported as a list of Dicts

Other actions taken on import:

• Ignores any records not tagged with func
• Drops func records missing name or src tags (with a warning)
• Removes existing id and mod tags from imported records

Options

Import behavior can be modified by control options passed by opts:

• commit: Boolean; if true commits the imported functions to the database (default = false)
• conflict: Action on conflicts; one of "skip", "overwrite", or "rename" (default = "skip")
• filter: sys::Str compatible with parseFilter; filters (subsets) the imported function records
• merge: Dict to merge onto imported functions
• preview: Boolean; if true previews the import (see below)
• warn: Boolean; if true log warnings (default = true)

The commit, preview, and warn options may be also be passed as markers, with x equivalent to x:true and -x equivalent to x:false.

Conflicts

Conflicts with existing functions (matched by name) are handled based on the conflict option:

• skip: Skip import
• overwrite: Merge imported function onto existing function, overwriting it
• rename: Rename imported function by appending an integer

Renaming will increment the appended integer until no conflict exists. For example, if the imported function is called foo but functions foo and foo1 already exist, then the imported function will be renamed foo2.

Previewing Functions

Enabling the preview option returns a grid summarizing the functions to be imported, whether they already exist, and what action will be taken on conflicts. The grid returned has columns:

• name: Name of the function
• rec: Nested dict with full function record
• exists: Marker; whether the function already exists
• action: sys::Str; action that will be taken

Enabling preview overrides commit and warn to false. Note that if preview is false and commit is false, the function records themselves are returned (not the summary grid described above).

Convenience for b.contains(a); see contains.

Returns all rows from grid a where there are matching values in grid b combining all columns from a and b. If there are multiple matches between a and b, all combinations of the matches are returned.

innerJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Returns the set intersection of two lists or dicts a and b. Behavior for dicts differs by checked:

• If checked == true, verifies that keys included in both a and b have matching values, and throws an error on mismatch.
• If checked == false, excludes name-value pairs with matching keys but differing values.

Examples:

intersect([1, 2, 3],[2, 3, 4])        >> [2, 3]
intersect({a, b}, {a, c})             >> {a}
intersect({a, b:1}, {a, b:1})         >> {a, b:1}
intersect({a, b:1}, {a, b:2})         >> error
intersect({a, b:1}, {a, b:2}, false)  >> {a}

Returns true if val equals haystack::NA, false otherwise.

Core implementation of *Join() functions. Not intended to be used directly.

Returns a haystack::DateSpan for the prior fiscal year. See fiscalYear.

Returns all rows from grid a and all columns from grids a and b. Rows in a with no match in b will have missing entries in the columns joined from b. If there are multiple matches between a and b, all combinations of the matches are returned.

leftJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Calculate the normalized mean bias error (NMBE) for vector yhat with respect to measurement vector y, following the NMBE formula given in ASHRAE Guideline 14.

• y: vector (numeric list) of measured data
• yhat: vector (numeric list) of modeled or predicted data
• p: number of parameters in the model (default = 1)

Fold function to apply logical OR to a set of Boolean values. Return null if no values.

Alias for fullJoin.

Parse a sys::Str val, automatically guessing its data type. Supports all docHaystack::Zinc data types plus the following keywords:

• True: true, True, or TRUE (as Bool)
• False: false, False', or FALSE (as Bool)
• Null: null, Null, or NULL
• NA: na, Na, or NA
• Not a Number (NaN): nan, NaN, or NAN
• Positive Infinity: +inf, +Inf, or +INF
• Negative Infinity: -inf, -Inf, or -INF

For everything else, this function wraps ioReadZinc. The resulting parsing behavior supports most basic Axon data types, but ranges, triple-quoted string literals, and raw string literals are not supported.

If parsing fails and checked is false returns null; otherwise throws an error.

Parse a sys::Str val as a haystack::Coord. val must consist of two number values separated by a comma. If parsing fails and checked = false returns null; otherwise throws an error.

• Numbers must be within the valid range per coord
• Numbers cannot have a unit
• Negative numbers must be preceded by -
• Enclosing parentheses ( ) are optional
• Spaces, tabs, and any preceding non-digit characters are ignored

Examples:

parseCoord("-42,105")                >> C(-42, 105)
parseCoord("coord(40.689, -74.044)") >> C(40.689, -74.044)

Parse a sys::Str val as a haystack::Dict. val must be encoded as a valid docHaystack::Zinc dictionary. Because this function wraps ioReadZinc, it requires Zinc-style syntax rather than Axon syntax for the following data types:

• Null: N instead of null
• Boolean: T/F instead of true/false

Also, ranges, triple-quoted string literals, and raw string literals are not supported.

If parsing fails and checked is false returns null; otherwise throws an error.

Parse a sys::Str val as a sys::List. val must be encoded as a valid docHaystack::Zinc list. Because this function wraps ioReadZinc, it requires Zinc-style syntax rather than Axon syntax for the following data types:

• Null: N instead of null
• Boolean: T/F instead of true/false

Also, ranges, triple-quoted string literals, and raw string literals are not supported.

If parsing fails and checked is false returns null; otherwise throws an error.

Deprecated; in SkySpark 3.1.2+, parseRef already strips leading "@".

Convenience wrapper for parseRef that supports leading "@" without throwing error.

Convert a list of Str to a Uri. Use empty strings at the beginning or end to add leading or trailing slashes, respectively. See also uriPlusSlash to add a trailing slash.

["io", "fileToImport.trio"].pathToUri       >> `io/fileToImport.trio`
["", "proj", "myProj", "io", ""].pathToUri  >> `/proj/myProj/io/`

Fold multiple values into their numeric product. Return null if no values.

Removes NA values from list or dict x.

Side effects: may rearrange dict key order.

Removes NaN values from list or dict x.

Side effects: may rearrange dict key order.

Removes null values from list or dict x.

Side effects: may rearrange dict key order.

Remove any elements from list or dict x that equal val.

Side effects: may rearrange dict key order.

Replicate the value x the specified number of times. Returns a list.

Examples:

rep(1, 2)               >> [1,1]
rep("A", 3).concat("")  >> "AAA"

Convenience wrapper for replace that also accepts uris, lists, and dicts.

• If val is a string, identical to replace
• If val is a uri, it is coerced to string, modified, and re-parsed as a uri
• If val is a list or dict, all its string and uri elements have the replacement applied following the rules above

For lists and dicts, the string replacement is recursive.

Examples:

"hello".replace2("hell", "t")            >> "to"
`io/funcs.txt`.replace2("txt", "trio")   >> `io/funcs.trio`
{a:["b","c"], d:`b`}.replace2("b", "x")  >> {a:["x","c"], d:`x`}

Returns all rows from grid b and all columns from grids a and b. Rows in b with no match in a will have missing entries in the columns joined from a. If there are multiple matches between a and b, all combinations of the matches are returned.

rightJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Returns all rows from grid a where there are matching values in grid b, keeping columns from a only. Differs from innerJoin in that it will never duplicate rows of a.

semiJoin is one of six SQL-style joins modeled on the two-table verbs in the dplyr R package. For more information, including syntax for by and valid options for opts, see the join documentation.

Returns the set difference of two lists or dicts a and b: all elements of a that are not in b.

For dicts, elements for removal are checked by name only. Values are ignored, including for keys mapped to Remove.val.

Examples:

setDiff([1, 2, 3],[2, 3, 4])  >> [1]
setDiff({a, b}, {a, c})       >> {b}
setDiff({a, b:1}, {b:2})      >> {a}
setDiff({a, b:1}, {-b})       >> {a}

Returns a haystack::DateSpan for the current fiscal year. See fiscalYear.

Return a list of type haystack::DateSpan representing the set of whole days for date/time range span. If clip == true, the first and last days are converted to haystack::Span and clipped to the beginning and end of span, respectively.

Return a list of type haystack::DateSpan representing the set of whole fiscal years for date/time range span. If clip == true, the first and last fiscal years are converted to haystack::Span and clipped to the beginning and end of span, respectively. See also fiscalYear.

Return a list of type haystack::DateSpan representing the set of whole months for date/time range span. If clip == true, the first and last months are converted to haystack::Span and clipped to the beginning and end of span, respectively.

Return a list of type haystack::DateSpan representing the set of whole weeks for date/time range span. Weeks begin on the weekday returned by startOfWeek. If clip == true, the first and last weeks are converted to haystack::Span and clipped to the beginning and end of span, respectively.

Return a list of type haystack::DateSpan representing the set of whole years for date/time range span. Years begin on January 1. If clip == true, the first and last years are converted to haystack::Span and clipped to the beginning and end of span, respectively.

Return tomorrow's Date according to context's time zone

Returns the set union of two lists or dicts a and b. Behavior for dicts differs by checked:

• If checked == true, verifies that keys included in both a and b have matching values, and throws an error on mismatch.
• If checked == false, values from a override values from b. This is similar to merge(b, a) except that keys not mapped to Remove.val always take precedence.

Examples:

union([1, 2, 3],[2, 3, 4])        >> [1, 2, 3, 4]
union({a, b}, {a, c})             >> {a, b, c}
union({a, b}, {-b, c}, false)     >> {a, b, c}
union({a, b:1}, {a, b:1})         >> {a, b:1}
union({a, b:1}, {a, b:2})         >> error
union({a, b:1}, {a, b:2}, false)  >> {a, b:1}