Variable, the element type of VariableRow, exists to ensure as much as possible that the values computed within an asclepias application can be seamlessly converted to one of the supported target type systems downstream. At present, the conversions all pass through JSON as an intermediary.

Each supported target has an associated variant of Variable. See the variant-specific documentation for details.

Programmers building an asclepias application are intended to wrap their computations in Variable only at the final step of the computations in runVariables. Variable intentionally erases the underlying types it wraps, so as to allow an inhomogeneous list in VariableRow. That makes it inconvenient to work with Variable directly in most cases.

However, users might find it helpful to work with the underlying target types that Variable wraps, such as the base R vectors represented by RTypeRep r. See the documentation for the respective types for details.

To construct a Variable, users will use the smart constructors for each target type, such as rVector. Each supported target is represented by one of the variants of Variable.

Examples

>>> :set -XOverloadedStrings
>>> import Variable
>>> :{
>>> myVar :: Variable
>>> myVar = rVector "myVar" $ as_logical [True, False]
>>> :}
>>> myVar
MkVariableWrapped {varTarget = "RVector", vals = Array [Bool True,Bool
False], attrs = MkVarAttrs {varType = "LGLSXP", varName = "myVar"}, subAttrs
= Array []}

>>> :set -XOverloadedStrings -XDataKinds
>>> import Variable
>>> import qualified Data.Vector as V
>>> :{
>>> ageAtEvent :: RTypeRep 'REALSXP
>>> ageAtEvent = as_numeric [51 :: Double, 30, 60]
>>> maxAgeVar :: Variable
>>> maxAgeVar = rVector "maxAgeVar" $ summarizeWith V.maximum ageAtEvent
>>> :}
>>> maxAgeVar
MkVariableWrapped {varTarget = "RVector", vals = Array [Number 60.0], attrs
= MkVarAttrs {varType = "REALSXP", varName = "maxAgeVar"}, subAttrs = Array
[]}

A VariableRow is the output type of runVariables and is the collection of computed values associated with each ObsUnit of a Cohort. It can be thought of as a row of data for a given observational unit in a given cohort, with each component Variable giving a particular column's value for that observational unit.

See Variable for details.

JSON shape

{
  "varTarget": StypeVector,
  "attrs": {
    "varName": "ageAtIndex",
    "varType": INTSXP
  },
  "subAttrs": {
    "long_label": "Age at day of index, computed from January 7 of smallest provided birth year.",
    "short_label": "Age at day of index",
    "special_attrs": [
      "91"
    ],
    "study_role": null,
    "stypeType": "v_nominal"
  },
  "vals": [
    91
  ]
}

Constructor for RVector with the given name as first argument, automatically producing type attribute information. To produce an RTypeRep, use of the of as_* constructors or produce one directly by constructing the 'Data.Vector.Vector a' with appropriate a, as determined by RTypeRep.

Constructor for RFactor with the given name as first argument, values as second argument and levels as third. Calls factor, which is associated to an unordered factor in R. Note the varType always is STRSXP and not the SEXPTYPE of the input, in keeping with the R implementation in which factor variables are backed by character vectors.

Constructor for StypeVector with the given name as first argument. To produce a Stype, use one of the v_* constructors such as v_binary or as_v_binary.

The "element" type of an RTypeRep. See RTypeRep for more.

Existential type used within inhomogeneous lists of R vectors, in RTypeRep 'VECSXP.

'RTypeRep s' is a Haskell representation of s, an SEXPTYPE, in R. Nothing elements represent NA values.

R SEXP vector types do not distinguish between vectors and their elements, but Haskell does. SEXPElem provides a one-to-one correspondence between 'Vector (Maybe a)' and the supported SEXPTYPE s in R by providing a map between the a and its corresponding Haskell type. 'SEXPElem s' for some SEXPTYPE s is chosen such that the conversion from a Haskell value of type 'RTypeRep s' and the R type s is as seamless as possible.

Each 'SEXPElem s' is wrapped in Maybe within an 'RTypeRep s' to allow for typed NA values in R. For example, Nothing in an RTypeRep 'LGLSXP corresponds to NA_logical_.

A Haskell programmer can work with 'RTypeRep s' types directly, with little to no overhead relative to working with any other 'Data.Vector.Vector (Maybe a)'. Some additional utilities to facilitate conversions are provided as part of the AsRTypeRep class with various aliases, e.g. AsLogical. See the examples.

To work with RTypeRep directly you will need at a minimum the DataKinds extension, and in many cases also the TypeFamilies and FlexibleContexts extensions.

Examples

>>> :set -XOverloadedStrings -XDataKinds -XFlexibleContexts
>>> import Variable
>>> import qualified Data.Vector as V
>>> import GHC.Float (int2Double)
>>> :{
>>> mean :: V.Vector Double -> Double
>>> mean v = V.sum v / int2Double (V.length v)
>>> 
>>> rMean :: (AsNumeric a) => Bool -> a -> RTypeRep 'REALSXP
>>> rMean narm = summarizeWith (op narm) . as_numeric
>>> where op True = Just . mean . V.catMaybes
>>> op False = fmap mean . V.sequence
>>> :}
>>> rMean False (as_integer [True, True]) == V.singleton (Just 1)
True
>>> rMean False (as_integer [1, 2]) == V.singleton (Just 1.5)
True
>>> rMean True (as_integer [Just 1, Just 2, Nothing]) == V.singleton (Just 1.5)
True
>>> rMean False (as_integer [Just 1, Just 2, Nothing]) == V.singleton Nothing
True

R list representation

Some caveats

Advanced usage

Constraints for SomeRTypeRep.

Haskell representation of R's factor, either ordered or unordered. Construct with factor or ordered, preferably.

Constructor for Factor. as_character is called on the first argument. User provided levels in the second argument are sorted and made unique with sortUniq.

Important: As in R, elements of the input vector that do not appear among the levels (after conversion with as_character) are marked as invalid, here represented by Nothing. That check has an \(O(nm)\) runtime cost, where n is the length of the input and m the length of the levels.

To avoid that cost, users can use MkConstructor directly but must themselves ensure all values appear in the levels.

Haskell representatives of vector types from the stype R package. Parameterized by the "prototype" SEXP backing the type. For types such as ContinuousNonneg, with constrained domains not represented in the standard Haskell types, the constraints are enforced in the `v_*` constructors, as in stype.

Stype vectors must always be created with their corresponding StypeAttrs. However, to reduce the overhead in some cases, they can be constructed with `as_v_*` functions calling the appropriate `as_*` coercion functions from SEXP to create the underlying RTypeRep directly from some other Haskell type.

To work with Stype vectors directly, you will want DataKinds.

Examples

>>> :set -XOverloadedStrings -XDataKinds
>>> import Variable
>>> :{
>>> src_dbl :: [Maybe Double]
>>> src_dbl = Nothing : map Just [1, 0.5, 0]
>>> ctx = MkStypeAttrs "important_var" "A very important variable" Nothing
>>> v = as_v_proportion src_dbl ctx
:}
>>> v
Proportion [Nothing,Just 1.0,Just 0.5,Just 0.0] MkStypeAttrs {short_label =
"important_var", long_label = "A very important variable", study_role =
Nothing}

User-provided stype common attributes. SEXPTYPE and name information is purposefully ommitted, since that will appear in VariableAttrs.

Indication of variable role.

Build a Binary from RTypeRep 'LGLSXP and StypeAttrs. Aliases constructor in this case.

Build a Continuous from RTypeRep 'REALSXP and StypeAttrs. Aliases constructor.

Build a ContinuousNonneg from RTypeRep 'REALSXP and StypeAttrs. This converts negative elements to NA, unlike the R function with the same name, which throws an error.

Build a Count from the RTypeRep 'INTSXP and StypeAttrs. This converts negative elements to NA, unlike the R function with the same name, which throws an error.

Build a Nominal with the provided levels as second argument. The RTypeRep r will be converted to a Factor via factor.

Build a Ordered with provided levels as second argument. The 'RTypeRep r' will be converted to a Factor via factor. At present, it is the unescapeArgs responsibility to ensure the provided levels are in the desired order by values, not the lexicographical order on the character vector (in R speak) of factor.

Build a Proportion from RTypeRep 'REALSXP and StypeAttrs. This converts elements less than 0 or greater than 1 to NA, unlike the R function with the same name, which throws an error.

Convert Haskell types to 'RTypeRep s'. It is up to the user to define conversions in a manner consistent with R's behavior. Nothing elements of an 'RTypeRep s' correspond to the NA value in R, where appropriate.

Note: It never makes sense to produce a Nothing element within an RTypeRep 'VECSXP.

Analogous to R's as.logical.

Analogous to R's as.integer.

Analogous to R's as.numeric.

Analogous to R's as.character. Includes versions to directly construct character vectors from lists or vector containing Show elements.

as_list v is analogous to R's as.list(v) for v of the supported RTypeRep s. Note R's ... syntax is not supported here. The constraints provided are those of SomeRTypeRep.

Sort a RTypeRep using sort.

Sort a Vector and return unique elements using sortUniq.

R has no element-of-vector type, only vector types. This utiltity takes Haskell functions that summarize an R vector, and wrap the output in the appropriate RTypeRep, as a singleton, mimicing what R would do and (I hope) lowering the overhead.

Construct a Binary from any a that can be converted to RTypeRep 'LGLSXP.

Construct a Continuous from any a that can be converted to RTypeRep 'REALSXP.

Attempt to construct a ContinuousNonneg from any a that can be converted to RTypeRep 'REALSXP.

Attempt to build a Count from any a that can be converted to RTypeRep 'INTSXP.

Attempt to build a Proportion from an a that can be converted to RTypeRep 'REALSXP.

Run a routine with SomeRTypeRep, whose 'RTypeRep s' type you cannot inspect.

Return the SEXPTYPE of an 'RTypeRep (s :: SEXPTYPE)'.

>>> sexpTypeOf (V.fromList [True]) == LGLSXP
>>> sexpTypeOf (V.fromList [1 :: Double]) == REALSXP

Recover the 'Sing r' from SomeRTypeRep, which recovers the type information lost in the existential type.