unitted: Attach units to data

In appling/unitted: Track Units as you Manipulate Data

Description

A unitted object is the fusion of data and units. The unitted() function, or its alias u(), constructs an object inheriting from the unitted class.

tbl_dfs work very similarly to data.frames

Usage

u(object, units = NA, ...)

unitted(object, units = NA, ...)

## S4 method for signature 'data.frame'
unitted(object, units = NA, ...)

## S4 method for signature 'tbl_df'
unitted(object, units = NA, ...)

## S4 method for signature 'array'
unitted(object, units = NA, ...)

## S4 method for signature 'list'
unitted(object, units = NA, ...)

## S4 method for signature 'unitted'
unitted(object, units = NA, ...)

Arguments

object	A vector, data.frame, array, matrix, list, or S4 object containing data
units	A specification of the units to attach to object. The class and form of units depends on the class of object; see Details
...	Further arguments passed to unitbundle() for each unitted vector or element created

Details

The short constructor name (u) makes it easy to write clean code that enforces units consistency throughout your data analysis. The underlying constructor function is called unitted() but aliased to u(). Similarly, units can be removed from data using the deunitted() function or its alias v().

Data.frames

In a call to unitted(object, units, ...) where object is a non-unitted data.frame, object may contain columns that are non-unitted, unitted, or a mix.

units may be one of three possibilities: (1) a character vector of unit strings or NAs, one per column of the data.frame, (2) a list of the same length as ncol(object) where each element is a units specification of one of the forms permitted by unitbundle(), or (3) either NA or missing, indicating that units should be inferred from current units of the data.frame columns.

If object contains some unitted columns, the units of those columns will be preserved if and only if the corresponding element of units is NA. To overwrite a previously unitted column's units with empty units, specify the new units for that column with "". Any non-unitted column with a corresponding NA in units is given units of "".

Known issue: Attaching units to a data.frame with unitted() creates row names for the data.frame even if they were absent before. This is a known issue with no known resolution. In other respects, unitted data.frames behave very much like non-unitted data.frames.

Arrays and matrices

Arrays and matrices are currently only permitted to have one unit apiece. This may change in the future; if this is a feature you want implemented, please create an issue on GitHub with information about how you would use multiple units in an array or matrix if the option were available.

Lists

Even non-unitted lists may contain unitted elements (or a mixture of unitted and non-unitted elements). However, there are advantages to defining the list itself as unitted - specifically, operations such as print(), show(), or arithmetic will treat the entire list as unitted, displaying and applying units as appropriate to each element.

A unitted list, unlike a list of unitted elements, may have exactly one unitbundle for the entire list.

Already-unitted objects

The unitted or u function may be used to replicate an already-unitted object or replace its units with new ones. When object is unitted and the units argument is NA, the constructor returns the data untouched. If the units argument is anything else, the call to unitted() replaces the units of object with the new units.

appling/unitted documentation built on May 10, 2019, 12:44 p.m.