crunch: Crunch.io Data Tools

Description

The Crunch.io service https://crunch.io/ provides a cloud-based data store and analytic engine, as well as an intuitive web interface. Using this package, analysts can interact with and manipulate Crunch datasets from within R. Importantly, this allows technical researchers to collaborate naturally with team members, managers, and clients who prefer a point-and-click interface.

Author(s)

Maintainer: Greg Freedman Ellis greg@crunch.io

Authors:

• Jonathan Keane jkeane@gmail.com

• Mike Malecki mike@crunch.io

• Neal Richardson neal.p.richardson@gmail.com

• Gordon Shotwell gordon.shotwell@gmail.com

• Aljaž Sluga aljaz.sluga@crunch.io

See Also

Useful links:

• https://crunch.io/r/crunch/

• https://github.com/Crunch-io/rcrunch

• Report bugs at https://github.com/Crunch-io/rcrunch/issues

Abstract categories

Description

An abstract class that categories, elements, insertions, etc. fall under

Usage

AbstractCategories(..., data = NULL)

AbstractCategory(..., data = NULL)

Arguments

Categories in CategoricalVariables

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)

Context managers

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

CrunchDataFrame

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.

Crunch Datasets

Description

Crunch Datasets

Geography properties for crunch variables

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)

Variables in Crunch

Description

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

Slots

filter

either NULL or CrunchLogicalExpr

tuple

VariableTuple

Organize Datasets

Description

A DatasetOrder object is a subclass of list that contains DatasetGroups. DatasetGroup objects contain a group name and an set of "entities", which can be dataset references or other nested DatasetGroups.

Details

This API is deprecated. Use folders instead.

Slots

group

character, the name of the DatasetGroup. In the constructor and more generally, this field can be referenced as "name" as well.

entities

a character vector of dataset URLs, or a list containing a combination of dataset URLs and DatasetGroup objects.

Insert categories in transformations

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.

Schema for the 2017 Stack Overflow developer survey

Description

Survey questions and variable names for the 2017 Stack Overflow Developers Survey #'

Usage

SO_schema

Format

A data frame with 23 rows and 2 variables.

Column

The column name of the survey data frame

Question

Question asked of respondents

R users who responded to the 2017 Stack Overflow developer survey

Description

A slightly modified version of the 2017 Stack Overflow developer survey. The dataset is filtered to only include respondents who have used R before, and to include illustrative variable types.

Usage

SO_survey

Format

A data frame with 1634 rows and 25 variables.

Respondent

Respondent ID number

Professional

Which of the following best describes you?

Country

In which country do you currently live?

CompanySize

In terms of the number of employees, how large is the company or organization you work for?

CareerSatisfaction

Career satisfaction rating

JobSatisfaction

Job satisfaction rating

ImportantHiringAlgorithms

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Knowledge of algorithms and data structures

ImportantHiringTechExp

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Experience with specific tools (libraries, frameworks, etc.) used by the employer

ImportantHiringCommunication

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Communication skills

ImportantHiringOpenSource

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Contributions to open source projects

ImportantHiringPMExp

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Experience with specific project management tools & techniques

ImportantHiringCompanies

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Previous companies worked at

ImportantHiringTitles

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Previous job titles held

ImportantHiringEducation

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Educational credentials (e.g. schools attended, specific field of study, grades earned)

ImportantHiringRep

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Stack Overflow reputation

ImportantHiringGettingThingsDone

Congratulations! You've just been put in charge of technical recruiting at Globex, a multinational high- tech firm. This job comes with a corner office, and you have an experienced staff of recruiters at your disposal. They want to know what they should prioritize when recruiting software developers. How important should each of the following be in Globex's hiring process? Track record of getting things done

Gender

Which of the following do you currently identify as?

Race

Which of the following do you identify as?

Salary

What is your current annual base salary, before taxes, and excluding bonuses, grants, or other compensation?

ExpectedSalary

You said before that you are currently learning how to program. When you have completed your studies, what annual salary do you expect to earn in your first job after graduation?

TabsSpaces

Tabs or spaces?

WantWorkLanguage

Which of the following languages have you done extensive development work in over the past year, and which do you want to work in over the next year?

HaveWorkedLanguage

Which of the following languages have you done extensive development work in over the past year, and which do you want to work in over the next year?

Source

https://survey.stackoverflow.co

Mix-in class for multiple inheritance of variables and datasets.

Description

Exists for common methods in interacting with Crunch API only. Has no Extract methods declared so as not to conflict with the vector/list/data.frame methods jointly inherited in CrunchVariable and CrunchDataset.

Manipulate VariableGroup and VariableOrder

Description

Manipulate VariableGroup and VariableOrder

Usage

## S4 method for signature 'OrderGroup'
entities(x, simplify = FALSE)

## S4 method for signature 'ShojiOrder'
entities(x, simplify = FALSE)

## S4 method for signature 'list'
entities(x, simplify = FALSE)

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

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

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

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

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

Arguments

Value

• entities returns Variable references and VariableGroups;

• names returns group names;

See Also

VariableOrder grouped

Subtotals and headings

Description

Subtotals and headings for Categorical Variables and Multiple Response Variables. These are especially useful for making aggregates across multiple categories (sometimes referred to as nets, top box, or top 2 box).

Subtotals and headings for Categorical Variables and Multiple Response Variables. These are especially useful for making aggregates across multiple categories (sometimes referred to as nets, top box, or top 2 box).

Usage

Subtotal(
  name,
  categories = NULL,
  position = c("relative", "top", "bottom"),
  after = NULL,
  before = NULL,
  negative = NULL,
  na.rm = TRUE,
  variable = NULL,
  id = NULL,
  alias = NULL
)

Heading(name, position = c("relative", "top", "bottom"), after = NULL)

subtotals(x)

subtotals(x) <- value

Subtotal(
  name,
  categories = NULL,
  position = c("relative", "top", "bottom"),
  after = NULL,
  before = NULL,
  negative = NULL,
  na.rm = TRUE,
  variable = NULL,
  id = NULL,
  alias = NULL
)

is.Subtotal(x)

is.Heading(x)

are.Subtotals(x)

are.Headings(x)

Heading(name, position = c("relative", "top", "bottom"), after = NULL)

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

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

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

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

Subtotal(
  name,
  categories = NULL,
  position = c("relative", "top", "bottom"),
  after = NULL,
  before = NULL,
  negative = NULL,
  na.rm = TRUE,
  variable = NULL,
  id = NULL,
  alias = NULL
)

is.Subtotal(x)

is.Heading(x)

are.Subtotals(x)

are.Headings(x)

Heading(name, position = c("relative", "top", "bottom"), after = NULL)

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

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

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

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

Arguments

Details

To see the subtotals or headings set for a variable, use subtotals(variable)

To see the subtotals or headings set for a variable, use subtotals(variable)

Adding Subtotals and Headings

Subtotals and headings can be added either by passing a list of Subtotals or Headings, or they can be added one at a time by passing Subtotal or Heading to subtotals(variable) alone.

Adding subtotals or headings is additive; meaning that subtotals or headings that are already set on the variable are not removed when new subtotals or headings are added. To remove all subtotals and headings, set subtotals(variable) to NULL.

To get an array of just the subtotal rows from a CrunchCube, use the function subtotalArray(CrunchCube).

Subtotals and headings can be added either by passing a list of Subtotals or Headings, or they can be added one at a time by passing Subtotal or Heading to subtotals(variable) alone.

Adding subtotals or headings is additive; meaning that subtotals or headings that are already set on the variable are not removed when new subtotals or headings are added. To remove all subtotals and headings, set subtotals(variable) to NULL.

To get an array of just the subtotal rows from a CrunchCube, use the function subtotalArray(CrunchCube).

Working with Subtotals and headings

When interacting programmatically with Subtotals and Headings, it can be useful to be able to tell if something is a Subtotal or a Heading. The ⁠is.*⁠ family of methods are useful here: the singular versions (is.Subtotal and is.Heading) take a single object and returns TRUE if the object is either a Subtotal or a Heading and FALSE if not; the plural versions (are.Subtotals and are.Headings) take a list of objects (including an Insertions object) and returns a vector of TRUE/FALSEs.

When interacting programmatically with Subtotals and Headings, it can be useful to be able to tell if something is a Subtotal or a Heading. The ⁠is.*⁠ family of methods are useful here: the singular versions (is.Subtotal and is.Heading) take a single object and returns TRUE if the object is either a Subtotal or a Heading and FALSE if not; the plural versions (are.Subtotals and are.Headings) take a list of objects (including an Insertions object) and returns a vector of TRUE/FALSEs.

Removing transforms

noTransforms() is useful if you don't want to see or use any transformations like Subtotals and Headings. This action only applies to the CrunchCube object in R: it doesn't actually change the variables on Crunch servers or the query that generated the CrunchCube.

noTransforms() is useful if you don't want to see or use any transformations like Subtotals and Headings. This action only applies to the CrunchCube object in R: it doesn't actually change the variables on Crunch servers or the query that generated the CrunchCube.

Examples

## Not run: 
# given a variable ds$opinion, with categories: Strongly Agree, Somewhat
# Agree, Neither Agree nor Disagree, Somewhat Disagree, and Strongly Disagree,
# to make two subtotals for Agree and Disagree:
subtotals(ds$opinion) <- list(
    Subtotal(
        name = "Agree",
        categories = c("Strongly Agree", "Somewhat Agree"),
        after = "Somewhat Agree"
    ),
    Subtotal(
        name = "Disagree",
        categories = c("Strongly Disagree", "Somewhat Disagree"),
        after = "Strongly Disagree"
    )
)

# headings can also be added:
subtotals(ds$opinion) <- Heading(name = "All opinions", position = "top")

# to see the subtotals and headings associated with a variable
subtotals(ds$opinion)
#        anchor         name     func    args
# 1      2        Agree subtotal 1 and 2
# 2      4     Disagree subtotal 4 and 5
# 3      0 All opinions     <NA>      NA

# when you use a variable with subtotals and headings in a cube, you see them
# by default
opinion_cube <- crtabs(~opinion, ds)
opinion_cube
#               All opinions
#             Strongly Agree 23
#             Somewhat Agree 24
#                      Agree 47
# Neither Agree nor Disagree 18
#          Somewhat Disagree 16
#          Strongly Disagree 19
#                   Disagree 35


# to get just the subtotals,
subtotalArray(opinion_cube)
#    Agree Disagree
#       47       35

# to remove all subtotals and headings
subtotals(ds$opinion) <- NULL
crtabs(~opinion, ds)
#             Strongly Agree 23
#             Somewhat Agree 24
# Neither Agree nor Disagree 18
#          Somewhat Disagree 16
#          Strongly Disagree 19

# if you want to temporarily remove subtotals and headings, you can with `noTransforms`
noTransforms(crtabs(~opinion, ds))
#             Strongly Agree             Somewhat Agree Neither Agree nor Disagree
#                         23                         24                         18
#          Somewhat Disagree          Strongly Disagree
#                         16                         19

## End(Not run)

## Not run: 
# given a variable ds$opinion, with categories: Strongly Agree, Somewhat
# Agree, Neither Agree nor Disagree, Somewhat Disagree, and Strongly Disagree,
# to make two subtotals for Agree and Disagree:
subtotals(ds$opinion) <- list(
    Subtotal(
        name = "Agree",
        categories = c("Strongly Agree", "Somewhat Agree"),
        after = "Somewhat Agree"
    ),
    Subtotal(
        name = "Disagree",
        categories = c("Strongly Disagree", "Somewhat Disagree"),
        after = "Strongly Disagree"
    )
)

# headings can also be added:
subtotals(ds$opinion) <- Heading(name = "All opinions", position = "top")

# to see the subtotals and headings associated with a variable
subtotals(ds$opinion)
#        anchor         name     func    args
# 1      2        Agree subtotal 1 and 2
# 2      4     Disagree subtotal 4 and 5
# 3      0 All opinions     <NA>      NA

# when you use a variable with subtotals and headings in a cube, you see them
# by default
opinion_cube <- crtabs(~opinion, ds)
opinion_cube
#               All opinions
#             Strongly Agree 23
#             Somewhat Agree 24
#                      Agree 47
# Neither Agree nor Disagree 18
#          Somewhat Disagree 16
#          Strongly Disagree 19
#                   Disagree 35


# to get just the subtotals,
subtotalArray(opinion_cube)
#    Agree Disagree
#       47       35

# to remove all subtotals and headings
subtotals(ds$opinion) <- NULL
crtabs(~opinion, ds)
#             Strongly Agree 23
#             Somewhat Agree 24
# Neither Agree nor Disagree 18
#          Somewhat Disagree 16
#          Strongly Disagree 19

# if you want to temporarily remove subtotals and headings, you can with `noTransforms`
noTransforms(crtabs(~opinion, ds))
#             Strongly Agree             Somewhat Agree Neither Agree nor Disagree
#                         23                         24                         18
#          Somewhat Disagree          Strongly Disagree
#                         16                         19

## End(Not run)

Subvariables in Array Variables

Description

Multiple-response and categorical-array variables are higher order variables which are made up of sets of subvariables. These methods allow you to retrieve and change the subvariables of a multiple-response or categorical-array variable.

Usage

subvariables(x)

subvariables(x) <- value

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

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

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

## S4 replacement method for signature 'ArrayVariable,ANY'
subvariables(x) <- value

## S4 replacement method for signature 'ArrayVariable,Subvariables'
subvariables(x) <- value

Arguments

Details

Subvariables can be accessed from array variables (including multiple response) with the subvariables method. They can be assigned back with the ⁠subvariables<-⁠ setter, but there are limitations to what is supported. Specifically, you can reorder subvariables, but you cannot add or remove subvariables by ⁠subvariables<-⁠ assignment. See deleteSubvariable to remove subvariables from an array.

Subvariables have a names attribute that can be accessed, showing the display names of the subvariables. These can be set with the ⁠names<-⁠ method.

Finally, subvariables can be accessed as regular (categorical) variables with the $ and [[ extract methods.

See the vignette on array variables for further details and examples.

See Also

describe-catalog deleteSubvariable vignette("array-variables", package="crunch")

Summary insertions

Description

Just like subtotals()s, summary statistics can be inserted into cubes. SummaryStat() makes an object of type SummaryStat which can be added on to a CrunchCube's insertions to add the specified summary statistic. Currently only mean and median are supported; both use weighted algorithms to go from counts and numeric values of categories to the expected statistic. Although SummaryStat objects can be made by hand, it is recommended instead to use the addSummaryStat() function which is much quicker and easier to simply add a summary statistic to an existing CrunchCube.

Usage

SummaryStat(
  name,
  stat,
  categories = NULL,
  position = c("relative", "top", "bottom"),
  after = NULL,
  before = NULL,
  includeNA = FALSE
)

SummaryStat(
  name,
  stat,
  categories = NULL,
  position = c("relative", "top", "bottom"),
  after = NULL,
  before = NULL,
  includeNA = FALSE
)

is.SummaryStat(x)

are.SummaryStats(x)

Arguments

Details

Summary statistics are intended only for CrunchCube objects, and are not able to be set on Crunch variables.

Removing transforms

noTransforms() is useful if you don't want to see or use any transformations like Subtotals and Headings. This action only applies to the CrunchCube object in R: it doesn't actually change the variables on Crunch servers or the query that generated the CrunchCube.

Transformations of variable and cube views

Description

Transformations allow you to change how a variable or cube is displayed without changing the underlying data.

Usage

Transforms(..., data = NULL)

TransformsList(..., data = NULL)

transforms(x)

transforms(x) <- value

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

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

## S4 replacement method for signature 'CrunchVariable,Transforms'
transforms(x) <- value

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

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

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

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

## S4 replacement method for signature 'CrunchCube,TransformsList'
transforms(x) <- value

## S4 replacement method for signature 'CrunchCube,NULL'
transforms(x) <- value

Arguments

Getting transformations

The transforms(x) methods can be used with Variables and CrunchCubes to get what transformations are currently set. For variables, they return a single Transforms object that includes all transformations for the variable. For CrunchCubes, it returns a named list with the same length as the number of dimensions of the cube with each dimension's transformations.

Currently, Insertions (e.g. Subtotal() and Heading()) are the only type of transformations that are supported.

Setting transformations on a variable

The transforms(x) <- value methods can be used to assign transformations for a specific variable. value must be a Transforms object. This allows you to set transformations on categorical variables. These transformations will automatically show up in any new CrunchCubes that contain this variable.

Setting transformations on a CrunchCube

The transforms(x) <- value methods can also be used to assign transformations to a CrunchCube that has already been calculated. value must be a named list of Transforms objects. The names of this list must correspond to dimensions in the cube (those dimensions correspondences are matched based on variable aliases). You don't have to provide an entry for each dimension, but any dimension you do provide will be overwritten fully.

Removing transformations

To remove transformations from a variable or CrunchCube, use transforms(x) <- NULL.

Collection of Variables within a Dataset

Description

A VariableCatalog contains references to all variables in a dataset, plus some descriptive metadata about each. Each VariableCatalog also contains a VariableOrder that governs how variables within it are organized.

Construct a variable definition

Description

Crunch variables are created by posting a VariableDefinition to the Crunch server. The VariableDefinition contains the information the server requires to calculate the variable. This can information can either be in the form of the actual data which you would like to include in the variable, or a derivation which tells the server how to derive the new variable from existing ones. This function converts an R vector or set of attributes into a variable definition which can be posted to the server.

Usage

VariableDefinition(data, ...)

VarDef(data, ...)

Arguments

Value

a VariableDefinition object, ready to POST to Crunch.

See Also

toVariable

Examples

VariableDefinition(rnorm(5),
    name = "Some numbers",
    description = "Generated pseudorandomly from the normal distribution"
)
VarDef(
    name = "Integers", values = 1:5, type = "numeric",
    description = "When creating variable definitions with 'values', you must
    specify 'type', and categorical variables will require 'categories'."
)

Organize Variables within a Dataset

Description

Variables in the Crunch web application can be viewed in an ordered, hierarchical list. These objects and methods allow you to modify that order from R.

Details

A VariableOrder object is a subclass of list that contains VariableGroups. VariableGroup objects contain a group name and an set of "entities", which can be variable references or other nested VariableGroups.

Slots

group

character, the name of the VariableGroup. In the constructor and more generally, this field can be referenced as "name" as well.

entities

a character vector of variable URLs, or a list containing a combination of variable URLs and VariableGroup objects.

duplicates

logical: should duplicate variable references be allowed in this object? Deprecated field: duplicates are never allowed.

vars

either NULL or a VariableCatalog(). If not NULL, it will be used to look up variable names from the URLs.

Add geodata metadata to a crunch variable

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)

Add subvariable to an array

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)

Add summary statistics to a CrunchCube

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)

Add multiple variables to a dataset

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)

Get and set names, aliases on Catalog-type objects

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")

Append one Crunch dataset to another

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", project = "client 1")
new_wave <- loadDataset("Survey, 2017", project = "client 1")
ds <- appendDataset(ds, new_wave)

## End(Not run)

Manually trigger a pending append to a dataset

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.

apply a function against a dimension

Description

Similar to other apply functions, this takes an array and applies the function against the dimensions (specified in the MARGIN argument). These dimensions must be a single number (unlike many apply functions). See the examples below, where we use the function add_one_hundred to add 100 on to the end of each MARGIN.

Usage

applyAgainst(X, MARGIN, FUN, ...)

Arguments

Details

FUN can be any function that takes a vector and returns a vector, but one common use case is a function that adds new entries to the vector, effectively expanding the array in the dimension given.

Value

an array with the function applied

Examples

array <- array(c(1:24), dim = c(4, 3, 2))
array
# , , 1
#
#      [,1] [,2] [,3]
# [1,]    1    5    9
# [2,]    2    6   10
# [3,]    3    7   11
# [4,]    4    8   12
#
# , , 2
#
#      [,1] [,2] [,3]
# [1,]   13   17   21
# [2,]   14   18   22
# [3,]   15   19   23
# [4,]   16   20   24

add_one_hundred <- function(x) c(x, 100)

crunch:::applyAgainst(array, 1, add_one_hundred)
# , , 1
#
#      [,1] [,2] [,3]
# [1,]    1    5    9
# [2,]    2    6   10
# [3,]    3    7   11
# [4,]    4    8   12
# [5,]  100  100  100
#
# , , 2
#
#      [,1] [,2] [,3]
# [1,]   13   17   21
# [2,]   14   18   22
# [3,]   15   19   23
# [4,]   16   20   24
# [5,]  100  100  100

crunch:::applyAgainst(array, 2, add_one_hundred)
# , , 1
#
#      [,1] [,2] [,3] [,4]
# [1,]    1    5    9  100
# [2,]    2    6   10  100
# [3,]    3    7   11  100
# [4,]    4    8   12  100
#
# , , 2
#
#      [,1] [,2] [,3] [,4]
# [1,]   13   17   21  100
# [2,]   14   18   22  100
# [3,]   15   19   23  100
# [4,]   16   20   24  100

crunch:::applyAgainst(array, 3, add_one_hundred)
# , , 1
#
#      [,1] [,2] [,3]
# [1,]    1    5    9
# [2,]    2    6   10
# [3,]    3    7   11
# [4,]    4    8   12
#
# , , 2
#
#      [,1] [,2] [,3]
# [1,]   13   17   21
# [2,]   14   18   22
# [3,]   15   19   23
# [4,]   16   20   24
#
# , , 3
#
#      [,1] [,2] [,3]
# [1,]  100  100  100
# [2,]  100  100  100
# [3,]  100  100  100
# [4,]  100  100  100

Get and set "archived" and "published" status of a dataset

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", project = "current")
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)

Convert Variables to local R objects

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.

as.* methods for variables

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)

as.environment method for CrunchDataset

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.

Undo behavior of a Crunch Automation Script

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

Get the property features for available geographies

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

See the appended batches of this dataset

Description

See the appended batches of this dataset

Usage

batches(x)

Arguments

Value

a BatchCatalog

Build Regex to find delimited items.

Description

A delimited item maple can appear in a list in four ways

1. At the start of a list ⁠maple; oak⁠

2. In the middle of a list ⁠oak; maple; birch⁠

3. At the end of a list ⁠oak; maple⁠

4. Alone with no delimiters maple

Usage

buildDelimRegex(str, delim)

Arguments

Details

This function builds a regex expression which captures those four cases It is mostly broken out of createSubvarDeriv() for testing purposes.

Value

A character string

S3 method to concatenate Categories and Category objects

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))

Given a vector of values and elements, calculate the insertions

Description

Given a vector of values and elements, calculate the insertions

Usage

calcTransforms(array, insert_funcs, dim_names = names(insert_funcs))

calcInsertions(vec, insert_funcs, dim_names = names(insert_funcs))

Arguments

Value

the values given in vec, with any insertions specified in trans calculated and inserted

as.data.frame method for catalog objects

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", project = "ACME")
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)

A utility to return a data.frame from a ShojiCatalog.

Description

This is an internal function called by the various as.data.frame methods. Use as.data.frame instead of calling this directly.

Usage

catalogToDataFrame(
  x,
  keys = TRUE,
  rownames = NULL,
  list_columns = c("subvariables", "subvariables_catalog"),
  ...
)

Arguments

Details

Some of the attributes of a ShojiCatalog will not naturally fit in a conventional data.frame. For example, an array variable contains a list of subvariables, and these subvariables will not easily fit in a single row of a data.frame. In this case, the list of subvariables are stored in a list-column in the resulting data.frame.

Value

a data.frame view of the catalog

Convert a factor's levels into Crunch categories.

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))

Change to different folder

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", project = "Studies")
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)

Change the id of a category for a categorical variable

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)

Check if a user has packages installed

Description

Check if a user has packages installed

Usage

checkInstalledPackages(pkgs)

Arguments

Value

nothing, called for side effects

Check validity of margins

Description

A helper function to check if margins supplied are compatible with the dimensions

Usage

check_margins(margin, selecteds)

Arguments

Value

None

Remove batches from a dataset

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.

Combine Categories in place

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()

Collapse an array from a CrunchCube by summing

Description

This is an internal function that powers dimSums()

Usage

collapse_dims(array_in, margins_to_collapse, collapsed_items)

Arguments

Value

a duly-collapsed array

Combine categories or responses

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)

Compare two datasets to see how they will append

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)

Conditional transformation

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)

Give consent to do things that require permission

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)

Copy the folder structure from one dataset to another.

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)

Copy the variable order from one dataset to another.

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)

Copy a variable

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.

Create an empty dataset

Description

Use only if you're writing a function to create a Crunch dataset from a custom data structure. If you have a data.frame, just call newDataset() on it.

Usage

createDataset(name, body, ..., project = defaultCrunchProject())

Arguments

Value

An object of class CrunchDataset.

See Also

newDataset()

Create subvariable derivation expressions

Description

This function creates a single subvariable definition based on a character string to search for and an originating variable. It uses regex to determine whether a string is present in a delimited list, then substitutes the user supplied values to indicate selection, non-selection, and missingness.

Usage

createSubvarDeriv(var, str, delim, selected, not_selected, unanswered)

Arguments

Value

A VariableDefinition

Make a dataset with metadata and a CSV

Description

This function just takes what you give it and POSTs to Crunch. No validation, no automatic wrapping in the Shoji envelope, etc.

Usage

createWithMetadataAndFile(metadata, file, strict = TRUE)

Arguments

Value

On success, a new dataset.

Upload a prepared data.frame with metadata to Crunch

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.

Crunch xtabs: Crosstab and otherwise aggregate variables in a Crunch Dataset

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)

Crunch API Keys

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.

Extract and modify Crunch objects

Description

Extract and modify Crunch objects

This function is no-op because the items are already updated on the server with other methods called prior to it.

Usage

## S4 method for signature 'AbstractCategories,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'AbstractCategories,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'AbstractCategories,numeric,ANY'
x[i, j, ..., drop = TRUE]

## S4 replacement method for signature 'AbstractCategories,character,ANY,ANY'
x[i, j, ...] <- value

## S4 method for signature 'AbstractCategories,character'
x[[i, j, ...]]

## S4 replacement method for signature 'AbstractCategories,character,ANY,ANY'
x[[i, j, ...]] <- value

## S4 method for signature 'AbstractCategory'
x$name

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

## S4 method for signature 'ScriptCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'Categories,ANY,ANY,ANY'
x[i, j, ...] <- value

## S3 method for class 'CrunchDataFrame'
x[i, j, drop = TRUE]

## S3 replacement method for class 'CrunchDataFrame'
x[i, j] <- value

## S3 method for class 'CrunchDataFrame'
x[[i]]

## S3 replacement method for class 'CrunchDataFrame'
x[[i]] <- value

## S3 method for class 'CrunchDataFrame'
x$i

## S3 replacement method for class 'CrunchDataFrame'
x$i <- value

## S4 method for signature 'CubeDims,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchCube,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 replacement method for signature 'TransformsList,ANY,missing,NULL'
x[[i, j]] <- value

## S4 method for signature 'DatasetCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'DatasetCatalog,character,missing,DatasetTuple'
x[[i, j]] <- value

## S4 method for signature 'CrunchDataset,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchDataset,logical,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'CrunchDataset,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchDataset,VariableGroup,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchDataset,VariableOrder,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchDataset,missing,ANY'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'CrunchDataset,CrunchLogicalExpr,missing'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'CrunchDataset,CrunchLogicalExpr,ANY'
x[i, j, ..., drop = FALSE]

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

## S4 method for signature 'CrunchDataset,ANY'
x[[i, ..., drop = FALSE]]

## S4 method for signature 'CrunchDataset,character'
x[[i, ..., drop = FALSE]]

## S4 method for signature 'CrunchDataset'
x$name

## S4 replacement method for signature 'CrunchDataset,character,missing,CrunchVariable'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,missing,CrunchVariable'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,character,missing,ANY'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,ANY,ANY'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,character,missing,NULL'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,missing,NULL'
x[[i]] <- value

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

## S4 replacement method for signature 'CrunchDataset,character,missing,CrunchGeography'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,missing,CrunchGeography'
x[[i]] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,missing,list'
x[i, j] <- value

## S4 replacement method for signature 'CrunchDataset,ANY,missing,CrunchDataset'
x[i, j] <- value

## S4 replacement method for signature 'CrunchDataset,CrunchExpr,ANY,ANY'
x[i, j] <- value

## S4 method for signature 'ShojiCatalog,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiCatalog,numeric,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiCatalog,logical,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiCatalog,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiCatalog,ANY'
x[[i, j, ...]]

## S4 method for signature 'ShojiCatalog,character'
x[[i, j, ...]]

## S4 method for signature 'ShojiCatalog'
x$name

## S4 replacement method for signature 'ShojiCatalog'
x$name <- value

## S4 replacement method for signature 'ShojiCatalog,ANY,missing,ShojiCatalog'
x[i, j] <- value

## S4 method for signature 'DeckCatalog,ANY'
x[[i, j, ...]]

## S4 method for signature 'DeckCatalog,character'
x[[i, j, ...]]

## S4 replacement method for signature 'DeckCatalog,ANY,missing,CrunchDeck'
x[[i, j]] <- value

## S4 replacement method for signature 'CrunchDeck,ANY,missing,AnalysisCatalog'
x[[i, j]] <- value

## S4 replacement method for signature 'SlideCatalog,ANY,missing,CrunchSlide'
x[[i, j]] <- value

## S4 replacement method for signature 'AnalysisCatalog,ANY,missing,Analysis'
x[[i, j]] <- value

## S4 method for signature 'CrunchDeck,ANY'
x[[i, j, ...]]

## S4 replacement method for signature 'CrunchDeck,ANY,ANY,ANY'
x[[i, j]] <- value

## S4 method for signature 'CrunchExpr,CrunchLogicalExpr,ANY'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'CrunchExpr,logical,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchExpr,numeric,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'FilterCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'FilterCatalog,character,missing,CrunchLogicalExpr'
x[[i, j]] <- value

## S4 replacement method for signature 'FilterCatalog,numeric,missing,CrunchLogicalExpr'
x[[i, j]] <- value

## S4 replacement method for signature 'FilterCatalog,character,missing,CrunchFilter'
x[[i, j]] <- value

## S4 replacement method for signature 'FilterCatalog,numeric,missing,CrunchFilter'
x[[i, j]] <- value

## S4 method for signature 'MemberCatalog,character'
x[[i, j, ...]]

## S4 replacement method for signature 'MemberCatalog,ANY,missing,ANY'
x[[i, j]] <- value

## S4 replacement method for signature 'MemberCatalog,character,missing,NULL'
x[[i, j]] <- value

## S4 method for signature 'MultitableCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'MultitableCatalog,character,missing,formula'
x[[i, j]] <- value

## S4 replacement method for signature 'MultitableCatalog,numeric,missing,formula'
x[[i, j]] <- value

## S4 replacement method for signature 'MultitableCatalog,ANY,missing,Multitable'
x[[i, j]] <- value

## S4 replacement method for signature 'MultitableCatalog,ANY,missing,NULL'
x[[i, j]] <- value

## S4 method for signature 'PermissionCatalog,character'
x[[i, j, ...]]

## S4 replacement method for signature 'ProjectFolder,character,missing,list'
x[[i, j]] <- value

## S4 replacement method for signature 'ProjectFolder,character,missing,ProjectFolder'
x[[i, j]] <- value

## S4 method for signature 'ShojiFolder,numeric'
x[[i, ..., drop = FALSE]]

## S4 method for signature 'ShojiFolder,character'
x[[i, ..., drop = FALSE]]

## S4 method for signature 'ShojiOrder,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiOrder,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ShojiOrder,ANY'
x[[i, j, ...]]

## S4 method for signature 'ShojiOrder,character'
x[[i, j, ...]]

## S4 method for signature 'ShojiOrder'
x$name

## S4 replacement method for signature 'ShojiOrder,character,missing,ShojiOrder'
x[i, j] <- value

## S4 replacement method for signature 'ShojiOrder,ANY,missing,ShojiOrder'
x[i, j] <- value

## S4 replacement method for signature 'ShojiOrder,character,missing,list'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,character,missing,character'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,character,missing,OrderGroup'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,ANY,missing,OrderGroup'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,ANY,missing,ANY'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,ANY,missing,NULL'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,character,missing,NULL'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder,character,missing,ShojiOrder'
x[[i, j]] <- value

## S4 replacement method for signature 'ShojiOrder'
x$name <- value

## S4 method for signature 'OrderGroup,ANY,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'OrderGroup,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'OrderGroup,character'
x[[i, j, ...]]

## S4 method for signature 'OrderGroup,ANY'
x[[i, j, ...]]

## S4 method for signature 'OrderGroup'
x$name

## S4 replacement method for signature 'OrderGroup,character,missing,list'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,character,missing,character'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,character,missing,ShojiOrder'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,character,missing,OrderGroup'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,ANY,missing,OrderGroup'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,numeric,missing,NULL'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup,character,missing,NULL'
x[[i, j]] <- value

## S4 replacement method for signature 'OrderGroup'
x$name <- value

## S4 method for signature 'SlideCatalog,ANY'
x[[i, j, ...]]

## S4 replacement method for signature 'SlideCatalog,numeric,missing,CrunchSlide'
x[[i, j]] <- value

## S4 method for signature 'CrunchAnalysisSlide,ANY'
x[[i, j, ...]]

## S4 replacement method for signature 'CrunchAnalysisSlide,ANY,ANY,ANY'
x[[i, j]] <- value

## S4 method for signature 'AnalysisCatalog,ANY'
x[[i, j, ...]]

## S4 replacement method for signature 'AnalysisCatalog,numeric,missing,formula'
x[[i, j]] <- value

## S4 replacement method for signature 'AnalysisCatalog,numeric,missing,Analysis'
x[[i, j]] <- value

## S4 replacement method for signature 'AnalysisCatalog,numeric,missing,list'
x[[i, j]] <- value

## S4 method for signature 'Subvariables,character'
x[[i, j, ...]]

## S4 method for signature 'Subvariables,numeric'
x[[i, j, ...]]

## S4 method for signature 'Subvariables,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 replacement method for signature 'Subvariables,character,missing,CrunchVariable'
x[[i]] <- value

## S4 replacement method for signature 'Subvariables,ANY,missing,CrunchVariable'
x[[i]] <- value

## S4 replacement method for signature 'Subvariables,ANY,missing,NULL'
x[[i]] <- value

## S4 replacement method for signature 'Subvariables,ANY,missing,ANY'
x[[i]] <- value

## S4 replacement method for signature 'Subvariables,character,missing,Subvariables'
x[i] <- value

## S4 replacement method for signature 'Subvariables,ANY,missing,Subvariables'
x[i] <- value

## S4 replacement method for signature 'Subvariables,ANY,missing,ANY'
x[i] <- value

## S4 method for signature 'ArrayVariable,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ArrayVariable,missing,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ArrayVariable,missing,character'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'ArrayVariable,ANY'
x[[i, j, ...]]

## S4 method for signature 'ArrayVariable,character'
x[[i, j, ...]]

## S4 method for signature 'ArrayVariable'
x$name

## S4 replacement method for signature 'ArrayVariable,ANY,missing,ANY'
x[[i]] <- value

## S4 replacement method for signature 'ArrayVariable,character,missing,ANY'
x[[i]] <- value

## S4 replacement method for signature 'ArrayVariable'
x$name <- value

## S4 method for signature 'TabBookResult,numeric'
x[[i, j, ...]]

## S4 method for signature 'TabBookResult,character'
x[[i, j, ...]]

## S4 method for signature 'MultitableResult,ANY'
x[[i, j, ...]]

## S4 method for signature 'TeamCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'TeamCatalog,character,missing,list'
x[[i, j]] <- value

## S4 replacement method for signature 'TeamCatalog,character,missing,CrunchTeam'
x[[i, j]] <- value

## S4 method for signature 'UserCatalog,character,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'UserCatalog,character'
x[[i, j, ...]]

## S4 method for signature 'VariableCatalog,numeric'
x[[i, j, ...]]

## S4 replacement method for signature 'VariableCatalog,character,missing,VariableTuple'
x[[i, j]] <- value

## S4 replacement method for signature 'VariableCatalog,character,missing,CrunchVariable'
x[[i, j]] <- value

## S4 method for signature 'VariableCatalog,VariableOrder,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'VariableCatalog,VariableGroup,ANY'
x[i, j, ..., drop = TRUE]

## S4 replacement method for signature 
## 'VariableCatalog,VariableOrder,missing,VariableCatalog'
x[i, j] <- value

## S4 replacement method for signature 
## 'VariableCatalog,VariableGroup,missing,VariableCatalog'
x[i, j] <- value

## S4 replacement method for signature 'VariableOrder,character,missing,CrunchDataset'
x[[i, j]] <- value

## S4 replacement method for signature 'VariableGroup,character,missing,CrunchDataset'
x[[i, j]] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,ANY'
x[i, j] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,NULL'
x[i, j] <- value

## S4 replacement method for signature 'TextVariable,ANY,missing,character'
x[i, j] <- value

## S4 replacement method for signature 'NumericVariable,ANY,missing,numeric'
x[i, j] <- value

## S4 replacement method for signature 'DatetimeVariable,ANY,missing,Date'
x[i, j] <- value

## S4 replacement method for signature 'DatetimeVariable,ANY,missing,POSIXt'
x[i, j] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,CrunchExpr'
x[i, j] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,CrunchVariable'
x[i, j] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,CrunchLogicalExpr'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalVariable,ANY,missing,numeric'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalVariable,ANY,missing,character'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalVariable,ANY,missing,factor'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalArrayVariable,ANY,missing,numeric'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalArrayVariable,ANY,missing,character'
x[i, j] <- value

## S4 replacement method for signature 'CategoricalArrayVariable,ANY,missing,factor'
x[i, j] <- value

## S4 replacement method for signature 'CrunchVariable,ANY,missing,logical'
x[i, j] <- value

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

## S4 method for signature 'CrunchVariable,CrunchExpr,ANY'
x[i, j, ..., drop = FALSE]

## S4 method for signature 'CrunchVariable,numeric,ANY'
x[i, j, ..., drop = TRUE]

## S4 method for signature 'CrunchVariable,logical,ANY'
x[i, j, ..., drop = TRUE]

Arguments

Value

[ generally returns a subset of x, same class and "self" URL; when subsetting with a CrunchExpr, the expression is recorded in an attribute of the object. [[ and $ return appropriate extractions from x, wherever possible without making an additional API request. The assignment methods return x appropriately updated. Most assignment methods do not make an API request except where they clearly are used to create a new entity (as in assigning a variable definition to a Dataset); for editing metadata attributes, these methods generally assume that the API request to set the changes on the server happens in a different method (e.g. in names(variables(ds)[1:5]) <- value, assignment happens in the ⁠names<-⁠ method).

Summary methods for Crunch Variables

Description

Summary methods for Crunch Variables

Usage

## S3 method for class 'CategoricalVariable'
summary(object, ...)

## S3 method for class 'NumericVariable'
summary(object, ...)

Arguments

Value

a summary response. Categorical variable summaries should work like summary.factor; Numeric variables should be like summary.numeric. Other Variable types are not yet supported.

Univariate statistics on Crunch objects

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()

Main Crunch API handling function

Description

Main Crunch API handling function

Usage

crunchAPI(
  http.verb,
  url,
  config = list(),
  status.handlers = list(),
  progress.handler = NULL,
  ...
)

Arguments

Make a CrunchBox

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)

Crunch situation report

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)

Generate or extend the User-Agent string

Description

By default, the names and versions of curl, httr, and any attached Crunch packages are included in the User-Agent request header. You can add to this using this function.

Usage

crunch_user_agent(...)

Arguments

Value

The User-Agent string. Provide this appropriately in requests or set globally with set_crunch_config().

Work with CrunchCubes, MultitableResults, and TabBookResults

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()

Calculate standardized residuals from a CrunchCube

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

Get measure type of cube result

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)

Cut a Datetime Crunch variable

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", project = "client 1")
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)

Cut a numeric Crunch variable

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", project = "p1")
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)

View or set a dashboard URL

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)

as.data.frame method for CrunchDataset

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()

Get a Crunch object's dataset URL

Description

Get a Crunch object's dataset URL

Usage

datasetReference(x)

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

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

## S4 method for signature 'CrunchExpr'
datasetReference(x)

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

## S4 method for signature 'character'
datasetReference(x)

## S4 method for signature 'ANY'
datasetReference(x)

Arguments

Value

The URL of the dataset which contains that object

Get a catalog of datasets

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", project = "Studies")
datasets(proj) <- ds

## End(Not run)

Get a dataset's DeckCatalog

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

Delete a Crunch object from the server

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()

Delete a dataset from the dataset list

Description

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

Usage

deleteDataset(x, ..., project = defaultCrunchProject("./"))

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.

Delete subvariables from an array

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()

Delete Variables Within a Dataset

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().

Get or set a derived variable's expression

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)

Make a Categorical Array or Multiple Response variable

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)

Name, alias, and description for Crunch objects

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

Indicate how categories represent a dichotomized value

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)

Collapse an array from a CrunchCube by summing across dimensions to remove

Description

Typically when collapsing a crosstab you can just sum across the dimensions that you want to collapse across. However, because we have array-type questions/dimensions we have to be a little bit smarter. We cannot sum across any subvariable dimension (dimension types ending with "_items") because that would inflate the number of respondents by approximately the number of subvariables. Instead, we take the mean across any "_items" dimension. In principle, we could just take a single item or unique across the "_items" dimensions, however due to floating point differences + rounding there are minute differences that pop up, mean smooths over those tiny differences.

Usage

dimSums(x, margin = NULL)

Arguments

Details

dimSums returns a cube that retains the dimensions given in margin and collapses all the others. This is useful if you want to get counts that are equivalent to a univariate cube from a multivariate cube. For example dimSums(crtabs(~ fruit + pets, ds), 1) will be equal to crtabs(~ fruit, ds) and dimSums(crtabs(~ fruit + pets, ds), 2) will be equal to crtabs(~ pets, ds).

Value

a duly-collapsed CrunchCube

Column and row comparison

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

Pairwise column and row comparison

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

Methods on Cube objects

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

Permanently delete rows from a dataset

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)

"duplicated" method for Crunch objects

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()

Extract the email from a User Entity

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

Get HTML for embedding a CrunchBox

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)

Validate case statements for case variables

Description

Validate case statements for case variables

Usage

ensureValidCase(case)

Arguments

Methods for ShojiTuples

Description

ShojiTuples are objects extracted from ShojiCatalogs. They are internally used.

Usage

entity(x)

## S4 method for signature 'ShojiEntity'
x$name

## S4 replacement method for signature 'ShojiEntity'
x$name <- value

## S4 method for signature 'ShojiEntity,ANY'
x[[i]]

## S4 replacement method for signature 'ShojiEntity,ANY,ANY,ANY'
x[[i]] <- value

## S4 method for signature 'ShojiTuple'
refresh(x)

## S4 method for signature 'ShojiTuple'
x$name

## S4 replacement method for signature 'ShojiTuple'
x$name <- value

## S4 method for signature 'ShojiTuple,ANY'
x[[i]]

## S4 replacement method for signature 'ShojiTuple,ANY,ANY,ANY'
x[[i]] <- value

## S4 method for signature 'ShojiTuple'
self(x)

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

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

## S4 method for signature 'DatasetTuple'
entity(x)

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

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

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

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

Arguments

Get/set options (user-specified, in environment, or in R options)

Description

These functions allow for a consistent framework of options for the crunch package. When retrieving options, envOrOption() first looks for options set with the set_crunch_opts(), followed by options in the environment (see Sys.getenv()) and finally in the R options (see options).

Usage

envOrOption(opt, default = NULL, expect_lgl = FALSE, expect_num = FALSE)

set_crunch_opts(..., .source = NULL)

Arguments

Details

Environment variables are generally set at the operating system level, but R does look at a file called .Renviron on startup, and you can also set them using the function Sys.setenv(). Options are generally set using a options() function in the .Rprofile file, but can be set using that function anywhere.

The main crunch R package uses the following options (note that the option name is in all capital letters, with "." replaced with "" and a "R" prefix when used as an environment variable):

Value

the value of the option

Escape a regular expression

Description

This function takes a string and escapes all of the special characters in the string. For example, the . in VB.NET will be escaped with a slash (though regular R printing will make it look like there are two slashes).

Usage

escapeRegex(string)

Arguments

Value

string, escaped.

Examples

## Not run: 
escapeRegex("Tom&Jerry")
escapeRegex(".Net")

## End(Not run)

View and set exclusion filters

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.

Export a dataset to a file

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)

Export a Crunch Deck

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).

Construct Crunch Expressions from Crunch Database Functions

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()

Crunch expressions internal

Description

See expressions for more details.

Usage

x %in% table

crunchDifftime(e1, e2, resolution = NULL)

datetimeFromCols(year, month, day, hour = NULL, minute = NULL, second = NULL)

e1 %ornm% e2

## S4 method for signature 'CrunchExpr'
!x

## S4 method for signature 'CategoricalVariable,character'
x %in% table

## S4 method for signature 'CategoricalVariable,factor'
x %in% table

## S4 method for signature 'TextVariable,character'
x %in% table

## S4 method for signature 'NumericVariable,numeric'
x %in% table

## S4 method for signature 'DatetimeVariable,Date'
x %in% table

## S4 method for signature 'DatetimeVariable,POSIXt'
x %in% table

## S4 method for signature 'DatetimeVariable,character'
x %in% table

## S4 method for signature 'CategoricalVariable,numeric'
x %in% table

## S4 method for signature 'CategoricalVariable,numeric'
e1 == e2

## S4 method for signature 'CategoricalVariable,character'
e1 == e2

## S4 method for signature 'CategoricalVariable,factor'
e1 == e2

## S4 method for signature 'CategoricalVariable,numeric'
e1 != e2

## S4 method for signature 'CategoricalVariable,character'
e1 != e2

## S4 method for signature 'CategoricalVariable,factor'
e1 != e2

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

is.valid(x)

bin(x)

selectCategories(x, selections, collapse = TRUE)

crunchBetween(x, lower, upper, inclusive = c(TRUE, FALSE))

rowAll(x, na.rm = FALSE)

rowAny(x, na.rm = FALSE)

rowAnyNA(x)

rowAllNA(x)

## S4 method for signature 'CrunchVarOrExpr'
complete.cases(x, ...)

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

asSelected(x)

selectedDepth(x)

arraySelections(x)

## S4 method for signature 'CrunchVarOrExpr'
nchar(x, type = "chars", allowNA = FALSE, keepNA = NA)

trim(x, min, max)

alterCategoriesExpr(
  x,
  categories = NULL,
  category_order = NULL,
  subvariables = NULL
)

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")
)

arraySubsetExpr(x, subvars, subvar_id = c("alias", "name", "id"))

makeFrame(x, numeric = NULL)

Arguments

Value

Most functions return a CrunchExpr or CrunchLogicalExpr. as.vector returns an R vector.

Expression to fill a variable from another

Description

Given a categorical variable, assign one or more categories to be filled in by another existing variable or crunch expression. (Categories not filled in will remain unchanged ).

Usage

fillExpr(x, fills, ..., data = NULL, type = NULL)

Arguments

Value

A CrunchExpression that assigns categories to filling variables

Examples

## Not run: 
fillExpr(
    ds$v1,
    fills = list(
        list(fill = ds$v2, name = "dog")
    )
)
fillExpr(v1, "dog" = ds$v2)

# the dataset can be specified with data=
fillExpr(v1, "dog" = v2, data = ds)

## End(Not run)

Get and set slide analyses

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)

Get or set a dataset's filters

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.)

Remove nesting of groups within an order/group

Description

This function reduces a potentially nested order to its flattened representation, containing no nested groups. Entities are ordered in the result by their first appearance in the order object.

Usage

flattenOrder(x)

Arguments

Value

x, or its order resource, flattened.

Rearrange array subvariables

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)

Find and move entities to a new folder

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", project = "Studies")
folder(ds$income) <- "Demographics/Economic"
folder(ds$income)
## [1] "Demographics"    "Economic"

## End(Not run)

Force variables catalog to be loaded

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

Create a fork of a dataset

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,
  ...,
  project = defaultCrunchProject()
)

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()

Examples

## Not run: 
# Defaults to being placed in the same project folder as the original dataset
ds_fork <- forkDataset(ds)

# But you can specify a project by path, `ProjectFolder` object or URL
ds_fork2 <- forkDataset(ds, project = "/Client1/forks/")
ds_fork3 <- forkDataset(ds, project = projects()[["My forks"]])
ds_fork4 <- forkDataset(ds, project = "https://app.crunch.io/api/projects/abc/")

## End(Not run)

Fortify crunch objects for use with ggplot

Description

Fortify crunch objects for use with ggplot

Usage

fortify.CrunchDataFrame(model, data, ...)

fortify.CrunchDataset(model, data, ...)

Arguments

Generate Labels for the cut function

Description

A convenience function to generate labels for the cut function. This function is extracted from base::cut() and is broken out to make it easier to test. It is not meant to be called on its own.

Usage

generateNumCutLabels(dig.lab, breaks, nb, right, include.lowest)

Arguments

Value

A character vector of labels

Generate entry for makeWeight

Description

Utility function to catch formula errors passed to makeWeight, and to generate the appropriate entry.

Usage

generateWeightEntry(expr)

Arguments

Value

A list of the variable id and the target weights.

Examples

## Not run: 
validateWeightExpression(ds$var ~ c(10, 30, 60))

## End(Not run)

Find all users on your account

Description

Find all users on your account

Usage

getAccountUserCatalog(x = shojiURL(getAccount(), "catalogs", "users"))

Arguments

Value

a UserCatalog

Get dimension type

Description

This function returns the specific type of each cube dimension. This is useful when cubes contain array variables because it identifies the dimensions of the cube which refer to the different parts of array variable:

• ca_items: Categorical array items

• ca_categories: The categories of the categorical array

• mr_items: Multiple response options or items

• mr_selections: The selection status for a multiple response variable

• numarray_items: Numeric array items

Usage

getDimTypes(x)

Arguments

Value

a character vector of dimension types, similar to types(), except that the array variable types are more specific.

Retrieve your teams

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

grab column names for subsetting crdfs

Description

Take a character, logical, or integer vector and return the appropriate names of the crdf to subset. Disallow logicals (in the case of [[ subsetting, to conform with data.frame methods)

Usage

grabColNames(x, j, allow_logical = TRUE)

Arguments

Value

character names of the columns of the crdf to select

grab row indicators for subsetting crdfs

Description

grab row indicators for subsetting crdfs

Usage

grabRowInd(x, i)

Arguments

Value

integers of the rows of the crdf to select

Get grouped or ungrouped OrderGroups

Description

"ungrouped" is an OrderGroup that contains all entities not found in groups at a given level of nesting.

Usage

grouped(order.obj)

ungrouped(order.obj)

Arguments

Value

For grouped(), an Order/Group, respectively, with "ungrouped" omitted. For ungrouped(), an OrderGroup subclass.

See Also

VariableOrder

Do the right thing with the HTTP response

Description

Do the right thing with the HTTP response

Usage

handleAPIresponse(response, special.statuses = list(), progress.handler = NULL)

Arguments

Value

The full HTTP response object, just the content, or any other status-specific action

Check if a package has a function installed

Description

This is useful for handling if the user has the correct version of a suggested package installed.

Usage

hasFunction(fun, pkg)

Arguments

Value

Logical

HTTP methods for communicating with the Crunch API

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.

Get the body of a Catalog

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.

Calculate an index table for a CrunchCube

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)

Create a variable by interacting categorical variables

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)

is.na for Categories

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.

View and modify the "public" attribute of artifacts

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.

Check that a value is TRUE or FALSE

Description

Check that a value is TRUE or FALSE

Usage

is.TRUEorFALSE(value)

Arguments

Value

TRUE if value is either TRUE or FALSE, FALSE otherwise

Test whether a Crunch object belongs to a class

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

Read and set edit privileges

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.

Dataset weights

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()

Add columns from one dataset to another, joining on a key

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.

Length of Crunch objects

Description

Length of Crunch objects

Usage

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

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

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

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

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

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

Arguments

Value

Integer: the number of elements in the catalog, group, folder, etc.

Get the names of datasets in a project

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

Value

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

Load a Crunch Dataset

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 = defaultCrunchProject("."),
  refresh = FALSE
)

Arguments

Details

You can specify a dataset to load by its human-friendly "name", within the project (folder) to find it in. This makes code more readable, but it does mean that if the dataset is renamed or moved to a different folder, your code may no longer work. The fastest, most reliable way to use loadDataset() is to provide a URL to the dataset–the dataset's URL will never change.

Value

An object of class CrunchDataset.

See Also

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

Examples

## Not run: 
ds <- loadDatasets("A special dataset", project = "Studies")
ds2 <- loadDatasets("~/My dataset", project = "Studies")
ds3 <- loadDataset("My dataset", project = projects()[["Studies"]]) # Same as ds2
ds4 <- loadDataset("https://app.crunch.io/api/datasets/bd3ad2/")

## End(Not run)

Lock and unlock a dataset for editing

Description

Crunch allows a single active editor. If you have edit privileges but are not currently editing the dataset, you must unlock the dataset before making changes. You may then lock the dataset when you're done editing.

Usage

lock(dataset)

unlock(dataset)

Arguments

Value

dataset, invisibly, after having set the current editor.

DEPRECATED! Authenticate with the Crunch API

Description

A deprecated method to authenticate to the crunch.io API. See crunch-api-key for the currently supported method, as login(), logout() and resetPassword() no longer work.

Usage

logout()

login(...)

resetPassword(...)

Arguments

Make a case variable

Description

The makeCaseVariable function derives a variable using values from other variables. These are evaluated in the order they are supplied in the list as the cases argument (they proceed in an IF, ELSE IF, ELSE IF, ..., ELSE fashion); the first one that matches selects the corresponding value from the case list. caseExpr() is a version that returns an expression that could be used when creating complex variables, see expressions for more details.

Usage

makeCaseVariable(..., cases, data = NULL, name)

caseExpr(..., cases)

Arguments

Details

There are two ways to specify cases, but you must pick only one (note these two will produce the same case variable):

1. When you just want to specify conditions, you can use named conditions: makeCaseVariable(case1=ds$v1 == 1, case2=ds$v2 == 2, name="new case")

2. You can also use the cases argument, which is useful when you want to provide category ids, numeric values, or missingness: makeCaseVariable( cases=list( list(expression=ds$v1 == 1, name="case1"), list(expression=ds$v2 == 2, name="case2") ), name="new case" )

Rows in the dataset that do not match any of the provided "cases" will be assigned to an "else" category. By default, Crunch will use the system missing "No Data" category. Alternatively, you can provide an else case definition for these rows by including as the last "case" you provide one with its expression set to the string "else". See the examples for details.

Value

A VariableDefinition that will create the new case variable when assigned into the Dataset.

Examples

## Not run: 
makeCaseVariable(case1 = ds$v1 == 1, case2 = ds$v2 == 2, name = "new case")
makeCaseVariable(
    cases = list(
        list(expression = ds$v1 == 1, name = "case1"),
        list(expression = ds$v2 == 2, name = "case2")
    ),
    name = "new case"
)

# different ways to specify else cases
makeCaseVariable(
    cases = list(
        list(expression = ds$v1 == 1, name = "case1"),
        list(expression = ds$v2 == 2, name = "case2"),
        list(expression = "else", name = "other")
    ),
    name = "new case"
)
makeCaseVariable(case1 = ds$v1 == 1, case2 = ds$v2 == 2, other = "else", name = "new case")

# the dataset can be specified with data=
makeCaseVariable(case1 = v1 == 1, case2 = v2 == 2, data = ds, name = "new case")

## End(Not run)

Create a categorical or numeric variable based on conditions

Description

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. When creating a categorical variable, the right-hand side must be a Category or a categorical CrunchVariable or CrunchExpression, while for numeric variables it is a single number or variable or expression.

Usage

makeCaseWhenVariable(..., data = NULL, cases = NULL, name, type = NULL)

caseWhenExpr(..., data = NULL, cases = NULL, type = NULL)

Arguments

Value

makeCaseWhenVariable() returns a VariableDefinition and caseWhenExpr() returns an expression

Examples

## Not run: 
# Creating categorical variables
ds$new_var <- makeCaseWhenVariable(
   ds$x %in% c("a", "b") ~ ds$y, # can fill with a variable
   ds$x %in% c("c", "d") ~ Category(name = "c or d", numeric_value = 10), # or a Category
   # If none of the categories match, will be set to missing unless you
   # specify an "else" case with `TRUE` in the left hand side
   TRUE ~ Category(name = "catch all"),
   name = "combined x and y"
)

ds$brand_x_pref <- makeCaseWhenVariable(
   ds$brand[[1]] == "Brand X" ~ ds$pref[[1]],
   ds$brand[[2]] == "Brand X" ~ ds$pref[[2]],
   ds$brand[[3]] == "Brand X" ~ ds$pref[[3]],
   name = "brand x preference"
)

ds$x_among_aware <- makeCaseWhenVariable(
   ds$aware_x == "Yes" ~ ds$x,
   TRUE ~ Category(name = "(Not aware)", missing = TRUE),
   name = "x (among respondents aware of x)"
)

ds$new_num_var <- makeCaseWhenVariable(
  ds$x %in% c("a", "b") ~ ds$z, # LHS as before, RHS can be numeric variables,
  ds$x == "c" ~ ds$z * 10, # expressions,
  ds$x == "d" ~ 100, # or numbers
  name = "New numeric variable"
)

ds$capped_z <- makeCaseWhenVariable(
  ds$z > 10 ~ 10,
  TRUE ~ ds$z,
  name = "Capped z"
)

# caseWhenExpr can be used inside other expressions
ds$brand_x_prefer_high <- VarDef(
   selectCategories(
       caseWhenExpr(
           ds$brand_shown[[1]] == "Brand X" ~ ds$ratings[[1]],
           ds$brand_shown[[2]] == "Brand X" ~ ds$ratings[[2]],
           ds$brand_shown[[3]] == "Brand X" ~ ds$ratings[[3]]
       ),
       c("Best", "Very Good")
   ),
   name = "Rate X highly"
)

# Using lists in `cases` argument can be helpful when working programmatically
source_var <- ds$x
inclusion_condition <- ds$skipped_x != "Yes"

ds$x2_among_aware <- makeCaseWhenVariable(
   cases = list(list(fill = source_var, expression = inclusion_condition)),
   name = "x2 among aware"
)

## End(Not run)

Helper for creating slide dimension transformations for dashboards and exports

Description

When displayed in a Crunch Dashboard or exported, crunch slides can have transformations that customize their display. This is a helper to form the correct data structure for the functions newSlide() for setting the transformation directly. For more details see the API documentation

Usage

makeDimTransform(
  colors = NULL,
  hide = NULL,
  rename = NULL,
  order = NULL,
  name = NULL,
  description = NULL,
  ...
)

Arguments

Examples

## Not run: 
# Hiding an element
transforms(slide) <- list(rows_dimension = makeDimTransform(hide = "Neutral"))

# Using an existing saved palette
transforms(slide) <- list(rows_dimension = makeDimTransform(
    colors = defaultPalette(ds)
))

# Setting specific colors
transform(slide) <- list(rows_dimension = makeDimTransform(
     colors = c("#af8dc3", "#f7f7f7", "#7fbf7b")
))

# Reordering & renaming elements
transforms(slide) <- list(
     rows_dimension = makeDimTransform(
         rename = c("V. Good" = "Very Good", "V. Bad" = "Very Bad"),
         order = 5:1
     ),
     columns_dimension = makeDimTransform(order = c("Brand X", "Brand A", "Brand B"))
)

## End(Not run)

Convert a child class of Insertion into a proper Insertion

Description

The Crunch API expects that Subtotals, Headings, and other insertions all have the same shape. Before sending insertions to the server, we need to call makeInsertion on any insertions to make sure they are proper Insertions. This process sometimes requires a variable's categories object (e.g. in order to convert from category names to category ids)

The Crunch API expects that Subtotals, Headings, and other insertions all have the same shape. Before sending insertions to the server, we need to call makeInsertion on any insertions to make sure they are proper Insertions. This process sometimes requires a variable's categories object (e.g. in order to convert from category names to category ids)

Usage

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

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

## S4 method for signature 'Insertion'
makeInsertion(x, var_items, alias)

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

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

## S4 method for signature 'Insertion'
makeInsertion(x, var_items, alias)

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

Arguments

Value

an Insertion object

an Insertion object

Create Multiple Response Variable from Delimited lists

Description

Surveys often record multiple response questions in delimited lists where each respondent's selections are separated by a delimiter like ⁠;⁠ or |. This function breaks the delimited responses into subvariables, uploads those subvariables to Crunch, and finally creates a multiple response variable from them.

Usage

makeMRFromText(
  var,
  delim,
  name,
  selected = "selected",
  not_selected = "not_selected",
  unanswered = NA,
  ...
)

Arguments

Value

a Multiple response variable definition

Make a map of margins

Description

Useful when converting to and from user and real cube dimension indexes.

Usage

makeMarginMap(dimTypes)

Arguments

Value

a vector of margins, the length of which is the length of the real cube, the values are the user cube dimensions

Examples

## Not run: 
makeMarginMap(getDimTypes(cat_by_cat_cube))
# 1 2

makeMarginMap(getDimTypes(MR_by_cat_cube))
# 1 1 2

makeMarginMap(getDimTypes(cat_by_MR_cube))
# 1 2 2

makeMarginMap(getDimTypes(MR_by_MR_cube))
# 1 1 2 2

## End(Not run)

Generate a weight variable

Description

This function allows you to generate a weight variable by supplying a set of categorical variables and the target distribution for each of the variables' categories. Weights are computed by iteratively 'raking' conditional 'cells' to the provided marginal targets.

Usage

makeWeight(..., name)

Arguments

Details

For instance, if you wanted to create a weight variable which equally weighted four categories stored in ds$var you would call ds$weight1 <- makeWeight(ds$var ~ c(25, 25, 25, 25), name = "weight1"). Note that makeWeight returns a VariableDefinition, an expression that when assigned into your Dataset becomes a derived variable. This does not on its own set the new variable as "the weight" for your dataset. To set that attribute, use weight(). Alternatively, you can also create the variable and set the weight attribute in one step with weight(ds) <- makeWeight(ds$var ~ c(25, 25, 25, 25), name = "weight1").

Value

A crunch VariableDefinition() of the weight variable

See Also

weight<-(); settings() for the "default weight" for other dataset viewers.

Examples

## Not run: 
mtcars$cyl <- as.factor(mtcars$cyl)
mtcars$gear <- as.factor(mtcars$gear)
ds <- newDataset(mtcars, project = "examples/cars")
# Create a new "raked" variable
ds$weight <- makeWeight(ds$cyl ~ c(30, 30, 40, 0),
    ds$gear ~ c(20, 20, 60, 0),
    name = "weight"
)
summary(ds$weight)
# ds$weight is not "the weight" for the dataset unless you set it:
weight(ds) <- ds$weight
# Or, you can create the variable and set as weight in one step:
weight(ds) <- makeWeight(ds$var ~ c(25, 25, 25, 25), name = "weight2")

## End(Not run)

Convert from user margins to real cube margins or vice versa

Description

It is helpful to programmatically move from user-specified margins to real cube margins that apply to the higher-dimensional real cube (with user2realMargin). Or to move from the higher-dimensional real cube to user cube (with real2userMargin).

Usage

user2realMargin(margin, dimTypes = getDimTypes(cube), cube)

real2userMargin(margin, dimTypes = getDimTypes(cube), cube, dedupe = TRUE)

Arguments

Value

margin or margins in the higher-dimension real cube

Match categories with features from geodata

Description

Match categories with features from geodata

Usage

matchCatToFeat(categories, all_features = availableGeodataFeatures())

Arguments

Value

geodatum to associate with the variable that produced categories

My user entity

Description

Get the user entity of the currently authenticated user.

Usage

me()

Value

A UserEntity

Manage access to datasets and other objects

Description

These methods allow you to work with teams.

Usage

members(x)

members(x) <- value

permissions(x)

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

## S4 replacement method for signature 'ProjectFolder,MemberCatalog'
members(x) <- value

## S4 method for signature 'CrunchTeam'
members(x)

## S4 replacement method for signature 'ProjectFolder,character'
members(x) <- value

## S4 replacement method for signature 'CrunchTeam,MemberCatalog'
members(x) <- value

## S4 replacement method for signature 'CrunchTeam,character'
members(x) <- value

Arguments

Value

members() returns a MemberCatalog, which has references to the users that are members of the team. ⁠members<-⁠ returns x with the given users added to the members catalog. permissions() returns a PermissionCatalog with similar semantics.

See Also

users()

Merge a CrunchDataFrame

Description

mergeing a CrunchDataFrame with a local dataframe is useful in situations where you have new information in your local R session that you want to connect with Crunch data. For example, for making plots with Crunch and non-Crunch data. It produces a hybrid CrunchDataFrame that has the local data attached to it, but like normal CrunchDataFrames it is still judicious about downloading data from the server only when it is needed.

Usage

## S3 method for class 'CrunchDataFrame'
merge(
  x,
  y,
  by = intersect(names(x), names(y)),
  by.x = by,
  by.y = by,
  sort = c("x", "y"),
  ...
)

Arguments

Details

Merging a CrunchDataFrame with a local dataframe does not allow specifying all rows from both sources. Instead, the resulting CrunchDataFrame will include all of the rows in whichever source is used for sorting (x or y). So if you specify sort="x" (the default) all rows of x will be present but rows in y that do not match with rows in x will not be present.

Merging a CrunchDataFrame with a local dataframe is experimental and might result in unexpected results. One known issue is that using merge on a CrunchDataFrame will change the both the CrunchDataFrame used as input as well as create a new CrunchDataFrame.

Value

a CrunchDataFrame with columns from both x and y

Merge changes to a dataset from a fork

Description

Crunch datasets include information about the dataset's revision history. This function takes the changes made on a dataset fork and adds them to the revision history of the parent dataset, like a merge of branches in a version control system.

Usage

mergeFork(dataset, fork, autorollback = TRUE, force = FALSE)

Arguments

Details

All modifications of a dataset record actions in its revision history. For example, if you add a variable to the dataset, that action is recorded. The sum of these records is a dataset's revision history, and it is possible to merge in the revision history of a dataset that has been forked.

This function is most often used in conjunction with forkDataset() to create a copy of a dataset, make some changes to that copy, and then merge the changes back into the original dataset. For more on this workflow, see vignette("fork-and-merge", package = "crunch").

Value

dataset with changes from fork merged to it.

See Also

forkDataset()

Examples

## Not run: 
ds <- loadDataset("My survey", project = "Studies")
fork <- forkDataset(ds)
# Do stuff to fork
ds <- mergeFork(ds, fork)
# Now the changes you did to fork are also on ds

## End(Not run)

Move and delete last element of a vector This moves the last element of a vector to an index, then deletes the last element, it is broken out for testing purposes

Description

Move and delete last element of a vector This moves the last element of a vector to an index, then deletes the last element, it is broken out for testing purposes

Usage

moveLastElement(v, idx)

Arguments

Value

a vector

Multitable entities for a dataset

Description

Multitable entities for a dataset

Usage

multitables(x)

multitables(x) <- value

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

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

Arguments

Value

an object of class MultitableCatalog containing references to Multitable entities. (Setter returns the Dataset.)

Functions to manipulate variables' or project's folder structure

Description

Variables in Crunch datasets are organized into folders, like in a file system. Datasets are similarly organized into hierarchical Projects. These functions allow you to create new folders and move objects into folders. Their names, mv and mkdir, suggest their Unix file utility inspiration.

Usage

mv(x, what, path)

mkdir(x, path)

Arguments

Details

The functions have some differences from the strict behavior of their Unix ancestors. For one, they work recursively, without additional arguments: mkdir will make every directory necessary to construct the requested path, even if all parent directories didn't already exist; and mv doesn't require that the directory to move to already exist—it will effectively call mkdir along the way.

Value

x, with the folder at path guaranteed to be created, and for mv, containing what moved into it.

See Also

cd() to select a folder by path; rmdir() to delete a folder; folder() to identify and set an object's parent folder; base::dir.create() if you literally want to create a directory in your local file system, which mkdir() does not do

Examples

## Not run: 
ds <- loadDataset("Example survey", project = "Studies")
ds <- mv(ds, c("gender", "age", "educ"), "Demographics")
ds <- mkdir(ds, "Key Performance Indicators/Brand X")
# These can also be chained together
require(magrittr)
ds <- ds %>%
    mv(c("aware_x", "nps_x"), "Key Performance Indicators/Brand X") %>%
    mv(c("aware_y", "nps_y"), "Key Performance Indicators/Brand Y")
# Can combine with cd() and move things with relative paths
ds %>%
    cd("Key Performance Indicators/Brand X") %>%
    mv("nps_x", "../Net Promoters")
# Can combine with folder() to move objects to the same place as something else
ds %>% mv("nps_y", folder(ds$nps_x))
# Now let's put ds in a Project
projects() %>%
    mv(ds, "Brand Tracking Studies")

## End(Not run)

Omit missing categories

Description

Omit missing categories

Usage

na.omit(object, ...)

## S4 method for signature 'Categories'
na.omit(object, ...)

Arguments

Value

object with any categories that have missing: TRUE excluded

Dataset dimensions

Description

Dataset dimensions

Usage

ncol(x)

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

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

Arguments

Value

integer vector of length 2, indicating the number of rows and non-hidden variables in the dataset. Array subvariables are excluded from the column count.

See Also

base::dim()

Upload data to Crunch to make a new dataset

Description

This function creates a new dataset on the Crunch server with either a data.frame or similar object in your R session, a file, or a URL to a file. It captures available metadata from your R object and translates it into Crunch types.

Usage

newDataset(x, name = NULL, ..., project = defaultCrunchProject())

Arguments

Details

If you have an SPSS file, it is better specify the file name directly rather than first reading it into R. Uploading SPSS files directly to Crunch will preserve metadata that is stripped by the R import, regardless of the library used to read it into R.

If you have Triple-S files, you can import those directly to Crunch like you can with SPSS files. You should use the filename to the data file (ending in .asc or .dat) as the x argument and use the metadata file (ending in .sss or .xml) as the schema argument.

Value

If successful, an object of class CrunchDataset.

See Also

newDatasetFromFile(); newDatasetByColumn() for an alternate upload method.

Examples

## Not run: 
ds <- newDataset(mtcars, "cars", project = "studies/cars")
ds <- newDataset("mysurvey.sav", project = "https://app.crunch.io/api/projects/abc/")

## End(Not run)

Upload a data.frame column-by-column to make a new dataset

Description

Use this version if you have lots of variables, under 1M rows, perhaps backed by ff or other memory-mapped files, and time to kill. You really probably want newDataset() instead.

Usage

newDatasetByColumn(
  x,
  name = deparseAndFlatten(substitute(x), max_length = 40),
  ...
)

Arguments

Value

If successful, an object of class CrunchDataset.

See Also

newDataset()

Upload a file to Crunch to make a new dataset

Description

This function allows you to upload a .csv or .sav file directly to Crunch without first reading it into R. This is useful both because it preserves SPSS metadata that is lost when reading .sav files into R and because it is more efficient just to upload the file to the server.

Usage

newDatasetFromFile(x, name = basename(x), schema, ...)

Arguments

Details

You no longer need to call this function directly: you can call newDataset() and pass the filename or URL, and it will handle it for you, thereby saving you eight keystrokes.

Value

On success, an object of class CrunchDataset

See Also

newDataset()

Create an empty Crunch Deck

Description

Create an empty Crunch Deck

Usage

newDeck(dataset, name, ...)

Arguments

Value

The CrunchDeck that was created.

Import a fixture dataset for testing

Description

The crunch package includes some data for you to explore the features of the platform. Use this function to upload one to create a demo dataset.

Usage

newExampleDataset(name = "pets", project = defaultCrunchProject())

Arguments

Value

A new CrunchDataset entity.

Create a new filter

Description

This function creates a new filter for a CrunchDataset. You can achieve the same results by assigning into a dataset's filters catalog usingfilters(), but this may be a more natural way to think of the action, particularly when you want to do something with the filter entity after you create it.

Usage

newFilter(name, expression, catalog = NULL, ...)

Arguments

Value

A CrunchFilter object.

Create a new Multitable

Description

Multitables, or "banners" or "crossbreaks", define a set of variables or or query expressions to crosstab with as a unit. They are used in the Crunch web app to display tables side by side, as well as to define one dimension of a tab book.

Usage

newMultitable(formula, data, name, ...)

Arguments

Value

An object of class Multitable

See Also

stats::formula

Examples

## Not run: 
m <- newMultitable(~ gender + age4 + marstat, data = ds)
name(m) # [1] "gender + age4 + marstat"

## End(Not run)

Create a new folder

Description

This function creates a new project. You can achieve the same results by assigning into the projects catalog, but this may be a more natural way to think of the action, particularly when you want to do something with the project entity after you create it.

Usage

newProject(name, members = NULL, catalog = projects(), ...)

Arguments

Value

A ProjectFolder object.

See Also

mkdir()

Examples

## Not run: 
proj <- newProject("A project name")
# That is equivalent to doing:
p <- projects()
p[["A project name"]] <- list()
proj <- p[["A project name"]]

proj2 <- newProject("Another project", members = "you@yourco.com")
# That is equivalent to doing:
p[["Another project"]] <- list(members = "you@yourco.com")
proj <- p[["Another project"]]

## End(Not run)

Append a new slide to a Crunch Deck

Description

Append a new slide to a Crunch Deck

Usage

newSlide(
  deck,
  query = NULL,
  display_settings = list(),
  title = "",
  subtitle = "",
  filter = NULL,
  weight = NULL,
  viz_specs = NULL,
  transform = NULL,
  ...
)

Arguments

Value

CrunchSlide object

See Also

newMarkdownSlide for creating a markdown slide

Examples

## Not run: 
newSlide(
    main_deck,
    ~ cyl + wt,
    title = "Cyl and Weight",
    subtitle = "2017 Data"
)

# Grouped bar plot
newSlide(
    main_deck,
    ~ approval + age4,
    title = "Approval by age group",
    display_settings = list(
        vizType = "groupedBarPlot",
        showValueLabels = TRUE
    ),
    subtitle = "2017 Data"
)

# Horizontal stacked bars
newSlide(
    main_deck,
    ~ approval + age4,
    title = "Approval by age group",
    display_settings = list(
        vizType = "horizontalStackedBarPlot"
    ),
    subtitle = "2017 Data"
)

# A donut is only suitable for a single variable
newSlide(
    main_deck,
    ~ approval,
    title = "Approval of new feature",
    display_settings = list(
        vizType = "donut",
        showValueLabels = FALSE
    ),
    subtitle = "2017 Data"
)

# A Grouped bar plot with slide transformations to hide a category
newSlide(
    main_deck,
    ~ approval + age4,
    title = "Approval by age group",
    display_settings = list(
        vizType = "groupedBarPlot",
        showValueLabels = TRUE
    ),
    transform = list(rows_dimension = makeDimTransform(hide = "Neutral")),
    subtitle = "2017 Data"
)

# Example of advanced options being set:
# viz_specs can get quite long, see
# https://crunch.io/api/reference/#post-/datasets/-dataset_id-/decks/-deck_id-/slides/
viz_specs <- list(
    default = list(
        format = list(
            decimal_places = list(percentages = 0L, other = 2L),
            show_empty = FALSE
        )
    ),
    table = list(
        measures = c("col_percent", "pairwise_t_test"),
        page_layout = list(
            rows = list(
                top = list(),
                bottom = c("base_unweighted", "scale_mean", "significant_columns")
            ),
            measure_layout = "long"
        ),
        pairwise_comparison = list(sig_threshold = c(0.05, 0.01)),
        format = list(pval_colors = FALSE)
    )
)

newSlide(
    main_deck,
    ~categories(fav_array)+subvariables(fav_array),
    display_settings = list(viz_type = list(value = "table")),
    title = "custom slide",
    filter = filters(ds)[[1]],
    weight = ds$weight,
    viz_specs = viz_specs
)

# Can also specify `analyses` directly, which allows for very advanced use.
# `formulaToSlideQuery()` and `slideQueryEnv()` help describe the API
newSlide(
    main_deck,
    title = "custom slide",
    analyses = list(list(
        query = formulaToSlideQuery(~categories(fav_array)+subvariables(fav_array), ds),
        query_environment = slideQueryEnv(filter = filters(ds)[[1]]),
        display_settings = list(viz_type = list(value = "table")),
        viz_specs = viz_specs
    ))
)

## End(Not run)

Remove transformations from a CrunchCube

Description

Remove transformations from a CrunchCube

Usage

noTransforms(cube)

Arguments

Value

the CrunchCube with no transformations

Removing transforms

noTransforms() is useful if you don't want to see or use any transformations like Subtotals and Headings. This action only applies to the CrunchCube object in R: it doesn't actually change the variables on Crunch servers or the query that generated the CrunchCube.

Examples

## Not run: 
# A CrunchCube with a heading and subtotals
crtabs(~opinion, ds)
#               All opinions
#             Strongly Agree 23
#             Somewhat Agree 24
#                      Agree 47
# Neither Agree nor Disagree 18
#          Somewhat Disagree 16
#          Strongly Disagree 19
#                   Disagree 35

noTransforms(crtabs(~opinion, ds))
#             Strongly Agree             Somewhat Agree Neither Agree nor Disagree
#                         23                         24                         18
#          Somewhat Disagree          Strongly Disagree
#                         16                         19

## End(Not run)

See if there's a new version of the package on GitHub

Description

checkForNewVersion looks for a tagged version on GitHub and compares with the version number of the currently installed package. notifyIfNewVersion wraps it and displays a message if there is a new version. It is called in .onLoad().

Usage

notifyIfNewVersion(
  package = "crunch",
  github = "Crunch-io/rcrunch",
  installed.version = as.character(packageVersion(package))
)

checkForNewVersion(github, installed.version)

Arguments

Value

checkForNewVersion returns the version string if there is a new version, or NULL. notifyIfNewVersion returns nothing invisibly, called for its side effects.

Get and set VariableOrder

Description

The ordering methods allow you to get a VariableOrder on a CrunchDataset or on the VariableCatalog that the dataset contains.

Usage

ordering(x)

ordering(x) <- value

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

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

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

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

## S4 method for signature 'DatasetCatalog'
ordering(x)

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

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

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

Arguments

Details

Crunch datasets work with folders, and the ordering is deprecated. It is no longer possible to set the ordering of a variable catalog from rcrunch.

Value

ordering returns a VariableOrder object, while ⁠ordering<-⁠ sets the VariableOrder

Get and set the owner of a dataset

Description

Get and set the owner of a dataset

Usage

owner(x)

owner(x) <- value

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

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

Arguments

Value

The dataset.

See who owns these datasets

Description

See who owns these datasets

Usage

owners(x)

ownerNames(x)

Arguments

Value

For owners, the URLs of the users or projects that own these datasets. For ownerNames, their names.

Get the palettes from a crunch object

Description

CrunchDatasets have color palettes associated with them that can be used as default colors for dashboard tiles. One of them can be assigned the "default".

Usage

palettes(x)

defaultPalette(x, ...)

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

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

## S4 method for signature 'AnalyticPalettes'
defaultPalette(x, ...)

Arguments

Get the pending streams for a dataset

Description

Retrieves the number of pending messages. Use appendStream() to append all pending streamed rows to the dataset.

Usage

pendingStream(ds)

Arguments

Value

number of pending messages in the stream for the dataset

Get and set the primary key for a Crunch dataset

Description

A primary key is a variable in a dataset that has a unique value for every row. A variable must be either numeric or text type and have no duplicate or missing values. A primary key on a dataset causes appends to that dataset that have the rows with the same primary key value(s) as the first dataset to update the existing rows rather than inserting new ones.

Usage

pk(x)

pk(x) <- value

Arguments

Value

Getter returns the Variable object that is used as the primary key (NULL if there is no primary key); setter returns x duly modified.

Check a Crunch progress URL until it finishes

Description

You'll probably only call this function if progress polling times out and its error message tells you to call pollProgress to resume.

Usage

pollProgress(progress_url, wait = 0.5, error_handler = NULL)

Arguments

Value

The percent completed of the progress. Assuming the options(crunch.timeout) (default: 15 minutes) hasn't been reached, this will be 100. If the timeout is reached, it will be the last reported progress value.

Get and set the market size for Crunch datasets

Description

Crunch Datasets allow you to set a target population size in order to extrapolate population estimates from survey percentages. These functions let you work with the population size and magnitude.

Usage

popSize(x)

popMagnitude(x)

popSize(x) <- value

popMagnitude(x) <- value

setPopulation(x, size, magnitude)

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

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

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

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

## S4 method for signature 'CrunchDataset'
setPopulation(x, size, magnitude)

Arguments

Value

popSize and popMagnitude return the population size or magnitude. setPopulation returns the modified dataset.

Check if a dataset will make a good CrunchBox

Description