Package 'crunch'

Description

If the variable matches a single geographic shapefile hosted by crunch, addGeoMetadata will make the appropriate CrunchGeography to add to a variable's geo() metadata. It matches based on how well the contents of the variable match the feature properties that are in each shapefile.

Usage

addGeoMetadata(variable, ...)

Arguments

Details

If more than one property of the same geographic shapefile has the same highest matching score, the first one will be used.

If more than one geographic shapefile has the same highest matching score, an error will be printed listing the geographic shapefiles that matched. Information from this error can be used to setup an appropriate CrunchGeography by hand to connect a variable with the metadata needed.

Value

a CrunchGeography object that can be assigned into geo(variable)

Examples

## Not run: 
geo(ds$state) <- addGeoMetadata(ds$state)

## End(Not run)

Description

Add subvariable to an array

Usage

addSubvariable(variable, subvariable)

addSubvariables(variable, subvariable)

Arguments

Value

variable with the indicated subvariables added.

See Also

subvariables()

Examples

## Not run: 
ds$allpets <- addSubvariable(ds$allpets, ds$allpets_4)
ds$petloc <- addSubvariables(ds$petloc, ds[c("petloc_school", "petloc_daycare")])

## End(Not run)

Description

Use addSummaryStat() to add a summary statistic to a CrunchCube object. If not otherwise specified, the summary statistic will be mean and be placed at the bottom of the cube. You can change those defaults by passing any value you can use with SummaryStat() (e.g. position, categories, after).

Usage

addSummaryStat(cube, stat = c("mean", "median"), var, margin, ...)

Arguments

Value

a CrunchCube with the summary statistic Insertion added to the transforms of the variable specified

See Also

SummaryStat

Examples

## Not run: 
pet_feelings
#                   animals
# feelings            cats dogs
#  extremely happy      9    5
#  somewhat happy      12   12
#  neutral             12    7
#  somewhat unhappy    10   10
#  extremely unhappy   11   12

# add a mean summary statistic to a CrunchCube
addSummaryStat(pet_feelings, stat = "mean", var = "feelings")
#                 animals
# feelings                      cats             dogs
#  extremely happy                9                5
#   somewhat happy               12               12
#          neutral               12                7
# somewhat unhappy               10               10
# extremely unhappy               11               12
#             mean 4.90740740740741 4.34782608695652

# we can also store the CrunchCube for use elsewhere
pet_feelings <- addSummaryStat(pet_feelings, stat = "mean", var = "feelings")
pet_feelings
#                 animals
# feelings                      cats             dogs
#  extremely happy                9                5
#   somewhat happy               12               12
#          neutral               12                7
# somewhat unhappy               10               10
# extremely unhappy               11               12
#             mean 4.90740740740741 4.34782608695652

# `addSummaryStat` returns a CrunchCube that has had the summary statistic
# added to it, so that you can still use the Crunch logic for multiple
# response variables, missingness, etc.
class(pet_feelings)
# [1] "CrunchCube"
# attr(,"package")
# [1] "crunch"

# Since `pet_feelings` is a CrunchCube, although it has similar properties
# and behaviors to arrays, it is not a R array:
is.array(pet_feelings)
# [1] FALSE

# cleanup transforms
transforms(pet_feelings) <- NULL
# add a median summary statistic to a CrunchCube
pet_feelings <- addSummaryStat(pet_feelings, stat = "median", var = "feelings")
pet_feelings
#                 animals
# feelings             cats    dogs
#  extremely happy       9       5
#   somewhat happy      12      12
#          neutral      12       7
# somewhat unhappy      10      10
# extremely unhappy      11      12
#           median       5       5

# additionally, if you want a true matrix object from the CrunchCube, rather
# than the CrunchCube object itself, `applyTransforms()` will return the
# array with the summary statistics (just like subtotals and headings)
pet_feelings_array <- applyTransforms(pet_feelings)
pet_feelings_array
#                 animals
# feelings             cats    dogs
#  extremely happy       9       5
#   somewhat happy      12      12
#          neutral      12       7
# somewhat unhappy      10      10
# extremely unhappy      11      12
#           median       5       5

# and we can see that this is an array and no longer a CrunchCube
is.array(pet_feelings_array)
# [1] TRUE

## End(Not run)

Description

This function lets you add more than one variable at a time to a dataset. If you have multiple variables to add, this function will be faster than doing ds$var <- value assignment because it doesn't refresh the dataset's state in between variable POST requests.

Usage

addVariables(dataset, ...)

Arguments

Value

dataset with the new variables added (invisibly)

Description

These methods let you get and set names and aliases for variables in a Dataset's catalog, or within Subvariables in an array variable. They work like the base R names methods.

Usage

aliases(x)

aliases(x) <- value

descriptions(x)

descriptions(x) <- value

emails(x)

types(x)

timestamps(x)

ids(x)

ids(x) <- value

values(x)

values(x) <- value

scriptBody(x)

dates(x)

dates(x) <- value

## S4 method for signature 'AbstractCategories'
names(x)

## S4 replacement method for signature 'AbstractCategories'
names(x) <- value

## S4 method for signature 'AbstractCategories'
ids(x)

## S4 method for signature 'ScriptCatalog'
timestamps(x)

## S4 method for signature 'Script'
timestamps(x)

## S4 method for signature 'Script'
scriptBody(x)

## S4 method for signature 'BatchCatalog'
names(x)

## S4 replacement method for signature 'Categories'
ids(x) <- value

## S4 method for signature 'Categories'
values(x)

## S4 replacement method for signature 'Categories'
values(x) <- value

## S4 method for signature 'Categories'
dates(x)

## S4 replacement method for signature 'Categories'
dates(x) <- value

## S3 method for class 'CrunchDataFrame'
names(x)

## S4 method for signature 'CrunchCube'
names(x)

## S4 method for signature 'CrunchCube'
aliases(x)

## S4 method for signature 'CrunchCube'
descriptions(x)

## S4 method for signature 'CrunchCube'
types(x)

## S4 method for signature 'CrunchCube'
notes(x)

## S4 method for signature 'CrunchDataset'
names(x)

## S4 method for signature 'ShojiCatalog'
names(x)

## S4 replacement method for signature 'ShojiCatalog'
names(x) <- value

## S4 method for signature 'ShojiCatalog'
emails(x)

## S4 method for signature 'CrunchDeck'
names(x)

## S4 replacement method for signature 'CrunchDeck'
names(x) <- value

## S4 method for signature 'CrunchDeck'
types(x)

## S4 replacement method for signature 'MultitableCatalog'
names(x) <- value

## S4 method for signature 'ShojiFolder'
types(x)

## S4 method for signature 'ShojiOrder'
names(x)

## S4 method for signature 'OrderGroup'
names(x)

## S4 method for signature 'SlideCatalog'
names(x)

## S4 replacement method for signature 'SlideCatalog'
names(x) <- value

## S4 method for signature 'SlideCatalog'
types(x)

## S4 method for signature 'ArrayVariable'
names(x)

## S4 method for signature 'TabBookResult'
names(x)

## S4 method for signature 'TabBookResult'
aliases(x)

## S4 method for signature 'TabBookResult'
descriptions(x)

## S4 method for signature 'MultitableResult'
names(x)

## S4 method for signature 'MultitableResult'
aliases(x)

## S4 method for signature 'MultitableResult'
descriptions(x)

## S4 method for signature 'VariableCatalog'
aliases(x)

## S4 replacement method for signature 'VariableCatalog'
aliases(x) <- value

## S4 method for signature 'VariableCatalog'
notes(x)

## S4 replacement method for signature 'VariableCatalog'
notes(x) <- value

## S4 method for signature 'VariableCatalog'
descriptions(x)

## S4 replacement method for signature 'VariableCatalog'
descriptions(x) <- value

## S4 method for signature 'VariableCatalog'
types(x)

## S4 method for signature 'VariableCatalog'
ids(x)

## S4 method for signature 'VariableFolder'
aliases(x)

## S4 method for signature 'list'
types(x)

## S4 method for signature 'VersionCatalog'
names(x)

## S4 method for signature 'VersionCatalog'
descriptions(x)

## S4 method for signature 'VersionCatalog'
timestamps(x)

Arguments

Details

Note that the Dataset names method returns the aliases of its variables by default. This behavior is controlled by envOrOption("crunch.namekey.dataset"). Set options(crunch.namekey.dataset="name") if you wish to use variable names. See the variables vignette for more information.

Value

Getters return the character object in the specified slot; setters return x duly modified.

See Also

Subvariables Categories base::names() vignette("variables", package="crunch")

Description

With Crunch, you can add additional rows to a dataset by appending a second dataset to the bottom of the original dataset. Crunch makes intelligent guesses to align the variables between the two datasets and to harmonize the categories and subvariables of variables, as appropriate.

Usage

appendDataset(dataset1, dataset2, upsert = FALSE)

Arguments

Details

Variables are matched between datasets based on their aliases. Variables present in only one of the two datasets are fine; they're handled by filling in with missing values for the rows corresponding to the dataset where they don't exist. For variables present in both datasets, you will have best results if you ensure that the two datasets have the same variable names and types, and that their categorical and array variables have consistent categories. To preview how datasets will align when appended, see compareDatasets().

Particularly if you're appending to datasets that are already shared with others, you may want to use the fork-edit-merge workflow when appending datasets. This allows you to verify your changes before releasing them to the other viewers of the dataset. To do this fork the dataset with forkDataset(), append the new data to the fork, ensure that the append worked as expected, and then merge the fork back to the original dataset with mergeFork(). For more, see vignette("fork-and-merge", package = "crunch").

Value

dataset1, updated with dataset2, potentially filtered on rows and variables, appended to it.

Examples

## Not run: 
ds <- loadDataset("Survey, 2016")
new_wave <- loadDataset("Survey, 2017")
ds <- appendDataset(ds, new_wave)

## End(Not run)

Description

Crunch allows you to stream data to a dataset. Streaming data is useful for datasets which have frequent updates (see the Crunch API documentation for more information). Crunch automatically appends streamed data periodically; however, if you would like to trigger appending pending streamed data to a dataset, you can call appendStream().

Usage

appendStream(ds)

Arguments

Value

the dataset with pending stream data appended.

Description

"Archived" datasets are excluded from some views. "Draft" datasets are visible only to editors, while published datasets are available to all viewers. A dataset can either be published or in draft, but not both. These properties are accessed and set with the "is" methods. You can also set the properties by assigning into the function. The verb functions archive and publish are alternate versions of the setters.

Usage

is.archived(x)

is.archived(x) <- value

is.draft(x)

is.draft(x) <- value

is.published(x)

is.published(x) <- value

## S4 method for signature 'CrunchDataset'
is.archived(x)

## S4 method for signature 'CrunchDataset'
is.draft(x)

## S4 method for signature 'CrunchDataset'
is.published(x)

## S4 replacement method for signature 'CrunchDataset,logical'
is.archived(x) <- value

archive(x)

## S4 replacement method for signature 'CrunchDataset,logical'
is.draft(x) <- value

## S4 replacement method for signature 'CrunchDataset,logical'
is.published(x) <- value

publish(x)

## S4 method for signature 'DatasetCatalog'
is.archived(x)

## S4 method for signature 'DatasetCatalog'
is.draft(x)

## S4 method for signature 'DatasetCatalog'
is.published(x)

## S4 replacement method for signature 'DatasetCatalog,logical'
is.archived(x) <- value

## S4 replacement method for signature 'DatasetCatalog,logical'
is.draft(x) <- value

## S4 replacement method for signature 'DatasetCatalog,logical'
is.published(x) <- value

Arguments

Value

For the getters, the logical value of whether the dataset is archived, in draft mode, or published, where draft and published are inverses. The setters return the dataset.

Examples

## Not run: 
ds <- loadDataset("mtcars")
is.draft(ds) # FALSE
is.published(ds) # TRUE
identical(is.draft(ds), !is.published(ds))
# Can make a dataset a "draft" by:
is.draft(ds) <- TRUE
is.published(ds) # FALSE
# Could also have set is.published(ds) <- FALSE
# Now, can go the other way by setting is.draft, is.published, or:
ds <- publish(ds)
is.published(ds) # TRUE

is.archived(ds) # FALSE
is.archived(ds) <- TRUE
is.archived(ds) # TRUE
# Could have achieved the same effect by:
ds <- archive(ds)

## End(Not run)

Description

Crunch Variables reside on the server, allowing you to work with datasets that are too big to bring into memory on your machine. Many functions, such as max, mean, and crtabs(), translate your commands into API queries and return only the result. But, not every operation you'll want to perform has been implemented on the Crunch servers. If you need to do something beyond what is currently supported, you can bring a variable's data into R with as.vector(ds$var) and work with it like any other R vector.

Usage

## S4 method for signature 'CrunchVariable'
as.vector(x, mode = "any")

## S4 method for signature 'CrunchExpr'
as.vector(x, mode = "any")

Arguments

Details

as.vector transfers data from Crunch to a local R session. Note: as.vector returns the vector in the row order of the dataset. If filters are set that specify an order that is different from the row order of the dataset, the results will ignore that order. If you need the vector ordered in that way, use syntax like as.vector(ds$var)[c(10, 5, 2)] instead.

Value

an R vector of the type corresponding to the Variable. E.g. CategoricalVariable yields type factor by default, NumericVariable yields numeric, etc.

See Also

as.data.frame for another interface for (lazily) fetching data from the server as needed; exportDataset() for pulling all of the data from a dataset.

Description

This method allows you to eval within a Dataset.

Usage

## S4 method for signature 'CrunchDataset'
as.environment(x)

Arguments

Value

an environment in which named objects are (promises that return) CrunchVariables.

Description

Use the as.* family of functions to make a derived copy of a variable that has been converted into a new type.

Usage

as.Text(x, ...)

as.Numeric(x)

as.Categorical(x, ...)

as.Datetime(x, format = "%Y-%m-%d %H:%M:%S", resolution, offset)

## S4 method for signature 'CrunchVariable'
as.Numeric(x)

## S4 method for signature 'CrunchVariable'
as.Text(x, format)

## S4 method for signature 'CrunchVariable'
as.Categorical(x, format)

## S4 method for signature 'CrunchVariable'
as.Datetime(x, format = "%Y-%m-%d %H:%M:%S", resolution, offset)

## S3 method for class 'CrunchVariable'
as.double(x, ...)

## S3 method for class 'CrunchVariable'
as.character(x, ...)

## S4 method for signature 'CrunchExpr'
as.Numeric(x)

## S4 method for signature 'CrunchExpr'
as.Text(x, format)

## S4 method for signature 'CrunchExpr'
as.Categorical(x, format)

## S4 method for signature 'CrunchExpr'
as.Datetime(x, format = "%Y-%m-%d %H:%M:%S", resolution, offset)

## S3 method for class 'CrunchExpr'
as.double(x, ...)

## S3 method for class 'CrunchExpr'
as.character(x, ...)

Arguments

Details

Each type of Crunch variable (text, numeric, categorical, etc.) has an ⁠as.*⁠ function (as.Text, as.Numeric, and as.Categorical respectively) that takes the input given as x, and makes a new derived variable that is now of the type specified. See below for detailed examples.

For as.Text and as.Numeric, aliases to the R-native functions as.character and as.numeric are provided for convenience.

Value

a CrunchExpr to be used as the derivation

Examples

## Not run: 
# ds$v1 is of type Text
is.Text(ds$v1)
# [1] TRUE

# that has strings of numbers
as.vector(ds$v1)
# [1] "32"   "8"    "4096" "1024"

# convert this to a numeric variable with the alias `v1_numeric`
ds$v1_numeric <- as.Numeric(ds$v1)

# the values are the same, but are now numerics and the type is Numeric
as.vector(ds$v1_numeric)
# [1]   32    8 4096 1024
is.Numeric(ds$v1_numeric)
# [1] TRUE

# this new variable is derived, so if new data is appended or streamed, the
# new rows of data will be updated.
is.derived(ds$v1_numeric)
# [1] TRUE

## End(Not run)

Description

There are two ways to revert the output of a script:

• undoScript() - A "softer" delete of a script's created artifacts and variables, or

• revertScript() - A "harder" revert that returns the dataset to the state it was before running such script.

Usage

undoScript(dataset, x)

revertScript(dataset, x)

scriptSavepoint(x)

## S4 method for signature 'CrunchDataset,Script'
undoScript(dataset, x)

## S4 method for signature 'CrunchDataset,ANY'
undoScript(dataset, x)

## S4 method for signature 'CrunchDataset,Script'
revertScript(dataset, x)

## S4 method for signature 'CrunchDataset,ANY'
revertScript(dataset, x)

## S4 method for signature 'Script'
scriptSavepoint(x)

Arguments

Details

The difference between both is that a hard revert restores the dataset, as it drops all ensuing scripts and their output (artifacts and variables), while an undo only deletes the artifacts and variables created by this script, but changes made by other scripts and this script's record will remain in place.

The function scriptSavepoint() gets the version object

Value

For undoScript() and revertSctipt(), invisibly return the updated dataset. For scriptSavePoint() a version list object that can be used in restoreVersion().

See Also

runCrunchAutomation() & script-catalog

Description

Get the property features for available geographies

Usage

availableGeodataFeatures(
  x = getAPIRoot(),
  geodatum_fields = c("name", "description", "location")
)

Arguments

Value

a dataframe with all of the available features and geographies for matching

Description

See the appended batches of this dataset

Usage

batches(x)

Arguments

Value

a BatchCatalog

Description

S3 method to concatenate Categories and Category objects

Usage

## S3 method for class 'Categories'
c(...)

## S3 method for class 'Category'
c(...)

Arguments

Value

An object of class Categories

Examples

cat.a <- Category(name = "First", id = 1, numeric_value = 1, missing = FALSE)
cat.b <- Category(name = "Second", id = 2)
cat.c <- Category(name = "Third", id = 3, missing = TRUE)
cats.1 <- Categories(cat.a, cat.b)
identical(cats.1, c(cat.a, cat.b))
identical(c(cats.1, cat.c), Categories(cat.a, cat.b, cat.c))

Description

This method gives you a view of a catalog, such as a VariableCatalog, as a data.frame in order to facilitate further exploration.

Usage

## S3 method for class 'VariableCatalog'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  keys = c("alias", "name", "type"),
  ...
)

## S3 method for class 'ShojiCatalog'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)

## S3 method for class 'BatchCatalog'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  keys = c("id", "status"),
  ...
)

## S3 method for class 'FilterCatalog'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  keys = c("name", "id", "is_public"),
  ...
)

## S3 method for class 'UserCatalog'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  keys = c("name", "email", "teams", "collaborator"),
  ...
)

Arguments

Details

Modifying the data.frame produced by this function will not update the objects on the Crunch server. Other methods exist for updating the metadata in the variable catalog, for example. See vingette("variables", package = "crunch").

Value

A data.frame including metadata about each entity contained in the catalog. The fields in the data.frame match the keys argument provided to the function, and each row represents a entity.

Examples

## Not run: 
ds <- loadDataset("iris")
vars <- variables(ds)
var_df <- as.data.frame(vars, keys = TRUE)
# With row names
as.data.frame(vars, row.names = urls(vars))

## End(Not run)

Description

CategoricalVariables, as well as the array types composed from Categoricals, contain Categories. Categories are a subclass of list that contains only Category objects. Category objects are themselves subclasses of lists and contain the following fields:

• "name": The name of the category, must be unique within a set of categories

• "id": An integer that uniquely identifies the category

• "numeric_value": A numeric value associated with the category (defaults to NA meaning that no value is associated, not that the category is missing)

• "missing": Logical indicating whether the category should be considered missing (defaults to FALSE)

• "selected": Logical indicating whether the category is selected or not (defaults to FALSE)

• "date": A string indicating a day or range of days that should be associated with the category. Accepted formats are "YYYY-MM-DD" ("2020-01-01") for a day, "YYYY-WXX" ("2020-W01") for an ISO week (a week that starts on a Monday, with the first week of the year being the first week with more than 4 days in it), "YYYY-MM" ("2020-01") for a month, "YYYY" ("2020") for a year, or "YYYY-MM-DD,YYYY-MM-DD" ("2020-01-01,2020-01-10") for a range of days.

Usage

Categories(..., data = NULL)

Category(..., data = NULL)

Arguments

Examples

cat.a <- Category(name = "First", id = 1, numeric_value = 1, missing = FALSE)
cat.b <- Category(data = list(name = "First", id = 1, numeric_value = 1, missing = FALSE))
identical(cat.a, cat.b)
cat.c <- Category(name = "Second", id = 2)
cats.1 <- Categories(cat.a, cat.c)
cats.2 <- Categories(data = list(cat.a, cat.c))
identical(cats.1, cats.2)

Description

Crunch categorical variables have slightly richer metadata than R's factor variables. This function generates a list of category data from a factor's levels which can then be further manipulated in R before being imported into Crunch.

Usage

categoriesFromLevels(level_vect)

Arguments

Value

A list with each category levels id, name, numeric_value, and missingness.

Examples

categoriesFromLevels(levels(iris$Species))

Description

Like cd in a file system, this function takes you to a different folder, given a relative path specification.

Usage

cd(x, path, create = FALSE)

Arguments

Value

A Folder (VariableFolder or ProjectFolder)

See Also

mv() to move entities to a folder; rmdir() to delete a folder; base::setwd() if you literally want to change your working directory in your local file system, which cd() does not do

Examples

## Not run: 
ds <- loadDataset("Example survey")
demo <- cd(ds, "Demographics")
names(demo)
# Or with %>%
require(magrittr)
ds <- ds %>%
    cd("Demographics") %>%
    names()
# Can combine with mv() and move things with relative paths
ds %>%
    cd("Key Performance Indicators/Brand X") %>%
    mv("nps_x", "../Net Promoters")

## End(Not run)

Description

Changes the id of a category from an existing value to a new one. The variable can be a categorical, categorical array, or multiple response variable. The category changed will have the same numeric value and missing status as before. The one exception to this is if the numeric value is the same as the id, then the new numeric value will be the same as the new id.

Usage

changeCategoryID(variable, from, to)

Arguments

Details

It is highly recommended to disable any exclusion filter before using changeCategoryID, especially if it is being called multiple times in quick succession (e.g. as part of an automated script). If a problematic exclusion is encountered changeCategoryID will attempt to disable and re-enable the exclusion, but that process will be repeated for every call made which could have adverse consequences (not to mention slow down processing time).

Value

variable with category from and all associated data values mapped to id to

Examples

## Not run: 
ds$country <- changeCategoryID(ds$country, 2, 6)

## End(Not run)

Description

Sometimes append operations do not succeed, whether due to conflicts between the two datasets or other server-side issues. Failed appends can leave behind "error" status batch records, which can cause confusion. This function lets you delete batches that don't match the status or statuses you want to keep.

Usage

cleanseBatches(dataset, keep = c("imported", "appended"))

Arguments

Value

dataset with the specified batches removed.

Description

This function allows you to combine the categories of a variable without making a copy of the variable.

Usage

collapseCategories(var, from, to)

Arguments

Value

the variable duly modified

See Also

combine()

Description

Crunch allows you to create a new categorical variable by combining the categories of another variable. For instance, you might want to recode a categorical variable with three categories small, medium, and large to one that has just small and large.

Usage

combine(variable, combinations = list(), ...)

combineCategories(variable, combinations = list(), ...)

combineResponses(variable, combinations = list(), ...)

Arguments

Details

Categorical and categorical array variables can have their categories combined (by specifying categories in the combinations argument). Multiple response variables can only have their responses (or items) combined (by specifying responses in the combinations argument). Categorical array items are not able to be combined together (even by specifying responses).

dplyr users may experience a name conflict between crunch::combine() and dplyr:: combine(). To avoid this, you can either explicitly use the ⁠crunch::⁠ prefix, or you can call combineCategories() and combineResponses(), provided for disambiguation.

Value

A VariableDefinition that will create the new combined-category or -response derived variable. Categories/responses not referenced in combinations will be appended to the end of the combinations.

Examples

## Not run: 
ds$fav_pet2 <- combine(ds$fav_pet,
    name = "Pets (combined)",
    combinations = list(
        list(name = "Mammals", categories = c("Cat", "Dog")),
        list(name = "Reptiles", categories = c("Snake", "Lizard"))
    )
)
ds$pets_owned2 <- combine(ds$allpets,
    name = "Pets owned (collapsed)",
    combinations = list(list(name = "Mammals", responses = c("Cat", "Dog")))
)

## End(Not run)

Description

When one dataset is appended to another, variables and subvariables are matched on their aliases, and then categories for variables that have them are matched on category name. This function lines up the metadata between two datasets as the append operation will so that you can inspect how well the datasets will align before you do the append.

Usage

compareDatasets(A, B)

Arguments

Details

Calling summary on the return of this function will print an overview of places where the matching on variable alias and category name may lead to undesired outcomes, enabling you to alter one or both datasets to result in better alignment.

Value

An object of class 'compareDatasets', a list of three elements: (1) 'variables', a data.frame of variable metadata joined on alias; (2) 'categories', a list of data.frames of category metadata joined on category name, one for each variable with categories; and (3) 'subvariables', a list of data.frames of subvariable metadata joined on alias, one for each array variable.

Summary output reports on (1) variables that, when matched across datasets by alias, have different types; (2) variables that have the same name but don't match on alias; (3) for variables that match and have categories, any categories that have the same id but don't match on name; (4) for array variables that match, any subvariables that have the same name but don't match on alias; and (5) array variables that, after assembling the union of their subvariables, point to subvariables that belong to other arrays.

Examples

## Not run: 
comp <- compareDataset(ds1, ds2)
summary(comp)

## End(Not run)

Description

Create a new variable that has values when specific conditions are met. Conditions are specified using a series of formulas: the left-hand side is the condition that must be true (a CrunchLogicalExpr) and the right-hand side is where to get the value if the condition on the left-hand side is true. This is commonly a Crunch variable but may be a string or numeric value, depending on the type of variable you're constructing.

Usage

conditionalTransform(
  ...,
  data,
  else_condition = NA,
  type = NULL,
  categories = NULL,
  formulas = NULL
)

Arguments

Details

The type of the new variable can depend on the type(s) of the source variable(s). By default (type=NULL), the type of the new variable will be the type of all of the source variables (that is, if all of the source variables are text, the new variable type will be text, if all of the source variables are categorical, the new variable will be categorical). If there are multiple types in the source variables, the result will be a text variable. The default behavior can be overridden by specifying type = "categorical", "text", or "numeric".

conditionalTransform is similar to makeCaseVariable; however, conditionalTransform can use other Crunch variables as a source of a variable, whereas, makeCaseVariable can only use characters. This additional power comes at a cost: makeCaseVariable can be executed entirely on Crunch servers, so no data needs to be downloaded or uploaded to/from the local R session. conditionalTransform on the other hand will download the data necessary to construct the new variable.

Value

a Crunch VariableDefinition

Examples

## Not run: 

ds$cat_opinion <- conditionalTransform(pet1 == "Cat" ~ Opinion1,
    pet2 == "Cat" ~ Opinion2,
    pet3 == "Cat" ~ Opinion3,
    data = ds,
    name = "Opinion of Cats"
)

## End(Not run)

Description

Potentially destructive actions require that you confirm that you really want to do them. If you're running a script and you know that you want to perform those actions, you can preemptively provide consent.

Usage

consent()

with_consent(expr)

Arguments

Value

consent returns an S3 class "contextManager" object, which you can use with with. with_consent evaluates its arguments inside the consent context.

See Also

with-context-manager ContextManager

Examples

## Not run: 
with(consent(), delete(ds))
# Equivalent to:
with_consent(delete(ds))

## End(Not run)

Description

Context managers

Usage

ContextManager(
  enter = function() {
 },
  exit = function() {
 },
  error = NULL,
  as = NULL
)

Arguments

Value

an S3 class "contextManager" object

See Also

with-context-manager

Description

Copy the folder structure from one dataset to another.

Usage

copyFolders(source, target)

Arguments

Value

returns the target dataset with source's folder structure

Examples

## Not run: 
ds <- copyFolders(ds1, ds)

## End(Not run)

Description

copyOrder is deprecated and will be removed in a future version. Instead, you should use the copyFolders function.

Usage

copyOrder(source, target)

Arguments

Value

returns an object of class VariableOrder (which can be assigned to a dataset with ordering)

Examples

## Not run: 
ordering(ds) <- copyOrder(ds1, ds)

## End(Not run)

Description

Makes a copy of a Crunch variable on the server.

Usage

copyVariable(x, deep = FALSE, ...)

copy(x, deep = FALSE, ...)

Arguments

Details

Copies can be shallow (linked) or deep. Shallow copying is faster and is preferable unless a true hard copy is required. Shallow copies are effectively pointers to the original variable, and then you append data to the original variable or otherwise alter its values, the values in the copy automatically update. This linking may be desirable, but it comes with some limitations. First, you cannot edit the values of the copy independently of the original. Second, some attributes of the copy are immutable: of note, properties of categories cannot be altered independently in the copy, but you can alter Subvariable names and ordering within arrays.

Value

a VariableDefinition for the copied variable. Assign into a Dataset to make the copy happen.

Description

If you have manually created a Crunch dataset object with prepareDataForCrunch() this function allows you to upload it to the app.

Usage

createWithPreparedData(data, metadata = attr(data, "metadata"))

Arguments

Value

A CrunchDataset.

Description

Create a contingency table or other aggregation from cross-classifying variables in a CrunchDataset, expanding on the notation allowed in stats::xtabs() to tailor to the kinds of calculations available in crunch.

Usage

crtabs(
  formula,
  data,
  weight = crunch::weight(data),
  useNA = c("no", "ifany", "always")
)

Arguments

Details

There are 3 types of queries supported:

• Crosstabs: Share the most in common with stats::xtabs(), are defined by a formula with only a right hand side, with each dimension specified on the right-hand side, separated by a +. A dimension are generally variables, but categorical array variables contribute 2 dimensions, “categories” and “subvariables”. If you just use the categorical array variable directly, the subvariables dimensions will be added first and the categories second, but you can choose their order by specifying both categories(var) and subvariables(var) (where var is a Categorical Array CrunchVariable).

• Aggregations: An extension to 'Crosstabs' where you can select one or more measures by putting them in the left-hand side of the formula. Multiple measures can be placed in a list to calculate them together. The currently supported measures are mean(var), n() (the same as a crosstab), min(var), max(var), sd(var), sum(var) and median(var) (where var is a CrunchVariable).

• Scorecards: When you want to compare multiple MR variables with the same subvariables, you can use a scorecard to create a tabulation where they are lined up. Scorecard queries cannot be combined with the other types. Use the scorecard(..., vars = NULL) (where ... is a set of MR variables or vars is a list of them).

Value

an object of class CrunchCube

See Also

weight()

Examples

## Not run: 
# Crosstab of people by `age_cat`:
crtabs(~age_cat, ds)

# Aggregation of means of income by `age_cat`
crtabs(mean(income) ~ age_cat, ds)

# Scorecard of multiple MRs with aligned subvariables
crtabs(~scorecard(trust_mr, value_mr, quality_mr), ds)
# Can also pre-define the variables in a scorecard with
mr_list <- list(ds$trust_mr, ds$value_mr, ds$quality_mr)
crtabs(~scorecard(vars = mr_list), ds)

# Crosstab of people by `age_cat` and the reasons for enjoying a brand (cat array)
crtabs(~age_cat + enjoy_array, ds)

# Crosstab of people by `age_cat` and the `enjoy_array` (cat array)
# But manually choosing the order of the dimensions
crtabs(~subvariables(enjoy_array) + age_cat + categories(enjoy_array), ds)

# Aggregation of means & standard deviations of income by `age_cat`
crtabs(list(mean = mean(income), sd = sd(income)) ~ age_cat, ds)

## End(Not run)

Description

Get a situation report on how R will connect to crunch.io

Usage

crunch_sitrep(redact = TRUE, verbose = TRUE)

Arguments

Value

Invisibly, a list with information about the API

Examples

## Not run: 
crunch_sitrep()

## End(Not run)

Description

The rcrunch package recommends using API keys for authentication.

Details

To get an API key for your account, follow the instructions in the crunch help desk

The rcrunch package looks for the key in the environmental variable "R_CRUNCH_API_KEY" or the option "crunch.api.key" (see envOrOption() for details).

One way to establish your key is to add it to your ".Renviron" file. This file is located in your home directory (you can use usethis::edit_r_environ() to open the file if you have the usethis package installed). The .Renviron file has the name of the environment variable, followed by an equal sign and then the value. It is good practice to set the API host too, (usually equal to "https://app.crunch.io/api/").

R_CRUNCH_API=https://app.crunch.io/api/
R_CRUNCH_API_KEY=YOUR_SECRET_KEY

You can either restart your session, or run readRenviron("~/.Renviron") and then rcrunch will know to use your key going forward.

Description

Univariate statistics on Crunch objects

Usage

mean(x, ...)

sd(x, na.rm = FALSE)

median(x, na.rm = FALSE, ...)

## S4 method for signature 'CrunchVariable'
mean(x, ...)

## S4 method for signature 'NumericVariable'
mean(x, ...)

## S4 method for signature 'CrunchVariable'
sd(x, na.rm = FALSE)

## S4 method for signature 'NumericVariable'
sd(x, na.rm = FALSE)

## S4 method for signature 'CrunchVariable'
min(x, na.rm)

## S4 method for signature 'NumericVariable'
min(x, na.rm = FALSE)

## S4 method for signature 'DatetimeVariable'
min(x, na.rm = FALSE)

## S4 method for signature 'CrunchVariable'
max(x, na.rm)

## S4 method for signature 'NumericVariable'
max(x, na.rm = FALSE)

## S4 method for signature 'DatetimeVariable'
max(x, na.rm = FALSE)

Arguments

See Also

base::mean() stats::sd() stats::median() base::min() base::max()

Description

CrunchBoxes allow you to publish results to the world.

Usage

crunchBox(
  dataset,
  filters = crunch::filters(dataset),
  weight = crunch::weight(dataset),
  brand_colors,
  static_colors,
  category_color_lookup,
  ...
)

CrunchBox(
  dataset,
  filters = crunch::filters(dataset),
  weight = crunch::weight(dataset),
  brand_colors,
  static_colors,
  category_color_lookup,
  ...
)

Arguments

Details

In addition to specifying the variables and filters to include in your CrunchBox, you can provide custom color palettes. The arguments brand_colors, static_colors, and category_color_lookup allow you to provide color lists to use. Colors should be either a valid hexadecimal string representation, like "#fa1af1", or they may also be an R named color, such as "darkgreen".

Value

The URL to the newly created box.

See Also

preCrunchBoxCheck() to provide guidance on what you're including in the CrunchBox

Examples

## Not run: 
# Creating a CrunchBox with three variables
crunchBox(ds[c("var1", "var2", "var3")], title = "New CrunchBox")

# Creating a CrunchBox changing primary, secondary, and message brand colors
crunchBox(ds[c("var1", "var2", "var3")],
    title = "Branded CrunchBox",
    brand_colors = c("#ff0aa4", "#af17ff", "#260aff")
)

# Creating a CrunchBox changing category-specific colors
crunchBox(ds[c("var1", "var2", "var3")],
    title = "CrunchBox with category colors",
    category_color_lookup = list(
        "agree" = "#ff0aa4",
        "disagree" = "#af17ff",
        "don't know" = "#260aff"
    )
)

## End(Not run)

Description

CrunchDataFrames are designed to mimic the ways that data.frames are used. They should be a drop-in replacement in many places where data.frames are used.

Usage

## S3 method for class 'CrunchDataFrame'
dim(x)

Arguments

Details

CrunchDataFrames are generated not by downloading all of the variables from a dataset, but rather only the variables that are needed by subsequent functions. So, if you create a CrunchDataFrame, and then run a linear model using lm(), only the variables used by the linear model will be downloaded.

CrunchDataFrames can be altered (that is: adding more columns, removing columns, subsetting rows, etc.) with the same [, [[, and $ syntax as data.frames.

Description

Crunch Datasets

Description

Crunch stores geographic data as variable metadata. There are a number of functions that help access and change this metadata.

Usage

CrunchGeography(..., data = NULL)

geo(x)

geo(x) <- value

## S4 method for signature 'CrunchVariable'
geo(x)

## S4 replacement method for signature 'CrunchVariable,CrunchGeography'
geo(x) <- value

## S4 replacement method for signature 'CrunchVariable,NULL'
geo(x) <- value

availableGeodata(x = getAPIRoot())

Arguments

Details

geo retrieves the geographic information associate with a variable. If there is geographic information it returns an object of class CrunchGeography otherwise it returns NULL.

CrunchGeography objects store geography metadata from a variable. There are three slots:

• geodatum an object of class CrunchGeodata which stores references to the Crunch-hosted (geo|topo)json to use

• feature_key a character string representing the feature inside of the (geo|topo)json which is used to match match_field (e.g. properties.name)

• match_field a character string representing the variable metadata information which is used to match feature_key to (e.g. name)

Value

geographic information of class CrunchGeography (NULL if there is none)

Examples

## Not run: 
geo(ds$location)

geo(ds$location)$feature_key <- "properties.name"
geo(ds$location)$match_field <- "name"

## End(Not run)

Description

Variables are S4 objects. All inherit from the base class CrunchVariable.

Slots

filter

either NULL or CrunchLogicalExpr

tuple

VariableTuple

Description

These functions provide an interface like base::margin.table() and base::prop.table() for the CrunchCube object. CrunchCubes contain richer metadata than standard R array objects, and they also conceal certain complexity in the data structures from the user. In particular, multiple-response variables are generally represented as single dimensions in result tables, but in the actual data, they may comprise two dimensions. These methods understand the subtleties in the Crunch data types and correctly compute margins and percentages off of them.

Usage

margin.table(x, margin = NULL)

prop.table(x, margin = NULL)

bases(x, margin = NULL)

## S4 method for signature 'CrunchCube'
prop.table(x, margin = NULL)

## S4 method for signature 'CrunchCube'
round(x, digits = 0)

## S4 method for signature 'CrunchCube'
bases(x, margin = NULL)

## S4 method for signature 'CrunchCube'
margin.table(x, margin = NULL)

## S4 method for signature 'MultitableResult'
prop.table(x, margin = NULL)

## S4 method for signature 'TabBookResult'
prop.table(x, margin = NULL)

## S4 method for signature 'TabBookResult'
bases(x, margin = NULL)

## S4 method for signature 'MultitableResult'
bases(x, margin = NULL)

Arguments

Details

These functions also generalize to MultitableResults and TabBookResults, which are returned from a tabBook() request. When called on one of those objects, they effectively apply over each CrunchCube contained in them.

bases is an additional method for CrunchCubes. When making weighted requests, bases allows you to access the unweighted counts for every cell in the resulting table (array). The bases function takes a "margin" argument to work like margin.table, or with margin=0 gives all cell counts.

Value

When called on CrunchCubes, these functions return an array. Calling prop.table on a MultitableResult returns a list of prop.tables of the CrunchCubes it contains. Likewise, prop.table on a TabBookResult returns a list of lists of prop.tables.

See Also

margin.table() prop.table()

Description

Standardized residuals, (observed - expected) / sqrt(V), where V is the residual cell variance (Agresti, 2007, section 2.4.5). Special care is taken for multiple-response variables which are in effect a series of separate tables where ‘not selected’ cells for each item are are hidden.

Usage

zScores(x)

## S4 method for signature 'CrunchCube'
zScores(x)

rstandard(model)

Arguments

Value

an array of standardized residuals or Z-scores from the hypothesis being tested. The default method is that the joint distributions of (weighted) counts are equal to the marginal distributions of the table.

References

Agresti, A. (2007) An Introduction to Categorical Data Analysis, 2nd ed., New York: John Wiley & Sons. Page 38.

See Also

stats::chisq.test

Description

Returns a string describing the measure type of the cube result, such as "count", "mean", "sd", etc.

Usage

cubeMeasureType(x, measure = NULL)

## S4 method for signature 'CrunchCube'
cubeMeasureType(x, measure = 1)

Arguments

Value

A string describing the cube's measure type

Examples

## Not run: 
cube1 <- crtabs(~allpets, ds)
cubeMeasureType(cube1)
#> "count"

cube2 <- crtabs(list(a = n(), b = mean(age)) ~ allpets, ds)
cubeMeasureType(cube2)
#> "count"
cubeMeasureType(cube2, "b")
#> "mean"

## End(Not run)

Description

crunch::cut() is equivalent to base::cut() except that it operates on Crunch variables instead of in-memory R objects. The function takes a Datetime variable and derives a new categorical variable from it based on the breaks argument. You can either break the variable into evenly spaced categories by specifying an interval using a string that defines a period or a vector containing the start and end point of each category. For example, specifying breaks = "2 weeks" will break the datetime data into 2 week size bins while ⁠breaks = as.Date(c("2020-01-01", "2020-01-15" "2020-02-01"))⁠ will recode the data into two groups based on whether the numeric vector falls between January 1 and 14 or January 15 and 31

Usage

## S4 method for signature 'DatetimeVariable'
cut(x, breaks, labels = NULL, dates = NULL, name, right = FALSE, ...)

Arguments

Value

a Crunch VariableDefinition. Assign it into the dataset to create it as a derived variable on the server.

Examples

## Not run: 
ds <- loadDataset("example")
ds$month_cat <- cut(ds$date, breaks = "month", name = "monthly")
ds$four_weeks_cat <- cut(ds$date, breaks = "4 weeks", name = "four week categorical date")

ds$wave_cat <- cut(
    ds$date,
    as.Date(c("2020-01-01", "2020-02-15", "2020-04-01", "2020-05-15")),
    labels = c("wave1", "wave2", "wave3"),
    name = "wave var"
  )

## End(Not run)

Description

crunch::cut() is equivalent to base::cut() except that it operates on Crunch variables instead of in-memory R objects. The function takes a numeric variable and derives a new categorical variable from it based on the breaks argument. You can either break the variable into evenly spaced categories by specifying the number of breaks, or specify a numeric vector identifying the start and end point of each category. For example, specifying breaks = 5 will break the numeric data into five evenly spaced portions while breaks = c(1, 5, 10) will recode the data into two groups based on whether the numeric vector falls between 1 and 5 or 5 and 10.

Usage

## S4 method for signature 'NumericVariable'
cut(
  x,
  breaks,
  labels = NULL,
  name,
  include.lowest = FALSE,
  right = TRUE,
  dig.lab = 3,
  ordered_result = FALSE,
  ...
)

Arguments

Value

a Crunch VariableDefinition. Assign it into the dataset to create it as a derived variable on the server.

Examples

## Not run: 
ds <- loadDataset("mtcars")
ds$cat_var <- cut(ds$mpg,
    breaks = c(10, 15, 20),
    labels = c("small", "medium"), name = "Fuel efficiency"
)
ds$age <- sample(1:100, 32)
ds$age4 <- cut(df$age, c(0, 30, 45, 65, 200),
    c("Youth", "Adult", "Middle-aged", "Elderly"),
    name = "Age (4 category)"
)

## End(Not run)

Description

You can designate a dashboard that will show when the dataset is loaded in the Crunch web app. This dashboard could be a Crunch Shiny ("Crunchy") app, a CrunchBox, an RMarkdown website or something else.

Usage

dashboard(x)

setDashboardURL(x, value)

dashboard(x) <- value

Arguments

Value

The getter returns a URL (character) or NULL. The setter returns the dataset (x).

Examples

## Not run: 
dashboard(ds) <- "https://shiny.crunch.io/example/"

## End(Not run)

Description

This method is defined principally so that you can use a CrunchDataset as a data argument to other R functions (such as stats::lm()) without needing to download the whole dataset. You can, however, choose to download a true data.frame.

Usage

## S3 method for class 'CrunchDataset'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  force = FALSE,
  categorical.mode = "factor",
  row.order = NULL,
  include.hidden = TRUE,
  ...
)

## S3 method for class 'CrunchDataFrame'
as.data.frame(
  x,
  row.names = NULL,
  optional = FALSE,
  include.hidden = attr(x, "include.hidden"),
  array_strategy = c("alias", "qualified_alias", "packed"),
  verbose = TRUE,
  ...
)

Arguments

Details

By default, the as.data.frame method for CrunchDataset does not return a data.frame but instead CrunchDataFrame, which behaves like a data.frame without bringing the whole dataset into memory. When you access the variables of a CrunchDataFrame, you get an R vector, rather than a CrunchVariable. This allows modeling functions that require select columns of a dataset to retrieve only those variables from the remote server, rather than pulling the entire dataset into local memory.

If you call as.data.frame() on a CrunchDataset with force = TRUE, you will instead get a true data.frame. You can also get this data.frame by calling as.data.frame on a CrunchDataFrame (effectively calling as.data.frame on the dataset twice)

When a data.frame is returned, the function coerces Crunch Variable values into their R equivalents using the following rules:

• Numeric variables become numeric vectors

• Text variables become character vectors

• Datetime variables become either Date or POSIXt vectors

• Categorical variables become either factors with levels matching the Crunch Variable's categories (the default), or, if categorical.mode is specified as "id" or "numeric", a numeric vector of category ids or numeric values, respectively

• Array variables (Categorical Array, Multiple Response) can be decomposed into their constituent categorical subvariables or put in 'packed' data.frame columns, see the array_strategy argument.

Column names in the data.frame are the variable/subvariable aliases.

Value

When called on a CrunchDataset, the method returns an object of class CrunchDataFrame unless force = TRUE, in which case the return is a data.frame. For CrunchDataFrame, the method returns a data.frame.

See Also

as.vector()

Description

Crunch datasets are collected in folders called "projects". datasets() can be used to filter a project's contents to see only datasets (and not other projects). You can also use it to pull a catalog of datasets from search results.

Usage

datasets(x = getAPIRoot())

datasets(x) <- value

Arguments

Details

The ⁠datasets()<-⁠ assignment function provides an alternative method for moving a dataset into a project. This may be more convenient in some cases than using mv().

Value

When x is a ProjectFolder, datasets() returns the folder with its "index" filtered to contain only datasets; otherwise, it returns an object of class DatasetCatalog. The assignment function returns the project x with the given dataset added to it.

Examples

## Not run: 
# Get the names of the datasets contained in a project
projects() %>%
    cd("Important Clients") %>%
    datasets() %>%
    names()
# The assignment method lets you move a dataset to a project
proj <- cd(projects(), "Important Clients")
ds <- loadDataset("New important client survey")
datasets(proj) <- ds

## End(Not run)

Description

Crunch decks are stored in catalogs. This function returns those catalogs so that you can access and manipulate decks in R.

Usage

decks(x)

decks(x) <- value

## S4 method for signature 'CrunchDataset'
decks(x)

Arguments

Value

a DeckCatalog

Description

These methods delete entities, notably Datasets and Variables within them, from the server. This action is permanent and cannot be undone, so it should not be done lightly. Consider instead using archive for datasets and hide for variables.

Usage

delete(x, ...)

## S4 method for signature 'CrunchDataset'
delete(x, ...)

## S4 method for signature 'DatasetTuple'
delete(x, ...)

## S4 method for signature 'CrunchDeck'
delete(x, ...)

## S4 method for signature 'CrunchSlide'
delete(x, ...)

## S4 method for signature 'Multitable'
delete(x, ...)

## S4 method for signature 'CrunchTeam'
delete(x, ...)

## S4 method for signature 'CrunchVariable'
delete(x, ...)

## S4 method for signature 'VariableTuple'
delete(x, ...)

## S4 method for signature 'ShojiFolder'
delete(x, ...)

## S4 method for signature 'ShojiTuple'
delete(x, ...)

## S4 method for signature 'ShojiObject'
delete(x, ...)

## S4 method for signature 'ANY'
delete(x, ...)

Arguments

Details

Deleting requires confirmation. In an interactive session, you will be asked to confirm. To avoid that prompt, or to delete objects from a non-interactive session, wrap the call in with_consent() to give your permission to delete.

See Also

hide() deleteDataset() deleteVariables() deleteSubvariables()

Description

This function lets you delete a dataset without first loading it, which is faster.

Usage

deleteDataset(x, ...)

Arguments

Details

The function also works on CrunchDataset objects, just like delete(), which may be useful if you have loaded another package that masks the crunch::delete() method.

Value

(Invisibly) the API response from deleting the dataset

See Also

delete(); cd() for details of parsing and walking dataset folder/project paths.

Description

Deleting variables requires confirmation. In an interactive session, you will be asked to confirm. To avoid that prompt, or to delete subvariables from a non-interactive session, wrap the call in with_consent() to give your permission to delete.

Usage

deleteSubvariables(variable, to.delete)

deleteSubvariable(variable, to.delete)

Arguments

Details

To delete the subvariables the function unbinds the array, deletes the subvariable, and then binds the remaining subvariables into a new array.

Value

a new version of variable without the indicated subvariables

See Also

deleteVariable() delete()

Description

This function permanently deletes a variable from a dataset.

Usage

deleteVariables(dataset, variables)

deleteVariable(dataset, variables)

Arguments

Details

In an interactive session, you will be prompted to confirm that you wish to delete the variable. To avoid that prompt, or to delete variables from a non-interactive session, wrap the call in with_consent() to give your permission to delete.

Value

(invisibly) dataset with the specified variables deleted

See Also

delete(); deleteSubvariable(); For a non-destructive alternative, see hide().

Description

Get a derived variable's derivation formula as a CrunchExpr with derivation(variable). Set (change) a derived variable's derivation with derivation(variable) <- expression.

Usage

derivation(x)

derivation(x) <- value

is.derived(x)

is.derived(x) <- value

## S4 method for signature 'CrunchVariable'
derivation(x)

## S4 replacement method for signature 'CrunchVariable,ANY'
derivation(x) <- value

## S4 replacement method for signature 'CrunchVariable,NULL'
derivation(x) <- value

## S4 method for signature 'CrunchVariable'
is.derived(x)

## S4 replacement method for signature 'CrunchVariable,logical'
is.derived(x) <- value

Arguments

Details

To break a derivation link between a derived variable and the originating variable, set the derivation value of the derived variable to NULL with derivation(variable) <- NULL

is.derived can be used to see if a variable is derived or not. Additionally setting a derived variable's is.derived to FALSE will break the derivation link between two variables.

Value

a CrunchExpr of the derivation for derivation; a logical for is.derived; the variable given in x for ⁠is.derived<-⁠ returns

Examples

## Not run: 

ds$derived_v1 <- ds$v1 + 5

derivation(ds$derived_v1)
# Crunch expression: v1 + 5

derivation(ds$derived_v1) <- ds$v1 + 10
derivation(ds$derived_v1)
# Crunch expression: v1 + 10

is.derived(ds$derived_v1)
# TRUE

# to integrate or instantiate the variable in place (remove the link between
# variable v1 and the derivation) you can:
derivation(ds$derived_v1) <- NULL

# after integrating, the derived variable is no longer derived.
is.derived(ds$derived_v1)
# FALSE

# Derivations can be updated with arbitrary expressions.
# Consider a numeric case variable that combines weights
# calculated separately in a separate variable
# for each of several waves:
ds$weight <- makeCaseWhenVariable(
    ds$wave == 1 ~ ds$weight_wave1,
    ds$wave == 2 ~ ds$weight_wave2,
    ds$wave == 3 ~ ds$weight_wave3,
    name = "Weight"
)

# When a new wave is added, update the derivation
# of the weight to add the new condition and source
# column.
derivation(ds$weight) <- caseWhenExpr(
    ds$wave == 1 ~ ds$weight_wave1,
    ds$wave == 2 ~ ds$weight_wave2,
    ds$wave == 3 ~ ds$weight_wave3,
    ds$wave == 4 ~ ds$weight_wave4
)

## End(Not run)

Description

In most situations we recommend using deriveArray which leaves your subvariables in the dataset. makeArray removes component subvariables from your dataset. Array variables are composed of a set of "subvariables" bound together for display in the app. For example, you might have a set of survey questions that ask how the respondent would rate a TV show from 1-5. Array variables allow you to display all of their ratings in a compact table rather than a set of distinct variables.

Usage

deriveArray(subvariables, name, selections, numeric = NULL, ...)

makeArray(subvariables, name, ...)

makeMR(subvariables, name, selections, ...)

Arguments

Value

A VariableDefinition that when added to a Dataset will create the categorical-array or multiple-response variable. deriveArray will make a derived array expression (or a derived multiple response expression if selections are supplied), while makeArray and makeMR return an expression that "binds" variables together, removing them from independent existence.

Examples

## Not run: 
# Categorical Array - Variables from list of variables
ds$enjoy_cat2 <- deriveArray(
    list(ds$enjoy1, ds$enjoy2),
    "Enjoy activities"
)

# Categorical Array - Variables from var catalog
# (result is the same as `ds$enjoy_cat1` above)
ds$enjoy_cat2 <- deriveArray(
    ds[c("enjoy1", "enjoy2")],
    "Enjoy activities v2"
)

# Multiple Response (selections as character names)
ds$enjoy_mr1 <- deriveArray(
    list(ds$enjoy1, ds$enjoy2),
    "Enjoy activities very much or a little",
    selections = c("Very much", "A little")
)

# Numeric Array
ds$rating_numa <- deriveArray(
    list(ds$rating1, ds$rating2),
    "Activity Rating"
)

# Using VarDef to specify metadata (and thus needing to specify type)
ds$enjoy_mr <- deriveArray(
    list(
        VarDef(ds$enjoy1 == "Very much", name = "enjoy brand 1"),
        VarDef(ds$enjoy2 == "Very much", name = "enjoy brand 2")
    ),
    "Enjoy activities with custom names"
)

# Multiple Response (selections as ids, same as ds$enjoy_mr1)
# Be careful `ids(categories(ds$enjoy1))` is not necessarily the same as
# `values(categories(ds$enjoy1))`
ds$enjoy_mr1 <- deriveArray(
    list(ds$enjoy1, ds$enjoy2),
    "Enjoy activities very much or a little v2",
    selections = c(1, 2)
)

## End(Not run)

Description

Name, alias, and description for Crunch objects

Usage

name(x)

name(x) <- value

id(x)

value(x)

value(x) <- value

description(x)

description(x) <- value

startDate(x)

startDate(x) <- value

endDate(x)

endDate(x) <- value

alias(object, ...)

alias(x) <- value

digits(x)

digits(x) <- value

uniformBasis(x)

uniformBasis(x) <- value

notes(x)

notes(x) <- value

## S4 method for signature 'AbstractCategory'
name(x)

## S4 replacement method for signature 'AbstractCategory'
name(x) <- value

## S4 replacement method for signature 'NULL'
name(x) <- value

## S4 method for signature 'AbstractCategory'
id(x)

## S4 method for signature 'Category'
value(x)

## S4 replacement method for signature 'Category'
value(x) <- value

## S4 method for signature 'Category'
dates(x)

## S4 replacement method for signature 'Category'
dates(x) <- value

## S4 method for signature 'CrunchDataset'
name(x)

## S4 replacement method for signature 'CrunchDataset'
name(x) <- value

## S4 method for signature 'CrunchDataset'
description(x)

## S4 replacement method for signature 'CrunchDataset'
description(x) <- value

## S4 method for signature 'CrunchDataset'
startDate(x)

## S4 replacement method for signature 'CrunchDataset'
startDate(x) <- value

## S4 method for signature 'CrunchDataset'
endDate(x)

## S4 replacement method for signature 'CrunchDataset'
endDate(x) <- value

## S4 method for signature 'CrunchDataset'
id(x)

## S4 method for signature 'CrunchDataset'
notes(x)

## S4 replacement method for signature 'CrunchDataset'
notes(x) <- value

## S4 replacement method for signature 'CrunchDeck'
name(x) <- value

## S4 method for signature 'CrunchDeck'
description(x)

## S4 replacement method for signature 'CrunchDeck'
description(x) <- value

## S4 method for signature 'Geodata'
description(x)

## S4 replacement method for signature 'Multitable'
name(x) <- value

## S4 replacement method for signature 'ProjectFolder'
name(x) <- value

## S4 method for signature 'ProjectFolder'
name(x)

## S4 method for signature 'ShojiObject'
name(x)

## S4 replacement method for signature 'VariableFolder'
name(x) <- value

## S4 method for signature 'VariableTuple'
alias(object)

## S4 method for signature 'VariableTuple'
description(x)

## S4 method for signature 'VariableTuple'
notes(x)

## S4 method for signature 'CrunchVariable'
name(x)

## S4 replacement method for signature 'CrunchVariable'
name(x) <- value

## S4 method for signature 'CrunchVariable'
id(x)

## S4 method for signature 'CrunchVariable'
description(x)

## S4 replacement method for signature 'CrunchVariable'
description(x) <- value

## S4 method for signature 'CrunchVariable'
alias(object)

## S4 replacement method for signature 'CrunchVariable'
alias(x) <- value

## S4 method for signature 'CrunchVariable'
notes(x)

## S4 replacement method for signature 'CrunchVariable'
notes(x) <- value

## S4 method for signature 'CrunchVariable'
digits(x)

## S4 replacement method for signature 'NumericVariable'
digits(x) <- value

## S4 replacement method for signature 'CrunchVariable'
digits(x) <- value

## S4 method for signature 'MultipleResponseVariable'
uniformBasis(x)

## S4 replacement method for signature 'MultipleResponseVariable'
uniformBasis(x) <- value

Arguments

Value

Getters return the character object in the specified slot; setters return x duly modified.

See Also

Categories describe-catalog

Description

Multiple Response variables are Categorical Arrays in which one or more categories are set as "selected". These methods allow you to view and set that attribute.

Usage

is.dichotomized(x)

dichotomize(x, i)

undichotomize(x)

is.selected(x)

is.selected(x) <- value

## S4 method for signature 'Categories'
is.dichotomized(x)

## S4 method for signature 'Categories,numeric'
dichotomize(x, i)

## S4 method for signature 'Categories,logical'
dichotomize(x, i)

## S4 method for signature 'Categories,character'
dichotomize(x, i)

## S4 method for signature 'Categories'
undichotomize(x)

## S4 method for signature 'CategoricalVariable,ANY'
dichotomize(x, i)

## S4 method for signature 'CategoricalArrayVariable,ANY'
dichotomize(x, i)

## S4 method for signature 'CategoricalVariable'
undichotomize(x)

## S4 method for signature 'CategoricalArrayVariable'
undichotomize(x)

## S4 method for signature 'Categories'
is.selected(x)

## S4 replacement method for signature 'Categories'
is.selected(x) <- value

## S4 method for signature 'Category'
is.selected(x)

## S4 replacement method for signature 'Category'
is.selected(x) <- value

Arguments

Details

dichotomize lets you specify which categories are "selected", while undichotomize strips that selection information. Dichotomize converts a Categorical Array to a Multiple Response, and undichotomize does the reverse. is.dichotomized reports whether categories have any selected values.

is.selected is lower level and maps more directly onto the "selected" attributes of categories. The best illustration of this difference is that is.selected(categories(var)) returns a logical vector, a value for each category, while is.dichotomized(categories(var)) returns a single TRUE/FALSE value.

Value

Categories or the Variable, (un)dichotomized accordingly

See Also

describe-entity

Examples

## Not run: 
ds <- newExampleDataset()
is.MR(ds$allpets)
is.dichotomized(categories(ds$allpets))
is.selected(categories(ds$allpets))
ds$allpets <- undichotomize(ds$allpets)
is.CA(ds$allpets)
ds$allpets <- dichotomize(ds$allpets, "selected")
is.MR(ds$allpets)

## End(Not run)

Description

Comparing a column or row with a baseline column or row. This calculates the z-score for the cells when comparing x to the baseline columns

Usage

compareCols(cube, ...)

compareRows(cube, ...)

compareDims(cube, dim = c("cols", "rows"), baseline, x)

Arguments

Value

the z-score for the column or row given in x

Description

Given a single baseline column compare each other row or column against this baseline. Internally this function uses compareDims() iteratively.

Usage

compareColsPairwise(cube, ...)

compareRowsPairwise(cube, ...)

compareDimsPairwise(cube, dim = c("cols", "rows"), baseline)

Arguments

Details

Warning since there is more than one comparison being made against each baseline the z-scores, and especially the p-values derived from these z-scores should be interpreted with caution. Using standard p-value cutoffs will result in anti-conservative interpretations because of the multiple comparisons problem. Adjustments to p-value cut offs (e.g. Bonferonni correction) should be used when interpreting z-scores from the ⁠compare[Rows|Cols|Dims]Pairwise()⁠ family of functions.

Value

an array of z-score for the all the columns or rows compared to baseline. The baseline column is all 0s

Description

These methods provide an array-like interface to the CrunchCube object.

Usage

dimensions(x)

dimensions(x) <- value

measures(x)

## S4 method for signature 'CubeDims'
dimnames(x)

## S4 method for signature 'CubeDims'
dim(x)

## S4 method for signature 'CubeDims'
is.na(x)

## S4 method for signature 'CrunchCube'
dimensions(x)

## S4 replacement method for signature 'CrunchCube,CubeDims'
dimensions(x) <- value

## S4 method for signature 'CrunchCube'
dim(x)

## S4 method for signature 'CrunchCube'
dimnames(x)

## S4 method for signature 'CrunchCube'
measures(x)

Arguments

Value

Generally, the same shape of result that each of these functions return when applied to an array object.

See Also

cube-computing base::array

Description

Permanently delete rows from a dataset

Usage

dropRows(dataset, expr)

Arguments

Value

dataset without the rows indicated by expr

See Also

exclusion for a non-destructive way to suppress rows

Examples

## Not run: 
ds <- dropRows(ds, ds$gender == "Male")

## End(Not run)

Description

"duplicated" method for Crunch objects

Usage

duplicated(x, incomparables = FALSE, ...)

## S4 method for signature 'CrunchVariable'
duplicated(x, incomparables = FALSE, ...)

## S4 method for signature 'CrunchExpr'
duplicated(x, incomparables = FALSE, ...)

Arguments

Value

A CrunchLogicalExpr that evaluates TRUE for all repeated entries after the first occurrence of a value.

See Also

base::duplicated()

Description

Extract the email from a User Entity

Usage

email(x)

## S4 method for signature 'UserEntity'
email(x)

Arguments

Value

a character string of the user's email

Description

crunchBox() returns a URL to the box data that it generates, but in order to view it in a CrunchBox or to embed it on a website, you'll need to translate that to the Box's public URL and wrap it in some HTML. This function takes a CrunchBox and returns the HTML which you can embed in a website.

Usage

embedCrunchBox(box, title = NULL, logo = NULL, ...)

Arguments

Value

Prints the HTML markup to the screen and also returns it invisibly.

See Also

crunchBox()

Examples

## Not run: 
box <- crunchBox(ds)
embedCrunchBox(box, logo = "//myco.example/img/logo_200px.png")

## End(Not run)

Description

Exclusion filters express logic that defines a set of rows that should be dropped from the dataset. The rows aren't permanently deleted—you can recover them at any time by removing the exclusion filter—but they are omitted from all views and calculations, as if they had been deleted.

Usage

exclusion(x)

exclusion(x) <- value

Arguments

Details

Note that exclusion filters work opposite from how "normal" filters work. That is, a regular filter expression defines the subset of rows to operate on: it says "keep these rows." An exclusion filter defines which rows to omit. Applying a filter expression as a query filter will have the opposite effect if applied as an exclusion. Indeed, applying it as both query filter and exclusion at the same time will result in 0 rows.

Value

exclusion returns a CrunchFilter if there is one, else NULL. The setter returns x with the filter set.

Description

This function allows you to write a CrunchDataset to a .csv or SPSS .sav file.

Usage

exportDataset(
  dataset,
  file,
  format = c("csv", "spss", "parquet"),
  categorical = c("name", "id"),
  na = NULL,
  varlabel = c("name", "description"),
  include.hidden = FALSE,
  ...
)

## S4 method for signature 'CrunchDataset'
write.csv(x, ...)

Arguments

Value

Invisibly, file.

Examples

## Not run: 
csv_file <- exportDataset(ds, "data.csv")
data <- read.csv(csv_file)

# parquet will likely read more quickly and be a smaller download size
parquet_file <- exportDataset(ds, "data.parquet")
# data <- arrow::read_parquet(parquet_file) # The arrow package can read parquet files

## End(Not run)

Description

Crunch decks can be exported as excel or json files.

Usage

exportDeck(deck, file, format = c("xlsx", "pptx", "json"), ...)

Arguments

Value

the filename (file, if specified, or the the autogenerated file name).

Description

Crunch Expressions, i.e. CrunchExpr and CrunchLogicalExpr, encapsulate derivations of Crunch variables, possibly composed of other functions which are only evaluated when sent to the server when creating a variable using VarDef() or using as.vector() to get data. The crunch database functions can be found in the Help Center, and can be called directly via crunchdbFunc()m but many have also been wrapped in native R functions, and are described in the details section below.

Usage

crunchdbFunc(fun, x, ...)

Arguments

Details

Logical expressions

• These logical operators ==, !=, &, |, !,%in% work the same way as their base R counterparts

• is.selected(x) return CrunchLogicalExpr whether a value is in a selected category

• rowAny(x) and rowAll(x) work row-wise on MultipleResponse Variables (and expressions), though na.rm is not implemented for all(x). ⁠%ornm%⁠ is similar to |, but where "not selected" beats "missing" (so FALSE %ornm% NA is FALSE instead of NA as it would be with FALSE | NA)

Comparisons

• Comparison operators <, <=, >, >= work the same way as their base R counterparts.

• crunchBetween(x, lower, upper, inclusive) to provide lower and upper bounds in a single expression.

Missing data expressions

• is.na(x), is.valid(x) return CrunchLogicalExpr whether a single variable (or expression that creates one) is missing (or not missing).

• rowAnyNA(x), rowAllNA(x) return CrunchLogicalExpr whether any/all values in an array variable (or expression that creates one) are missing.

• complete.cases(x) returns an expression that is "selected" if all cases are non-missing, "missing" if they are all missing, and "other" otherwise.

Selection expressions

• selectCategories(x, selections, collapse = TRUE) takes a categorical variable (or array) and marks categories as selected. selections should be a list of category names or values. If collapse is TRUE, (the default), it collapses the categories to "selected", "other" and "missing", but it is FALSE, then the old categories are preserved.

• asSelected(x) returns an expression that condenses a categorical into 3 categories ("selected", "other" or "missing")

• selectedDepth(x) returns an expression that creates a numeric variable that counts the number of selections across rows of an array variable (or expression that creates one)

• arraySelections(x) returns an expression that takes an array and creates an array with each variable condensed to "selected", "other" or "missing" and an extra subvariable "any" that indicates whether any is selected.

• alterCategoriesExpr(x, categories = NULL, category_order = NULL, subvariables = NULL) Change the category names, order, or subvariable names of categorical or Array variables (can only modify existing ones, not add or remove categories or subvariables). categories is a Categories object or a list of lists, each with a name indicating the new name, as well as an id or old_name to identify which category to modify. category_order is either a numeric vector indicating category ids or a character vector indicating the names of the categories in the order they should be displayed (note that all categories must be specified). subvariables is a list of lists, each with a name to rename the subvariable and an alias, old_nam or id to identify the subvariable. When x is an expression, all categories and subvariables must be identified by id.

Array expressions

• makeFrame(x, numeric = NULL) an expression that creates an array from existing variables or expressions, see deriveArray() for more details

• arraySubsetExpr(x, subvars, subvar_id = c("alias", "name", "id")) Take a subset of an existing array variable, identifying the subvariables by alias, name, or id (if x is an expression, you must use id).

•  alterArrayExpr(
     x,
     add = NULL,
     order = NULL,
     order_id = c("alias", "name", "id"),
     remove = NULL,
     remove_id = c("alias", "name", "id"),
     subreferences = NULL,
     subreferences_id = c("alias", "name", "id")
  )
  

  Add, reorder, remove or rename subvariables on an an array variable x. The add argument is a list of variables or expressions, optionally named with the id they should have. order and remove are vectors of aliases, names or ids (specify which with order_id/remove_id). The subreferences object is a list of lists that are named the alias, name, or id (again specify which with subreferences_id) with metadata information like name and alias in the list.

Miscellaneous expressions

• caseExpr(..., cases) Create a categorical variable from a set of logical expressions that when met are assigned to a category. See makeCaseVariable() for more details.

• bin(x) returns a column's values binned into equidistant bins.

• nchar(x) returns a numeric value indicating the length of a string (or missing reason) in a TextVariable (or expression that creates one)

• unmissing(x) for a NumericVariable (or expression that creates one) return the values of the data, ignoring the ones set to missing.

• trim(x, min, max) for a NumericVariable (or expression that creates one) return values that where all values less than min have been replaced with min and all values greater than max have been

• crunchDifftime(e1, e2, resolution) Gets the difference between two datetimes as a number with specified resolution units (one of c("Y", "Q", "M", "W", "D", "h", "m", "s", "ms")).

• datetimeFromCols(year, month, day, hours, minutes, seconds) create a Datetime variable from numeric variables or expressions (year, month, and day are required, but hours, minutes, and seconds are optional)

• rollup(x, resolution) sets the resolution of a datetime variable or expression, see resolution()

Description

Slides are composed of analyses, which are effectively CrunchCubes with some additional metadata. You can get and set a slide's Analysis Catalog with the analyses method, and access an individual analysis with analysis. There are also helpers to get and set the components of the analysis such as filter(), weight(), transforms(), displaySettings() and vizSpecs(). You can also get the CrunchCube from an analysis using cube().

Usage

filter(x, ...)

filter(x) <- value

## S4 replacement method for signature 'CrunchDeck,ANY'
weight(x) <- value

## S4 replacement method for signature 'CrunchDeck'
filter(x) <- value

## S4 replacement method for signature 'CrunchDeck,ANY'
filters(x) <- value

## S4 method for signature 'CrunchAnalysisSlide'
transforms(x)

## S4 method for signature 'AnalysisCatalog'
transforms(x)

## S4 method for signature 'Analysis'
transforms(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
transforms(x) <- value

## S4 replacement method for signature 'AnalysisCatalog,ANY'
transforms(x) <- value

## S4 replacement method for signature 'Analysis,ANY'
transforms(x) <- value

analyses(x)

analysis(x)

analysis(x) <- value

query(x) <- value

cube(x)

cubes(x)

displaySettings(x)

displaySettings(x) <- value

vizSpecs(x)

vizSpecs(x) <- value

## S4 method for signature 'CrunchSlide'
type(x)

## S4 method for signature 'CrunchAnalysisSlide'
analyses(x)

## S4 method for signature 'CrunchAnalysisSlide'
analysis(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,formula'
analysis(x) <- value

## S4 replacement method for signature 'CrunchAnalysisSlide,Analysis'
analysis(x) <- value

## S4 replacement method for signature 'CrunchAnalysisSlide,list'
analysis(x) <- value

## S4 method for signature 'CrunchAnalysisSlide'
filter(x, ...)

## S4 method for signature 'CrunchAnalysisSlide'
filters(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
filters(x) <- value

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
query(x) <- value

## S4 method for signature 'CrunchAnalysisSlide'
cubes(x)

## S4 method for signature 'CrunchAnalysisSlide'
cube(x)

## S4 method for signature 'CrunchAnalysisSlide'
displaySettings(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
displaySettings(x) <- value

## S4 method for signature 'CrunchAnalysisSlide'
vizSpecs(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
vizSpecs(x) <- value

## S4 method for signature 'AnalysisCatalog'
cubes(x)

## S4 method for signature 'AnalysisCatalog'
displaySettings(x)

## S4 replacement method for signature 'AnalysisCatalog,list'
displaySettings(x) <- value

## S4 method for signature 'AnalysisCatalog'
vizSpecs(x)

## S4 replacement method for signature 'AnalysisCatalog,list'
vizSpecs(x) <- value

## S4 replacement method for signature 'Analysis,formula'
query(x) <- value

formulaToSlideQuery(query, dataset)

## S4 method for signature 'Analysis'
cube(x)

## S4 method for signature 'Analysis'
displaySettings(x)

## S4 replacement method for signature 'Analysis,ANY'
displaySettings(x) <- value

## S4 method for signature 'Analysis'
vizSpecs(x)

## S4 replacement method for signature 'Analysis,ANY'
vizSpecs(x) <- value

## S4 method for signature 'Analysis'
filter(x, ...)

## S4 method for signature 'Analysis'
filters(x)

## S4 method for signature 'ANY'
filter(x, ...)

## S4 replacement method for signature 'CrunchAnalysisSlide'
filter(x) <- value

## S4 replacement method for signature 'Analysis'
filter(x) <- value

## S4 replacement method for signature 'Analysis,CrunchLogicalExpr'
filters(x) <- value

## S4 replacement method for signature 'Analysis,CrunchFilter'
filters(x) <- value

## S4 replacement method for signature 'Analysis,NULL'
filters(x) <- value

## S4 replacement method for signature 'Analysis,list'
filters(x) <- value

slideQueryEnv(weight, filter)

## S4 method for signature 'CrunchDeck'
cubes(x)

## S4 method for signature 'CrunchAnalysisSlide'
weight(x)

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY'
weight(x) <- value

## S4 method for signature 'Analysis'
weight(x)

Arguments

Details

For more complex objects like displaySettings(), vizSpecs() and transforms(), the API documentation provides more details.

Advanced users of the API can assign a list to ⁠analysis<-⁠ to specify settings on the analyses that are not otherwise available in rcrunch. The helpers formulaToSlideQuery() and slideQueryEnv() help you create objects for the query and query_environment.

Examples

## Not run: 
# Examples of setting analysis details (in general these setters work on
# the slide, analysis catalog and analysis, but for brevity the examples only
# show on the slide)

# Change the filter
filters(slide) <- NULL # to remove a filter
filters(slide) <- filters(ds)[["My filter"]]
filters(slide) <- list( # Can set multiple filter
    filters(ds)[["My filter"]],
    ds$age_grp == "18-35"
)
filters(deck) <- filters(ds)[["My filter"]] # Can set the same filter on a whole deck too

# Change the weight
weight(slide) <- NULL # to remove
weight(slide) <- ds$weight
weight(deck) <- ds$weight # Can set the same weight on a whole deck too

# Change the transforms
transforms(slide) <- list(rows_dimension = makeDimTransform(hide = "Neutral"))

# Change the displaySettings
displaySettings(slide) <- list(vizType = "groupedBarPlot")

# Change the vizSpecs
# viz_specs can get quite long, see
# https://crunch.io/api/reference/#post-/datasets/-dataset_id-/decks/-deck_id-/slides/
vizSpecs(slide) <- viz_specs

# Change the query
#' query(slide) <- ~ cyl + wt

## End(Not run)

Description

You can build and save filters in the Crunch web app, and these filters are stored in a FilterCatalog. This function allows you to retrieve and modify those filters.

Usage

filters(x)

filters(x) <- value

## S4 method for signature 'CrunchDataset'
filters(x)

## S4 replacement method for signature 'CrunchDataset,ANY'
filters(x) <- value

Arguments

Value

an object of class FilterCatalog containing references to Filter entities usable in the web application. (Setter returns the Dataset.)

Description

Sometimes it is useful to group subvariables across arrays in order to compare them more easily. This function generates a set of derived views of common subvariables across arrays. Because they are derived, they share data with the underlying array variables, and they are thus automatically updated when new data is appended.

Usage

flipArrays(variables, suffix = ", flipped")

Arguments

Value

A list of derived VariableDefinitions, one per unique subvariable name across all variables. Each variable in variables that contains this subvariable will appear as a subvariable in these new derived array definitions. Use addVariables to add these to your dataset.

Examples

## Not run: 
ds <- addVariables(ds, flipArrays(ds[c("petloc", "petloc2")], suffix = ", rearranged"))

## End(Not run)

Description

Find and move entities to a new folder

Usage

folder(x)

folder(x) <- value

Arguments

Value

folder returns the parent folder of x, or NULL if the x is the root level. ⁠folder<-⁠ returns the x input, having been moved to the requested location.

See Also

mv() cd()

Examples

## Not run: 
ds <- loadDataset("Example survey")
folder(ds$income) <- "Demographics/Economic"
folder(ds$income)
## [1] "Demographics"    "Economic"

## End(Not run)

Description

Variables catalogs are generally loaded lazily, but this function allows you to force them to be loaded once.

Usage

forceVariableCatalog(x)

Arguments

Details

The forceVariableCatalog() function is probably most useful when writing tests because it allows you to be more certain about when API calls are made.

Another situation where you may care about when API calls for loading the variables are made is when you are loading many datasets at the same time (~15+) and referring to their variables later. In this situation, it can be faster to turn off the variables catalog with the option crunch.lazy.variable.catalog because there is a limit to the number of datasets your user can hold open at the same time and so at some point the server will have to unload and then reload the datasets. However, it's probably even faster if you are able to alter your code so that it operates on datasets sequentially.

Value

A dataset with it's variable catalogs filled in

Description

Forking a dataset makes a copy of the data that is linked by Crunch's version control system to the original dataset. When you make edits to a fork, users of the original dataset do not see the changes.

Usage

forkDataset(dataset, name = defaultForkName(dataset), draft = FALSE, ...)

Arguments

Details

A common strategy for revising a dataset that has been shared with others is to fork it, make changes to the fork, and then merge those changes back into the original dataset. This workflow allows you to edit a dataset and review changes before publishing them, so that you don't accidentally send your clients incorrect data. For more on this workflow, see vignette("fork-and-merge", package = "crunch").

Value

The new fork, a CrunchDataset.

See Also

mergeFork()

Description

Teams contain a list of users. You can grant access to a group of users by inviting the team. You can also share a set of datasets with a user all at once by adding the user to a team that contains those datasets.

Usage

getTeams()

Details

getTeams() returns your TeamCatalog. You can extract an individual team by name, or create a team by assigning into the function. To create a team by assignment, assign a list to teams("myteam") <- value_list. The value_list can either empty (to just create a team with that name), or can contain a "members" element with the emails or URLs of users to add to the team. Users can be also be added later with the ⁠members<-⁠ method.

Value

A TeamCatalog. Extract an individual team by name. Create a team by assigning in with a new name.

See Also

members

Description

These methods let you communicate with the Crunch API, for more background see Crunch Internals.

Usage

crGET(url, config = list(), ...)

crPUT(url, config = list(), ..., body)

crPATCH(url, config = list(), ..., body)

crPOST(url, config = list(), ..., body)

crDELETE(url, config = list(), ...)

Arguments

Value

Depends on the response status of the HTTP request and any custom handlers.

Description

The core of Catalog data is in its "index". These methods get and set that slot.

Usage

index(x)

index(x) <- value

## S4 method for signature 'ShojiCatalog'
index(x)

## S4 replacement method for signature 'ShojiCatalog'
index(x) <- value

Arguments

Value

Getters return the list object in the "index" slot; setters return x duly modified.

Description

Index tables are percentages of percentages. They take the percentage from prop.table(cube, margin) and, by default, divide that by the proportions of the other margin. The baseline argument can be used to provide baseline proportions to compare against.

Usage

index.table(x, margin, baseline)

Arguments

Details

index.table() is only implemented for 2 dimensional cubes. If you need to calculate indexes for a higher dimension Cube, please slice the cube first.

Value

an array of percentages indexed to the margin provided

Examples

## Not run: 
cube_object
#    v7
# v4  C E
#   B 5 2
#   C 5 3
index.table(cube_object, 1)
#    v7
# v4         C         E
#   B 107.1429  85.71429
#   C  93.7500 112.50000
index.table(cube_object, 2)
#    v7
# v4    C   E
#   B 100  80
#   C 100 120
index.table(cube_object, 2, c(0.6, 0.4))
#    v7
# v4          C         E
#   B  83.33333  66.66667
#   C 125.00000 150.00000

## End(Not run)

Description

Insertions allow you to insert new categories into a categorical-like response on a variable's transformations.

Usage

Insertions(..., data = NULL)

Insertion(...)

.Insertion(..., data = NULL)

anchor(x, ...)

anchors(x)

anchor(x) <- value

arguments(x, ...)

arguments(x) <- value

func(x)

funcs(x)

## S4 replacement method for signature 'Insertion'
anchor(x) <- value

## S4 replacement method for signature 'Subtotal'
anchor(x) <- value

## S4 replacement method for signature 'Heading'
anchor(x) <- value

## S4 replacement method for signature 'SummaryStat'
anchor(x) <- value

## S4 replacement method for signature 'Insertion,ANY'
subtotals(x) <- value

## S4 replacement method for signature 'Insertion'
arguments(x) <- value

## S4 replacement method for signature 'Subtotal'
arguments(x) <- value

## S4 replacement method for signature 'Heading'
arguments(x) <- value

## S4 replacement method for signature 'SummaryStat'
arguments(x) <- value

## S4 method for signature 'Insertion'
arguments(x)

## S4 method for signature 'Subtotal'
arguments(x, var_items)

## S4 method for signature 'Heading'
arguments(x)

## S4 method for signature 'SummaryStat'
arguments(x, var_items)

## S4 method for signature 'Insertion'
anchor(x, ...)

## S4 method for signature 'Subtotal'
anchor(x, var_items)

## S4 method for signature 'Heading'
anchor(x, var_items)

## S4 method for signature 'SummaryStat'
anchor(x, var_items)

## S4 method for signature 'Insertion'
func(x)

## S4 method for signature 'Subtotal'
func(x)

## S4 method for signature 'Heading'
func(x)

## S4 method for signature 'SummaryStat'
func(x)

## S4 method for signature 'Insertions'
anchors(x)

## S4 method for signature 'Insertions'
funcs(x)

Arguments

Working with Insertions

Insertions are used to add information about a variable or CrunchCube that extends the data in the dataset but does not alter it. This new data includes: aggregations like subtotals that sum the count of more than on category together or headings which can be added between categories.

Insertions objects are containers for individual Insertion objects. The individual Insertions contain all the information needed to calculate, apply, and display insertions to CrunchCubes and categorical variables.

An Insertion must have two properties:

• anchor - which is the id of the category the insertion should follow

• name - the string to display

Additionally, Insertions may also have the following two properties (though if they have one, they must have the other):

• function - the function to use to aggregate (e.g. "subtotal")

• args - the category ids to use as operands to the function above.

Although it is possible to make both subtotals and headings using Insertion alone, it is much easier and safer to use the functions Subtotal() and Heading() instead. Not only are they more transparent, they also are quicker to type, accept both category names as well as ids, and have easier to remember argument names.

Description

interactVariables takes two or more variables and creates a new one that is the cartesian product expansion of their unique values. For example, if we cross ethnicity (with 2 categories) and race (with 4 categories), the new variable would have 8 valid categories (e.g. black:hispanic, white:hispanic, black:non-hispanic, etc.) and 7 categories where at least one of the variables is missing (e.g. white:No Data).

Usage

interactVariables(..., name, collapse_missings = FALSE)

Arguments

Value

A VariableDefinition that creates the new interaction variable.

Examples

## Not run: 
ds$ethn_race <- interactVariables(
  ds$ethnicity, ds$race, name = "Interaction of ethnicity and race"
)

## End(Not run)

Description

Crunch categorical variables allow you to set multiple categories as missing. For instance, you might have "not answered" and "doesn't know" both coded as missing. This function returns a logical vector of all dataset entries that fall into any of the missing categories. It also allows you to append additional categories to the list of missing categories using the setter.

Usage

## S4 method for signature 'Categories'
is.na(x)

## S4 replacement method for signature 'Categories,character'
is.na(x) <- value

## S4 replacement method for signature 'Categories,logical'
is.na(x) <- value

## S4 method for signature 'Category'
is.na(x)

## S4 replacement method for signature 'Category,logical'
is.na(x) <- value

Arguments

Value

Getters return logical, a named vector in the case of the Categories method; setters return x duly modified.

Description

View and modify whether all dataset viewers have access to the dataset. This will return FALSE if the dataset is in draft.

Usage

is.public(x)

is.public(x) <- value

## S4 method for signature 'CrunchFilter'
is.public(x)

## S4 replacement method for signature 'CrunchFilter'
is.public(x) <- value

## S4 method for signature 'CrunchDeck'
is.public(x)

## S4 replacement method for signature 'CrunchDeck'
is.public(x) <- value

## S4 method for signature 'MultitableCatalog'
is.public(x)

## S4 replacement method for signature 'MultitableCatalog'
is.public(x) <- value

## S4 method for signature 'Multitable'
is.public(x)

## S4 replacement method for signature 'Multitable'
is.public(x) <- value

Arguments

Value

For is.public, a logical value for whether the object is flagged as shared with all dataset viewers. (Its setter thus takes a logical value as well.) Catalogs of datasets return a vector of logicals corresponding to the length of the catalog, while entities return a single value.

Description

Read and set edit privileges

Usage

is.editor(x)

is.editor(x) <- value

## S4 method for signature 'MemberCatalog'
is.editor(x)

## S4 replacement method for signature 'MemberCatalog,logical'
is.editor(x) <- value

## S4 method for signature 'PermissionCatalog'
is.editor(x)

## S4 method for signature 'PermissionTuple'
is.editor(x)

Arguments

Value

is.editor returns a logical vector corresponding to whether the users in the catalog can edit or not.⁠is.editor<-⁠ returns the catalog, modified.

Description

Test whether a Crunch object belongs to a class

Usage

is.VariableDefinition(x)

is.VarDef(x)

is.script(x)

is.dataset(x)

is.CrunchExpr(x)

is.Expr(x)

is.Geodata(x)

is.shoji(x)

is.variable(x)

is.Numeric(x)

is.Categorical(x)

is.Text(x)

is.Datetime(x)

is.Multiple(x)

is.MR(x)

is.MultipleResponse(x)

is.CA(x)

is.CategoricalArray(x)

is.NumericArray(x)

is.Array(x)

Arguments

Value

logical

Description

weight lets you view and set your user's currently applied weight on the server. weightVariables lets you view all of the variables that have been designated as valid to use as weights.

Usage

is.weight(x) <- value

weight(x)

weight(x) <- value

## S4 replacement method for signature 'Analysis,CrunchVariable'
weight(x) <- value

## S4 replacement method for signature 'Analysis,NULL'
weight(x) <- value

## S4 method for signature 'CrunchDataset'
weight(x)

## S4 replacement method for signature 'CrunchDataset,ANY'
weight(x) <- value

is.weight(x)

## S4 replacement method for signature 'NumericVariable'
is.weight(x) <- value

Arguments

Value

For the weight getter, a Variable if there is a weight, else NULL. For the setter, x, modified accordingly. weightVariables returns the aliases (or names, according to options(crunch.namekey.dataset)), of the variables designated as weights.

See Also

weightVariables() makeWeight()

Description

As base::merge() does for data.frames, this function takes two datasets, matches rows based on a specified key variable, and adds columns from one to the other.

Usage

joinDatasets(
  x,
  y,
  by = intersect(names(x), names(y)),
  by.x = by,
  by.y = by,
  all = FALSE,
  all.x = TRUE,
  all.y = FALSE,
  copy = TRUE
)

extendDataset(
  x,
  y,
  by = intersect(names(x), names(y)),
  by.x = by,
  by.y = by,
  all = FALSE,
  all.x = TRUE,
  all.y = FALSE,
  ...
)

## S3 method for class 'CrunchDataset'
merge(
  x,
  y,
  by = intersect(names(x), names(y)),
  by.x = by,
  by.y = by,
  all = FALSE,
  all.x = TRUE,
  all.y = FALSE,
  ...
)

Arguments

Details

Since joining two datasets can sometimes produce unexpected results if the keys differ between the two datasets, you may want to follow the fork-edit-merge workflow for this operation. To do this, fork the dataset with forkDataset(), join the new data to the fork, ensure that the resulting dataset is correct, and merge it back to the original dataset with mergeFork(). For more, see vignette("fork-and-merge", package = "crunch").

Value

x extended by the columns of y, matched on the "by" variables.

Description

listDatasets() is a convenience function for quickly seeing what datasets are in a project. It is equivalent to names(datasets(proj)), with some additional optional arguments.

Usage

listDatasets(
  kind = c("active", "all", "archived"),
  project = NULL,
  refresh = FALSE,
  shiny = FALSE
)

Arguments

Details

Specifying listDatasets(shiny = TRUE) will, instead of printing dataset names, load a Shiny gadget that provides a GUI for navigating the project tree to find a dataset, if you're running in RStudio.

Value

A character vector of dataset names, each of which would be a valid input for loadDataset()

Description

This function gives you a Dataset object, which refers to a dataset hosted on the Crunch platform. With this Dataset, you can perform lots of data cleaning and analysis as if the dataset were fully resident on your computer, without having to pull data locally.

Usage

loadDataset(
  dataset,
  kind = c("active", "all", "archived"),
  project = NULL,
  refresh = FALSE
)

Arguments