Package 'metasurvey.core'

Description

Pipe-friendly function to add a category to a Recipe object. Accepts either a category name (string) or a RecipeCategory object.

Usage

add_category(recipe, category, description = "")

Arguments

Value

The modified Recipe object (invisibly for piping).

See Also

remove_category, recipe_category, default_categories

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

r <- recipe(
  name = "Example", user = "Test",
  svy = survey_empty(type = "ech", edition = "2023"),
  description = "Example recipe"
)
r <- r |>
  add_category("labor_market", "Labor market indicators") |>
  add_category("income")

Description

Tidy wrapper for svy$add_recipe(recipe).

Usage

add_recipe(svy, recipe, bake = lazy_default())

Arguments

Value

The Survey object (invisibly), modified in place

See Also

Other recipes: Recipe-class, bake_recipes(), get_recipe(), harmonize(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

svy <- survey_empty(type = "ech", edition = "2023")
r <- recipe(
  name = "Example", user = "test",
  svy = svy, description = "Example"
)
svy <- add_recipe(svy, r)

Description

This function configures replicate weights (bootstrap, jackknife, etc.) that allow estimation of variance for complex statistics in surveys with complex sampling designs. It is essential for obtaining correct standard errors in population estimates.

Usage

add_replicate(
  weight,
  replicate_pattern,
  replicate_path = NULL,
  replicate_id = NULL,
  replicate_type
)

Arguments

Details

Replicate weights are essential for:

• Correctly estimating variance in complex designs

• Calculating appropriate confidence intervals

• Obtaining reliable coefficients of variation

• Performing valid statistical tests

The regex pattern must exactly match the replicate weight column names in the file. For example, if columns are named "wr001", "wr002", etc., use the pattern "wr\\d+".

This function is typically used within add_weight() for more complex weight configurations.

Value

List with replicate configuration that will be used by the sampling design for variance estimation

See Also

add_weight for complete weight configuration svrepdesign for replicate design in survey package load_survey where this configuration is used

Other weights: add_weight()

Examples

# Basic configuration with external file
annual_replicates <- add_replicate(
  weight = "pesoano",
  replicate_pattern = "wr\\d+",
  replicate_path = "bootstrap_weights_2023.xlsx",
  replicate_id = c("ID_HOGAR" = "ID"),
  replicate_type = "bootstrap"
)

# With replicates in same dataset
integrated_replicates <- add_replicate(
  weight = "main_weight",
  replicate_pattern = "rep_\\d{3}",
  replicate_type = "jackknife"
)

# Use within add_weight
weight_config <- add_weight(
  annual = add_replicate(
    weight = "pesoano",
    replicate_pattern = "wr\\d+",
    replicate_path = "bootstrap_annual.xlsx",
    replicate_id = c("numero" = "ID_HOGAR"),
    replicate_type = "bootstrap"
  ),
  monthly = "pesomes"
)

Description

This function creates a weight structure that allows specifying different weight variables according to estimation periodicity. It is essential for proper functioning of workflows with multiple temporal estimation types.

Usage

add_weight(monthly = NULL, annual = NULL, quarterly = NULL, biannual = NULL)

Arguments

Details

This function is fundamental for surveys that require different weights according to temporal estimation type. For example, Uruguay's ECH has specific weights for monthly, quarterly, and annual estimations.

Each parameter can be:

• A simple string with the weight variable name

• A replicate structure created with add_replicate() for bootstrap or jackknife estimations

Weights are automatically selected in workflow() according to the specified estimation_type parameter.

Value

Named list with weight configuration by periodicity, which will be used by load_survey and workflow to automatically select the appropriate weight

See Also

add_replicate to configure bootstrap/jackknife replicates load_survey where this configuration is used workflow that automatically selects weights

Other weights: add_replicate()

Examples

# Basic configuration with simple weight variables
ech_weights <- add_weight(
  monthly = "pesomes",
  quarterly = "pesotri",
  annual = "pesoano"
)

# With bootstrap replicates for variance estimation
weights_with_replicates <- add_weight(
  monthly = add_replicate(
    weight = "pesomes",
    replicate_pattern = "wr\\d+",
    replicate_path = "monthly_replicate_weights.xlsx",
    replicate_id = c("ID_HOGAR" = "ID"),
    replicate_type = "bootstrap"
  ),
  annual = "pesoano"
)

Description

Bake recipes

Usage

bake_recipes(svy)

Arguments

Value

Survey object with all recipes applied

See Also

Other recipes: Recipe-class, add_recipe(), get_recipe(), harmonize(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

dt <- data.table::data.table(id = 1:20, x = rnorm(20), w = runif(20, 0.5, 2))
svy <- Survey$new(
  data = dt, edition = "2023", type = "demo",
  psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
r <- recipe(
  name = "Demo", user = "test", svy = svy,
  description = "Demo recipe"
)
svy <- add_recipe(svy, r)
processed <- bake_recipes(svy)

Description

Iterates over all pending (lazy) steps attached to a Survey or RotativePanelSurvey and executes them sequentially, mutating the underlying data.table. Each step is validated before execution (checks that required variables exist).

Usage

bake_steps(svy)

Arguments

Details

Steps are executed in the order they were added. Each step's expressions can reference variables created by previous steps.

For RotativePanelSurvey objects, steps are applied to both the implantation and all follow-up surveys.

Value

The same object with all steps materialized in the data and each step marked as bake = TRUE.

See Also

Other steps: get_steps(), step_collapse(), step_compute(), step_filter(), step_join(), step_quantile(), step_recode(), step_remove(), step_rename(), step_validate(), view_graph()

Examples

dt <- data.table::data.table(id = 1:5, age = c(15, 30, 45, 50, 70), w = 1)
svy <- Survey$new(
  data = dt, edition = "2023", type = "test",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
svy <- step_compute(svy, age2 = age * 2)
svy <- bake_steps(svy)
get_data(svy)

Description

Pretty-prints the sampling design configuration for each estimation type in a Survey object, showing PSU, strata, weights, and other design elements in a color-coded, readable format.

Usage

cat_design(self)

Arguments

Details

This function displays design information including:

• Primary Sampling Units (PSU/clusters)

• Stratification variables

• Weight variables for each estimation type

• Finite Population Correction (FPC) if used

• Calibration formulas if applied

• Overall design type classification

Output is color-coded for better readability in supporting terminals.

Value

Invisibly returns NULL; called for side effect of printing design info

See Also

cat_design_type for design type classification

Other survey-objects: Survey, cat_design_type(), get_data(), get_metadata(), has_design(), has_recipes(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

dt <- data.table::data.table(id = 1:20, x = rnorm(20), w = runif(20, 0.5, 2))
svy <- Survey$new(
  data = dt, edition = "2023", type = "demo",
  psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
cat_design(svy)

Description

Cast design type from survey

Usage

cat_design_type(self, design_name)

Arguments

Value

Character string describing the design type, or "None".

See Also

Other survey-objects: Survey, cat_design(), get_data(), get_metadata(), has_design(), has_recipes(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

dt <- data.table::data.table(id = 1:20, x = rnorm(20), w = runif(20, 0.5, 2))
svy <- Survey$new(
  data = dt, edition = "2023", type = "demo",
  psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
svy$ensure_design()
cat_design_type(svy, "annual")

Description

Pipe-friendly function to certify a Recipe at a given quality level.

Usage

certify_recipe(recipe, user, level)

Arguments

Value

The modified Recipe object.

See Also

recipe_certification, recipe_user

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

r <- recipe(
  name = "Example", user = "Test",
  svy = survey_empty(type = "ech", edition = "2023"),
  description = "Example recipe"
)
inst <- recipe_user("IECON", type = "institution")
r <- r |> certify_recipe(inst, "official")

Description

Returns a list of standard built-in categories for recipe classification.

Usage

default_categories()

Value

List of RecipeCategory objects

See Also

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

cats <- default_categories()
vapply(cats, function(c) c$name, character(1))

Description

Evaluate estimation with Coefficient of Variation

Usage

evaluate_cv(cv)

Arguments

Value

Character string with the quality category (e.g. "Excellent", "Good"), or NA when the CV is not defined (e.g. a zero estimate, where CV = 0/0).

See Also

Other workflows: RecipeWorkflow-class, print.RecipeWorkflow(), publish_workflow(), read_workflow(), save_workflow(), workflow(), workflow_from_list(), workflow_table()

Examples

evaluate_cv(3) # "Excellent"
evaluate_cv(12) # "Good"
evaluate_cv(30) # "Use with caution"
evaluate_cv(NaN) # NA

Description

Extracts subsets of surveys from a RotativePanelSurvey object based on temporal criteria. Allows obtaining surveys for different types of analysis (monthly, quarterly, annual) respecting the rotating panel's temporal structure.

Usage

extract_surveys(
  RotativePanelSurvey,
  index = NULL,
  monthly = NULL,
  annual = NULL,
  quarterly = NULL,
  biannual = NULL,
  use.parallel = FALSE
)

Arguments

Details

This function is essential for working with rotating panels because:

• Enables periodicity-based analysis: Extract data for different types of temporal estimations

• Preserves temporal structure: Respects temporal relationships between different panel waves

• Optimizes memory: Only loads surveys needed for the analysis

• Facilitates comparisons: Extract specific periods for comparative analysis

• Supports parallelization: For operations with large data volumes

Extraction criteria are interpreted according to survey frequency:

• For monthly ECH: monthly=c(1,3,6) extracts January, March and June

• For annual analysis: annual=1 typically extracts the first available year

• For quarterly analysis: quarterly=c(1,4) extracts Q1 and Q4

If no criteria are specified, the function returns the implantation survey with a warning.

Value

A list of Survey objects matching the specified criteria, or a single Survey object if a single index is specified

See Also

load_panel_survey for loading rotating panels get_implantation for obtaining implantation data get_follow_up for obtaining follow-up data workflow for using extracted surveys in analysis

Other panel-surveys: PoolSurvey, RotativePanelSurvey, get_follow_up(), get_implantation()

Examples

# Panels usually come from load_panel_survey(); here we build a
# small one in memory
mk <- function(edition) {
  Survey$new(
    data = data.table::data.table(id = 1:5, w = 1),
    edition = edition, type = "ech", psu = NULL,
    engine = "data.table", weight = add_weight(monthly = "w")
  )
}
panel <- RotativePanelSurvey$new(
  implantation = mk("2023-01-01"),
  follow_up = list(mk("2023-01-01"), mk("2023-02-01"), mk("2023-03-01")),
  type = "ech", default_engine = "data.table",
  steps = list(), recipes = list(), workflows = list(), design = NULL
)

# Extract follow-up surveys by index
ech_first <- extract_surveys(panel, index = 1)
ech_first_two <- extract_surveys(panel, index = c(1, 2))

## Not run: 
# Not run: interval extraction needs a panel loaded from the real
# microdata files (editions must carry the survey time pattern)
ech_q1 <- extract_surveys(panel_ech, monthly = c(1, 2, 3))
ech_annual <- extract_surveys(panel_ech, annual = 1)
results <- workflow(
  survey = extract_surveys(panel_ech, quarterly = c(1, 2)),
  svymean(~unemployed, na.rm = TRUE),
  estimation_type = "quarterly"
)

## End(Not run)

Description

Extract time pattern

Usage

extract_time_pattern(svy_edition)

Arguments

Value

List with components: periodicity, year, month (when applicable).

See Also

Other survey-loading: group_dates(), load_panel_survey(), load_survey(), load_survey_example(), validate_time_pattern()

Examples

# Annual edition
extract_time_pattern("2023")

# Monthly edition
extract_time_pattern("2023-06")

Description

Filter recipes in the active backend by survey type, edition, category, or certification level.

Usage

filter_recipes(
  survey_type = NULL,
  edition = NULL,
  category = NULL,
  certification_level = NULL,
  topic = NULL
)

Arguments

Value

List of matching Recipe objects.

See Also

search_recipes, rank_recipes

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_backend("local", path = tempfile(fileext = ".json"))
ech_recipes <- filter_recipes(survey_type = "ech")
length(ech_recipes)

Description

Filter workflows in the active backend by survey type, edition, recipe ID, or certification level.

Usage

filter_workflows(
  survey_type = NULL,
  edition = NULL,
  recipe_id = NULL,
  certification_level = NULL
)

Arguments

Value

List of matching RecipeWorkflow objects.

See Also

search_workflows, find_workflows_for_recipe

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_workflow_backend("local", path = tempfile(fileext = ".json"))
ech_wf <- filter_workflows(survey_type = "ech")
length(ech_wf)

Description

Cross-reference query: find all workflows that reference a given recipe ID.

Usage

find_workflows_for_recipe(recipe_id)

Arguments

Value

List of RecipeWorkflow objects that reference this recipe.

See Also

filter_workflows

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_workflow_backend("local", path = tempfile(fileext = ".json"))
wfs <- find_workflows_for_recipe("recipe_001")
length(wfs)

Description

Returns the currently configured recipe backend. Defaults to "api" if not configured.

Usage

get_backend()

Value

RecipeBackend object

See Also

Other backends: get_workflow_backend(), set_backend(), set_workflow_backend()

Examples

set_backend("local", path = tempfile(fileext = ".json"))
backend <- get_backend()
backend

Description

Get data from survey

Usage

get_data(svy)

Arguments

Value

A data.table (or data.frame) containing the survey microdata.

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_metadata(), has_design(), has_recipes(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

dt <- data.table::data.table(
  id = 1:5, age = c(25, 30, 45, 50, 60),
  w = rep(1, 5)
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "ech",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
head(get_data(svy))

Description

Retrieves the currently configured engine for loading surveys from system options or environment variables.

Usage

get_engine()

Value

Character vector with the name of the configured engine.

See Also

Other options: lazy_default(), set_engine(), set_lazy_processing(), set_use_copy(), show_engines(), use_copy_default()

Examples

get_engine()

Description

Extracts one or more follow-up surveys (waves after the implantation) from a RotativePanelSurvey object. Follow-up surveys represent subsequent data collections and are essential for longitudinal and temporal change analysis.

Usage

get_follow_up(
  RotativePanelSurvey,
  index = seq_along(RotativePanelSurvey$follow_up)
)

Arguments

Details

Follow-up surveys are fundamental in rotating panels because:

• Enable longitudinal analysis: Track the same units over time

• Capture temporal changes: Evolution of economic, social, and demographic variables

• Maintain representativeness: Each wave preserves population representativeness through controlled rotation

• Optimize resources: Reuse information from previous waves to reduce collection costs

• Facilitate comparisons: Consistent temporal structure for trend analysis

In rotating panels like ECH:

• Each follow-up wave covers a specific period (monthly/quarterly)

• Units rotate gradually maintaining temporal overlap

• Indices correspond to the chronological collection order

• Each follow-up maintains methodological consistency with implantation

Value

A list of Survey objects corresponding to the specified follow-up surveys. If a single index is specified, returns a list with one element

See Also

get_implantation for obtaining the implantation survey extract_surveys for extracting surveys by temporal criteria load_panel_survey for loading rotating panels workflow for analysis with follow-up surveys

Other panel-surveys: PoolSurvey, RotativePanelSurvey, extract_surveys(), get_implantation()

Examples

impl <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
fu1 <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023_01", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
fu2 <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023_02", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
panel <- RotativePanelSurvey$new(
  implantation = impl, follow_up = list(fu1, fu2),
  type = "test", default_engine = "data.table",
  steps = list(), recipes = list(), workflows = list(), design = NULL
)
get_follow_up(panel, index = 1)
get_follow_up(panel)

Description

Extracts the implantation (baseline) survey from a RotativePanelSurvey object. The implantation survey represents the first data collection wave and is essential for establishing the baseline and structural characteristics of the panel.

Usage

get_implantation(RotativePanelSurvey)

Arguments

Details

The implantation survey is special in a rotating panel because:

• Establishes the baseline: Defines initial characteristics of all panel units

• Contains the full sample: Includes all units that will participate in the different panel waves

• Defines temporal structure: Establishes rotation and follow-up patterns

• Configures metadata: Contains information about periodicity, key variables, and stratification

• Serves as tracking reference: Basis for unit tracking in subsequent waves

This function is essential for analysis requiring:

• Temporal comparisons from the baseline

• Analysis of the complete panel structure

• Configuration of longitudinal models

• Evaluation of sampling design quality

Value

A Survey object containing the implantation survey with all its metadata, data, and design configuration

See Also

get_follow_up for obtaining follow-up surveys extract_surveys for extracting multiple surveys by criteria load_panel_survey for loading rotating panels workflow for analysis with the implantation survey

Other panel-surveys: PoolSurvey, RotativePanelSurvey, extract_surveys(), get_follow_up()

Examples

impl <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
fu <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023_01", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
panel <- RotativePanelSurvey$new(
  implantation = impl, follow_up = list(fu),
  type = "test", default_engine = "data.table",
  steps = list(), recipes = list(), workflows = list(), design = NULL
)
get_implantation(panel)

Description

Display survey metadata on the console. This function is the shared implementation behind the print() methods of Survey, RotativePanelSurvey and PoolSurvey, which is why it writes with cat() rather than through the metasurvey.verbose-gated message helper.

Usage

get_metadata(self)

Arguments

Value

NULL (called for side effect: prints metadata to console).

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_data(), has_design(), has_recipes(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

dt <- data.table::data.table(
  id = 1:5, age = c(25, 30, 45, 50, 60),
  w = rep(1, 5)
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "ech",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
get_metadata(svy)

Description

This function retrieves data transformation recipes from the metasurvey repository or API, based on specific criteria such as survey type, edition, and topic. It is the primary way to access predefined and community-validated recipes.

Usage

get_recipe(
  svy_type = NULL,
  svy_edition = NULL,
  topic = NULL,
  allowMultiple = TRUE
)

Arguments

Details

This function is essential for:

• Accessing official recipes: Get validated and maintained recipes by specialized teams

• Reproducibility: Ensure different users apply the same standard transformations

• Automation: Integrate recipes into automatic pipelines

• Collaboration: Share methodologies between teams and organizations

• Versioning: Access different recipe versions according to edition

The function queries the metasurvey API to retrieve recipes. Internet connection is required. If the API is unavailable or you need to work offline:

Working Offline:

• Don't call get_recipe() - work directly with steps

• Set options(metasurvey.skip_recipes = TRUE) to disable API calls

• Load recipes from local files using read_recipe()

• Create custom recipes with recipe()

Search criteria are combined with AND operator, so all specified criteria must match for a recipe to be returned.

Value

Recipe object or list of Recipe objects according to the specified criteria and the value of allowMultiple

See Also

recipe to create custom recipes save_recipe to save recipes locally read_recipe to read recipes from file publish_recipe to publish recipes to the repository load_survey where recipes are used

Other recipes: Recipe-class, add_recipe(), bake_recipes(), harmonize(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

# Query a local backend (works offline)
old <- set_backend("local", path = tempfile(fileext = ".json"))

r <- Recipe$new(
  name = "labor_market", edition = "2023", survey_type = "ech",
  default_engine = "data.table", depends_on = list(),
  user = "demo", description = "Example recipe",
  steps = list("step_compute(., active = e27 >= 14)"),
  id = "r_demo"
)
publish_recipe(r)

# Get recipes for ECH 2023
ech_recipes <- get_recipe(svy_type = "ech", svy_edition = "2023")

# Get a single recipe
one_recipe <- get_recipe(
  svy_type = "ech", svy_edition = "2023",
  allowMultiple = FALSE
)

# Restore previous backend
options(metasurvey.backend = old)

Description

Get steps from survey

Usage

get_steps(svy)

Arguments

Value

List of Step objects

See Also

Other steps: bake_steps(), step_collapse(), step_compute(), step_filter(), step_join(), step_quantile(), step_recode(), step_remove(), step_rename(), step_validate(), view_graph()

Examples

dt <- data.table::data.table(
  id = 1:5, age = c(25, 30, 45, 50, 60),
  w = rep(1, 5)
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "ech",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
svy <- step_compute(svy, age2 = age * 2)
get_steps(svy) # list of Step objects

Description

Returns the currently configured workflow backend. Defaults to "local" if not configured.

Usage

get_workflow_backend()

Value

WorkflowBackend object

See Also

Other backends: get_backend(), set_backend(), set_workflow_backend()

Examples

backend <- get_workflow_backend()

Description

Group dates

Usage

group_dates(dates, type = c("monthly", "quarterly", "biannual"))

Arguments

Value

Integer vector of group indices (e.g. 1-12 for monthly, 1-4 for quarterly).

See Also

Other survey-loading: extract_time_pattern(), load_panel_survey(), load_survey(), load_survey_example(), validate_time_pattern()

Examples

dates <- as.Date(c(
  "2023-01-15", "2023-04-20",
  "2023-07-10", "2023-11-05"
))
group_dates(dates, "quarterly")
group_dates(dates, "biannual")

Description

For each survey in the list, fetches matching recipes from the active backend (by survey type and edition), sorts them by dependency order, applies them via bake_recipes, and assembles the results into a PoolSurvey ready for workflow.

Usage

harmonize(
  surveys,
  survey_type = NULL,
  topic = NULL,
  category = NULL,
  certification_level = NULL,
  grouping = "annual",
  group_name = "series",
  .verbose = getOption("metasurvey.verbose", TRUE)
)

Arguments

Details

The function performs the following steps for each survey:

1. Calls filter_recipes with the survey's type and edition (plus optional category/certification filters).

2. Sorts matching recipes using topological sort on depends_on_recipes.

3. Attaches recipes via add_recipe and applies them with bake_recipes.

If no recipes are found for a survey, it is included in the pool unchanged (with a warning).

Value

A PoolSurvey object containing the harmonized surveys, structured as list(<grouping> = list(<group_name> = list(svy1, svy2, ...))).

See Also

filter_recipes, bake_recipes, PoolSurvey, workflow

Other recipes: Recipe-class, add_recipe(), bake_recipes(), get_recipe(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

# Set up a local backend with a temp file
old <- set_backend("local", path = tempfile(fileext = ".json"))

# Create a small survey and a recipe
dt <- data.table::data.table(
  id = 1:10, x = 1:10, w = rep(1, 10)
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "test",
  psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
r <- Recipe$new(
  name = "demo", edition = "2023", survey_type = "test",
  default_engine = "data.table", depends_on = list(),
  user = "demo", description = "demo recipe",
  steps = list("step_compute(., z = x * 2)"),
  id = "demo_recipe"
)
publish_recipe(r)

pool <- harmonize(list(svy), .verbose = FALSE)

# Restore backend
options(metasurvey.backend = old)

Description

Check if survey has a design

Usage

has_design(svy)

Arguments

Value

Logical.

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_data(), get_metadata(), has_recipes(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

svy <- survey_empty(type = "test", edition = "2023")
has_design(svy) # FALSE

Description

Check if survey has recipes

Usage

has_recipes(svy)

Arguments

Value

Logical.

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_data(), get_metadata(), has_design(), has_steps(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

svy <- survey_empty(type = "test", edition = "2023")
has_recipes(svy) # FALSE

Description

Check if survey has steps

Usage

has_steps(svy)

Arguments

Value

Logical.

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_data(), get_metadata(), has_design(), has_recipes(), is_baked(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

svy <- survey_empty(type = "test", edition = "2023")
has_steps(svy) # FALSE

Description

Returns TRUE when every step attached to the survey has been executed (bake == TRUE), or when there are no steps.

Usage

is_baked(svy)

Arguments

Value

Logical.

See Also

Other survey-objects: Survey, cat_design(), cat_design_type(), get_data(), get_metadata(), has_design(), has_recipes(), has_steps(), set_data(), survey_empty(), survey_to_data_frame(), survey_to_datatable(), survey_to_tibble()

Examples

svy <- survey_empty(type = "test", edition = "2023")
is_baked(svy) # TRUE (no steps)

Description

Lazy processing

Usage

lazy_default()

Value

Logical indicating the current lazy processing setting.

See Also

Other options: get_engine(), set_engine(), set_lazy_processing(), set_use_copy(), show_engines(), use_copy_default()

Examples

# Check current lazy processing default
lazy_default()

Description

List all recipes from the active backend.

Usage

list_recipes()

Value

List of all Recipe objects.

See Also

search_recipes, filter_recipes

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_backend("local", path = tempfile(fileext = ".json"))
all <- list_recipes()
length(all)

Description

List all workflows from the active workflow backend.

Usage

list_workflows()

Value

List of all RecipeWorkflow objects.

See Also

search_workflows, filter_workflows

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_workflow_backend("local", path = tempfile(fileext = ".json"))
all <- list_workflows()
length(all)

Description

Read panel survey files from different formats and create a RotativePanelSurvey object

Usage

load_panel_survey(
  path_implantation,
  path_follow_up,
  svy_type,
  svy_weight_implantation,
  svy_weight_follow_up,
  svy_strata = NULL,
  ...
)

Arguments

Value

RotativePanelSurvey object

See Also

Other survey-loading: extract_time_pattern(), group_dates(), load_survey(), load_survey_example(), validate_time_pattern()

Examples

# Build a small panel from temporary CSV files
impl_dir <- tempfile("panel_")
follow_dir <- file.path(impl_dir, "follow_up")
dir.create(follow_dir, recursive = TRUE)
dt <- data.table::data.table(id = 1:20, income = runif(20), w = 1)
data.table::fwrite(dt, file.path(impl_dir, "ech_2023.csv"))
data.table::fwrite(dt, file.path(follow_dir, "ech_2023_01.csv"))
data.table::fwrite(dt, file.path(follow_dir, "ech_2023_02.csv"))

panel <- load_panel_survey(
  path_implantation = file.path(impl_dir, "ech_2023.csv"),
  path_follow_up = follow_dir,
  svy_type = "ech",
  svy_weight_implantation = add_weight(annual = "w"),
  svy_weight_follow_up = add_weight(monthly = "w")
)
panel
unlink(impl_dir, recursive = TRUE)

## Not run: 
# Not run: requires the full ECH 2023 microdata and bootstrap
# replicate-weight files on disk
path_dir <- here::here("example-data", "ech", "ech_2023")
ech_2023 <- load_panel_survey(
  path_implantation = file.path(
    path_dir,
    "ECH_implantacion_2023.csv"
  ),
  path_follow_up = file.path(
    path_dir,
    "seguimiento"
  ),
  svy_type = "ECH_2023",
  svy_weight_implantation = add_weight(
    annual = "W_ANO"
  ),
  svy_weight_follow_up = add_weight(
    monthly = add_replicate(
      "W",
      replicate_path = file.path(
        path_dir,
        c(
          "Pesos replicados Bootstrap mensuales enero_junio 2023",
          "Pesos replicados Bootstrap mensuales julio_diciembre 2023"
        ),
        c(
          "Pesos replicados mensuales enero_junio 2023",
          "Pesos replicados mensuales Julio_diciembre 2023"
        )
      ),
      replicate_id = c("ID" = "ID"),
      replicate_pattern = "wr[0-9]+",
      replicate_type = "bootstrap"
    )
  )
)

## End(Not run)

Description

This function reads survey files in multiple formats and creates a Survey object with all necessary metadata for subsequent analysis. Supports various survey types with specific configurations for each one.

Usage

load_survey(
  path = NULL,
  svy_type = NULL,
  svy_edition = NULL,
  svy_weight = NULL,
  svy_psu = NULL,
  svy_strata = NULL,
  ...,
  bake = FALSE,
  recipes = NULL
)

Arguments

Details

The function automatically detects file format and uses the appropriate reader. For each survey type, it applies specific configurations such as standard variables, data types, and validations.

When bake=TRUE is specified, recipes are applied immediately after loading the data, creating an analysis-ready object.

If no path is provided, an empty Survey object is created that can be used to build step pipelines without initial data.

Value

Survey object with structure:

• data: Survey data

• metadata: Information about type, edition, weights

• steps: History of applied transformations

• recipes: Available recipes

• design: Sample design information

See Also

add_weight to specify weights get_recipe to get available recipes load_survey_example to load example data load_panel_survey for panel surveys

Other survey-loading: extract_time_pattern(), group_dates(), load_panel_survey(), load_survey_example(), validate_time_pattern()

Examples

# Load the ECH sample bundled with the package
ech_sample <- load_survey(
  path = system.file(
    "extdata", "ech_2023_sample.csv",
    package = "metasurvey.core"
  ),
  svy_type = "ech",
  svy_edition = "2023",
  svy_weight = add_weight(annual = "W_ANO")
)
ech_sample

## Not run: 
# Not run: needs full local microdata files and a configured backend
ech_2023 <- load_survey(
  path = "data/ech_2023.csv",
  svy_type = "ech",
  svy_edition = "2023",
  svy_weight = add_weight(annual = "pesoano"),
  recipes = get_recipe("ech", "2023"),
  bake = TRUE
)

# Load monthly survey from STATA format
ech_january <- load_survey(
  path = "data/ech_202301.dta",
  svy_type = "ech",
  svy_edition = "202301",
  svy_weight = add_weight(monthly = "pesomes")
)

## End(Not run)

Description

Downloads and loads example survey data from the metasurvey data repository. This function provides access to sample datasets for testing and demonstration purposes, including ECH (Continuous Household Survey) and other survey types.

Usage

load_survey_example(svy_type, svy_edition)

Arguments

Details

This function downloads example data from the official metasurvey data repository on GitHub. The data is cached locally in a temporary file to avoid repeated downloads in the same session.

Available survey types and editions can be found at: https://github.com/metasurveyr/metasurvey_data

Value

Character string with the path to the downloaded CSV file containing the example survey data

See Also

load_survey for loading the downloaded data

Other survey-loading: extract_time_pattern(), group_dates(), load_panel_survey(), load_survey(), validate_time_pattern()

Examples

## Not run: 
# Not run: downloads data from GitHub (requires internet access)
ech_path <- load_survey_example("ech", "2023")

# Use with load_survey
ech_data <- load_survey(
  path = load_survey_example("ech", "2023"),
  svy_type = "ech",
  svy_edition = "2023"
)

## End(Not run)

Description

All errors and warnings signalled by metasurvey.core are classed conditions: they carry a domain-specific subclass plus the package-wide base class ("metasurvey_error" or "metasurvey_warning"), so you can handle them with tryCatch()/withCallingHandlers() without matching message text.

Value

No return value. This topic documents the condition classes signalled by metasurvey.core; catch them with tryCatch() or withCallingHandlers() as shown in the examples.

Error classes

Every error carries "metasurvey_error" plus one of:

metasurvey_input_error

An argument of an exported function failed input validation (wrong type, wrong class, missing value).

metasurvey_error_step

A step could not be created or baked (unknown step type, missing variables, failed step_validate() checks with .action = "stop").

metasurvey_error_recipe

A recipe is invalid or cannot be applied (missing metadata, unmet variable dependencies, dependency cycles).

metasurvey_error_workflow

A workflow object or a workflow() estimation is invalid.

metasurvey_error_panel

A rotating-panel operation failed (inconsistent waves, invalid extraction).

metasurvey_error_survey

A survey-level operation failed (design construction, weight or replicate specification).

metasurvey_error_engine

The requested processing engine is not supported or not installed.

metasurvey_error_io

A file could not be loaded (unsupported format, missing reader package, failed download).

metasurvey_error_backend

A recipe/workflow backend operation failed.

metasurvey_error_backend_unavailable

The "api" backend was selected but no provider is registered (also carries metasurvey_error_backend). Install a provider package such as metasurvey.explorer.backend.

Warning classes

Every warning carries "metasurvey_warning" plus one of metasurvey_warning_step, metasurvey_warning_recipe, metasurvey_warning_workflow, metasurvey_warning_panel, metasurvey_warning_survey, metasurvey_warning_engine or metasurvey_warning_backend, following the same domains as the error classes.

Examples

# Catch any metasurvey error by its base class
tryCatch(
  set_engine("not-an-engine"),
  metasurvey_error = function(e) message("caught: ", conditionMessage(e))
)

# Or target a specific domain
tryCatch(
  set_engine("not-an-engine"),
  metasurvey_error_engine = function(e) "engine problem"
)

Description

All behavior toggles of metasurvey.core are controlled through R options() under the metasurvey. prefix. None of them needs to be set explicitly: every option has a working default.

Value

No return value. This topic documents the global options recognized by metasurvey.core and their defaults.

Options

metasurvey.engine

Character. Data-processing engine used when loading surveys. Default "data.table" (set on load). Change it with set_engine(); see show_engines() for the available engines.

metasurvey.lazy_processing

Logical, default TRUE. When TRUE, ⁠step_*()⁠ functions record transformations without executing them until bake_steps() is called. Set with set_lazy_processing(); query with lazy_default().

metasurvey.use_copy

Logical, default TRUE. When TRUE, steps operate on a copy of the survey so the original object is never modified in place. Set with set_use_copy(); query with use_copy_default().

metasurvey.verbose

Logical, default TRUE. Gates all informational messages emitted by the package. Set it to FALSE to silence them; errors and warnings are not affected.

metasurvey.backend

A RecipeBackend object holding the active recipe backend. Unset by default (an in-memory local backend is used). Configure with set_backend(); query with get_backend().

metasurvey.workflow_backend

A WorkflowBackend object holding the active workflow backend. Unset by default (an in-memory local backend is used). Configure with set_workflow_backend(); query with get_workflow_backend().

metasurvey.backend_provider

A function ⁠(op, args)⁠ that implements the remote ("api") backend. Default NULL: core has no network access, and selecting the "api" backend without a registered provider signals a metasurvey_error_backend_unavailable error (see metasurvey_conditions). Companion packages such as metasurvey.explorer.backend register the provider on load.

metasurvey.skip_recipes

Logical, default FALSE. When TRUE, get_recipe() skips every backend lookup and returns NULL with a warning: useful for fully offline runs.

Examples

# Silence informational messages for a session
old <- options(metasurvey.verbose = FALSE)
options(old)

# Current engine and laziness
getOption("metasurvey.engine")
lazy_default()

Description

This class represents a collection of surveys grouped by specific periods (e.g., monthly, quarterly, annual). It provides methods to access and manipulate the grouped surveys.

Value

An object of class PoolSurvey.

Public fields

Methods

Public methods

• PoolSurvey$new()

• PoolSurvey$get_surveys()

• PoolSurvey$print()

• PoolSurvey$clone()

PoolSurvey$new()

Initializes a new instance of the PoolSurvey class.

Usage

PoolSurvey$new(surveys)

Arguments

PoolSurvey$get_surveys()

Retrieves surveys for a specific period.

Usage

PoolSurvey$get_surveys(period = NULL)

Arguments

Returns

A list of surveys for the specified period.

PoolSurvey$print()

Prints metadata about the PoolSurvey object.

Usage

PoolSurvey$print()

PoolSurvey$clone()

The objects of this class are cloneable with this method.

Usage

PoolSurvey$clone(deep = FALSE)

Arguments

See Also

Other panel-surveys: RotativePanelSurvey, extract_surveys(), get_follow_up(), get_implantation()

Examples

s1 <- Survey$new(
  data = data.table::data.table(id = 1:3, w = 1),
  edition = "2023", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
s2 <- Survey$new(
  data = data.table::data.table(id = 4:6, w = 1),
  edition = "2023", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
pool <- PoolSurvey$new(list(annual = list("group1" = list(s1, s2))))

Description

Print provenance information

Usage

## S3 method for class 'metasurvey_provenance'
print(x, ...)

Arguments

Value

Invisibly returns x.

See Also

Other provenance: print.metasurvey_provenance_diff(), provenance(), provenance_diff(), provenance_to_json()

Examples

s <- survey_empty("ech", "2023")
s <- set_data(s, data.table::data.table(age = 18:65))
s <- step_compute(s, age2 = age * 2)
s <- bake_steps(s)
print(provenance(s))

Description

Print provenance diff

Usage

## S3 method for class 'metasurvey_provenance_diff'
print(x, ...)

Arguments

Value

Invisibly returns x.

See Also

Other provenance: print.metasurvey_provenance(), provenance(), provenance_diff(), provenance_to_json()

Examples

s1 <- survey_empty("ech", "2022")
s1 <- set_data(s1, data.table::data.table(age = 18:65))
s1 <- step_compute(s1, age2 = age * 2)
s1 <- bake_steps(s1)

s2 <- survey_empty("ech", "2023")
s2 <- set_data(s2, data.table::data.table(age = 20:70))
s2 <- step_compute(s2, age2 = age * 2)
s2 <- bake_steps(s2)

diff_result <- provenance_diff(provenance(s1), provenance(s2))
print(diff_result)

Description

Displays a formatted recipe card showing metadata, required variables, pipeline steps, and produced variables.

Usage

## S3 method for class 'Recipe'
print(x, ...)

Arguments

Value

Invisibly returns the Recipe object

See Also

Other recipes: Recipe-class, add_recipe(), bake_recipes(), get_recipe(), harmonize(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

rec <- Recipe$new(
  id = "r1", name = "Example", user = "tester",
  edition = "2023", survey_type = "test",
  default_engine = "data.table", depends_on = list(),
  description = "Demo recipe", steps = list()
)
print(rec)

Description

Print method for RecipeWorkflow objects

Usage

## S3 method for class 'RecipeWorkflow'
print(x, ...)

Arguments

Value

Invisibly returns the object

See Also

Other workflows: RecipeWorkflow-class, evaluate_cv(), publish_workflow(), read_workflow(), save_workflow(), workflow(), workflow_from_list(), workflow_table()

Examples

wf <- RecipeWorkflow$new(
  id = "w1", name = "Example Workflow", user = "tester",
  edition = "2023", survey_type = "test",
  recipe_ids = "r1",
  calls = list(), description = "Demo"
)
print(wf)

Description

Returns the provenance metadata recording the full data lineage: source file, step history with row counts, and environment info.

Usage

provenance(x, ...)

## S3 method for class 'Survey'
provenance(x, ...)

## S3 method for class 'data.table'
provenance(x, ...)

## Default S3 method:
provenance(x, ...)

Arguments

Value

A metasurvey_provenance list, or NULL if no provenance is available.

See Also

Other provenance: print.metasurvey_provenance(), print.metasurvey_provenance_diff(), provenance_diff(), provenance_to_json()

Examples

svy <- Survey$new(
  data = data.table::data.table(id = 1:10, age = 20:29, w = 1),
  edition = "2023", type = "test", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
provenance(svy)

Description

Shows differences between two provenance records, useful for comparing processing across survey editions.

Usage

provenance_diff(prov1, prov2)

Arguments

Value

A metasurvey_provenance_diff list with detected differences.

See Also

Other provenance: print.metasurvey_provenance(), print.metasurvey_provenance_diff(), provenance(), provenance_to_json()

Examples

svy1 <- Survey$new(
  data = data.table::data.table(id = 1:5, w = rep(1, 5)),
  edition = "2023", type = "test",
  engine = "data.table", weight = add_weight(annual = "w")
)
svy2 <- Survey$new(
  data = data.table::data.table(id = 1:5, w = rep(2, 5)),
  edition = "2024", type = "test",
  engine = "data.table", weight = add_weight(annual = "w")
)
provenance_diff(provenance(svy1), provenance(svy2))

Description

Serializes a provenance object to JSON format, optionally writing to a file.

Usage

provenance_to_json(prov, path = NULL)

Arguments

Value

JSON string (invisibly if path is provided).

See Also

Other provenance: print.metasurvey_provenance(), print.metasurvey_provenance_diff(), provenance(), provenance_diff()

Examples

svy <- Survey$new(
  data = data.table::data.table(id = 1:5, w = rep(1, 5)),
  edition = "2023", type = "test",
  engine = "data.table", weight = add_weight(annual = "w")
)
prov <- provenance(svy)
provenance_to_json(prov)

Description

Publishes a Recipe object to the active backend (local JSON registry or remote API).

Usage

publish_recipe(recipe)

Arguments

Value

The Recipe object (invisibly).

See Also

Other recipes: Recipe-class, add_recipe(), bake_recipes(), get_recipe(), harmonize(), print.Recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

set_backend("local", path = tempfile(fileext = ".json"))
r <- recipe(
  name = "Example", user = "Test",
  svy = survey_empty(type = "ech", edition = "2023"),
  description = "Example recipe"
)
publish_recipe(r)
length(list_recipes())

Description

Publishes a RecipeWorkflow to the configured workflow backend.

Usage

publish_workflow(wf)

Arguments

Value

NULL (called for side effect).

See Also

set_workflow_backend, RecipeWorkflow

Other workflows: RecipeWorkflow-class, evaluate_cv(), print.RecipeWorkflow(), read_workflow(), save_workflow(), workflow(), workflow_from_list(), workflow_table()

Examples

set_workflow_backend("local", path = tempfile(fileext = ".json"))
wf <- RecipeWorkflow$new(
  name = "Example", description = "Test",
  survey_type = "ech", edition = "2023",
  recipe_ids = "r_001", estimation_type = "svymean"
)
publish_workflow(wf)

Description

Get the top recipes ranked by download count from the active backend.

Usage

rank_recipes(n = NULL)

Arguments

Value

List of Recipe objects sorted by downloads (descending).

See Also

search_recipes, filter_recipes

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_backend("local", path = tempfile(fileext = ".json"))
top10 <- rank_recipes(n = 10)

Description

Get the top workflows ranked by download count.

Usage

rank_workflows(n = NULL)

Arguments

Value

List of RecipeWorkflow objects sorted by downloads.

See Also

search_workflows, filter_workflows

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

set_workflow_backend("local", path = tempfile(fileext = ".json"))
top5 <- rank_workflows(n = 5)
length(top5)

Description

Reads a Recipe object from a JSON file.

Usage

read_recipe(file)

Arguments

Details

This function reads a JSON file and decodes it into a Recipe object.

Value

A Recipe object.

See Also

Other recipes: Recipe-class, add_recipe(), bake_recipes(), get_recipe(), harmonize(), print.Recipe(), publish_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

r <- recipe(
  name = "Example", user = "Test",
  svy = survey_empty(type = "ech", edition = "2023"),
  description = "Example recipe"
)
f <- tempfile(fileext = ".json")
save_recipe(r, f)
r2 <- read_recipe(f)
r2

Description

Read a RecipeWorkflow from a JSON file

Usage

read_workflow(file)

Arguments

Value

A RecipeWorkflow object

See Also

Other workflows: RecipeWorkflow-class, evaluate_cv(), print.RecipeWorkflow(), publish_workflow(), save_workflow(), workflow(), workflow_from_list(), workflow_table()

Examples

wf <- RecipeWorkflow$new(
  name = "Example", description = "Test",
  survey_type = "ech", edition = "2023",
  recipe_ids = "r_001", estimation_type = "svymean"
)
f <- tempfile(fileext = ".json")
save_workflow(wf, f)
wf2 <- read_workflow(f)

Description

Creates a Recipe object that encapsulates a sequence of data transformations that can be applied to surveys in a reproducible manner. Recipes allow documenting, sharing, and reusing data processing workflows.

Usage

recipe(...)

Arguments

Details

Recipes are essential for:

• Reproducibility: Ensure transformations are applied consistently

• Documentation: Keep a record of what transformations are performed and why

• Collaboration: Share workflows between users and teams

• Versioning: Maintain different processing versions for different editions

• Automation: Apply complex transformations automatically

Steps included in the recipe can be any combination of step_compute, step_recode, or other transformation steps.

Recipes can be saved with save_recipe(), loaded with read_recipe(), and applied automatically with bake_recipes().

Value

A Recipe object containing metadata, transformation steps, dependency information, and default engine configuration.

See Also

Recipe for class definition save_recipe to save recipes read_recipe to load recipes get_recipe to retrieve recipes from repository bake_recipes to apply recipes to data

Other recipes: Recipe-class, add_recipe(), bake_recipes(), get_recipe(), harmonize(), print.Recipe(), publish_recipe(), read_recipe(), save_recipe(), steps_to_recipe()

Examples

# Basic recipe without steps
r <- recipe(
  name = "Basic ECH Indicators",
  user = "Analyst",
  svy = survey_empty(type = "ech", edition = "2023"),
  description = "Basic labor indicators for ECH 2023"
)
r


# Recipe with steps using local data
dt <- data.table::data.table(
  id = 1:50, age = sample(18:65, 50, TRUE),
  income = runif(50, 1000, 5000), w = runif(50, 0.5, 2)
)
svy <- Survey$new(
  data = dt, edition = "2023", type = "demo",
  psu = NULL, engine = "data.table",
  weight = add_weight(annual = "w")
)
svy <- svy |>
  step_compute(income_cat = ifelse(income > 3000, "high", "low")) |>
  step_recode(age_group, age < 30 ~ "young", .default = "adult")
r2 <- recipe(
  name = "Demo", user = "test", svy = svy,
  description = "Demo recipe", steps = get_steps(svy)
)
r2

Description

Creates a RecipeCategory object for classifying recipes.

Usage

recipe_category(name, description = "", parent = NULL)

Arguments

Value

A RecipeCategory object.

See Also

RecipeCategory, add_category, default_categories

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

cat <- recipe_category("labor_market", "Labor market indicators")

# With parent hierarchy
sub <- recipe_category(
  "employment", "Employment stats",
  parent = "labor_market"
)

Description

Creates a RecipeCertification object. Typically you would use certify_recipe to certify a recipe in a pipeline instead.

Usage

recipe_certification(level = "community", certified_by = NULL, notes = NULL)

Arguments

Value

A RecipeCertification object.

See Also

RecipeCertification, certify_recipe

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

# Default community certification
cert <- recipe_certification()

# Official certification
inst <- recipe_user("IECON", type = "institution")
cert <- recipe_certification("official", certified_by = inst)

Description

Creates a RecipeUser object with a simple functional interface.

Usage

recipe_user(
  name,
  type = "individual",
  email = NULL,
  affiliation = NULL,
  institution = NULL,
  url = NULL,
  verified = FALSE
)

Arguments

Value

A RecipeUser object.

See Also

RecipeUser, set_user_info, certify_recipe

Other tidy-api: RecipeCategory, RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

# Individual user
user <- recipe_user("Juan Perez", email = "[email protected]")

# Institution
inst <- recipe_user(
  "Instituto de Economia",
  type = "institution", verified = TRUE
)

# Member linked to institution
member <- recipe_user(
  "Maria",
  type = "institutional_member",
  institution = inst
)

# Member with institution name shortcut
member2 <- recipe_user(
  "Pedro",
  type = "institutional_member",
  institution = "IECON"
)

Description

R6 class representing a reproducible data transformation recipe for surveys. It encapsulates metadata, declared dependencies, and a list of transformation steps to be applied to a Survey object.

Format

An R6 class generator (R6ClassGenerator)

Value

An object of class Recipe.

Methods

$new(name, edition, survey_type, default_engine, depends_on, user, description, steps, id, doi, topic)

Class constructor.

$doc()

Auto-generate documentation from recipe steps. Returns a list with metadata, input_variables, output_variables, and pipeline information.

$validate(svy)

Validate that a survey object has all required input variables.

Public fields

Methods

Public methods

• Recipe$new()

• Recipe$increment_downloads()

• Recipe$certify()

• Recipe$add_category()

• Recipe$remove_category()

• Recipe$to_list()

• Recipe$doc()

• Recipe$validate()

• Recipe$clone()

Recipe$new()

Create a Recipe object

Usage

Recipe$new(
  name,
  edition,
  survey_type,
  default_engine,
  depends_on,
  user,
  description,
  steps,
  id,
  doi = NULL,
  topic = NULL,
  step_objects = NULL,
  cached_doc = NULL,
  categories = list(),
  downloads = 0L,
  certification = NULL,
  user_info = NULL,
  version = "1.0.0",
  depends_on_recipes = list(),
  data_source = NULL,
  labels = NULL
)

Arguments

Recipe$increment_downloads()

Increment the download counter

Usage

Recipe$increment_downloads()

Recipe$certify()

Certify the recipe at a given level

Usage

Recipe$certify(user, level)

Arguments

Recipe$add_category()

Add a category to the recipe

Usage

Recipe$add_category(category)

Arguments

Recipe$remove_category()

Remove a category by name

Usage

Recipe$remove_category(name)

Arguments

Recipe$to_list()

Serialize Recipe to a plain list suitable for JSON/API publishing. Steps are encoded as character strings via deparse().

Usage

Recipe$to_list()

Returns

A named list with all recipe fields.

Recipe$doc()

Auto-generate documentation from recipe steps

Usage

Recipe$doc()

Returns

A list with metadata, input_variables, output_variables, and pipeline information

Recipe$validate()

Validate that a survey has all required input variables

Usage

Recipe$validate(svy)

Arguments

Returns

TRUE if valid, otherwise stops with error listing missing variables

Recipe$clone()

The objects of this class are cloneable with this method.

Usage

Recipe$clone(deep = FALSE)

Arguments

See Also

recipe, save_recipe, read_recipe, bake_recipes

Other recipes: add_recipe(), bake_recipes(), get_recipe(), harmonize(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

# Use the recipe() constructor:
svy <- survey_empty(type = "ech", edition = "2023")
r <- recipe(
  name = "Example", user = "Test", svy = svy,
  description = "Example recipe"
)

Description

Standardized taxonomy for classifying recipes by domain. Supports hierarchical categories with parent-child relationships.

Value

An R6 object of class RecipeCategory.

Public fields

Methods

Public methods

• RecipeCategory$new()

• RecipeCategory$is_subcategory_of()

• RecipeCategory$get_path()

• RecipeCategory$equals()

• RecipeCategory$to_list()

• RecipeCategory$print()

• RecipeCategory$from_list()

• RecipeCategory$clone()

RecipeCategory$new()

Create a new RecipeCategory

Usage

RecipeCategory$new(name, description, parent = NULL)

Arguments

RecipeCategory$is_subcategory_of()

Check if this category is a subcategory of another

Usage

RecipeCategory$is_subcategory_of(ancestor_name)

Arguments

Returns

Logical

RecipeCategory$get_path()

Get full hierarchical path

Usage

RecipeCategory$get_path()

Returns

Character string with slash-separated path

RecipeCategory$equals()

Check equality by name

Usage

RecipeCategory$equals(other)

Arguments

Returns

Logical

RecipeCategory$to_list()

Serialize to list for JSON

Usage

RecipeCategory$to_list()

Returns

List representation

RecipeCategory$print()

Print category

Usage

RecipeCategory$print(...)

Arguments

RecipeCategory$from_list()

Deserialize a RecipeCategory from a list

Usage

RecipeCategory$from_list(lst)

Arguments

Returns

RecipeCategory object or NULL

RecipeCategory$clone()

The objects of this class are cloneable with this method.

Usage

RecipeCategory$clone(deep = FALSE)

Arguments

See Also

Other tidy-api: RecipeCertification, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

# Use recipe_category() for the public API:
cat <- recipe_category(
  "economics", "Economic indicators"
)
sub <- recipe_category(
  "labor_market", "Labor market",
  parent = "economics"
)

Description

Quality certification for recipes with three tiers: community (default), reviewed (peer-reviewed by institutional member), and official (certified by institution).

Value

An object of class RecipeCertification.

Public fields

Methods

Public methods

• RecipeCertification$new()

• RecipeCertification$numeric_level()

• RecipeCertification$is_at_least()

• RecipeCertification$to_list()

• RecipeCertification$print()

• RecipeCertification$clone()

RecipeCertification$new()

Create a new RecipeCertification

Usage

RecipeCertification$new(
  level,
  certified_by = NULL,
  notes = NULL,
  certified_at = NULL
)

Arguments

RecipeCertification$numeric_level()

Get numeric level for ordering (1=community, 2=reviewed, 3=official)

Usage

RecipeCertification$numeric_level()

Returns

Integer

RecipeCertification$is_at_least()

Check if certification is at least a given level

Usage

RecipeCertification$is_at_least(level)

Arguments

Returns

Logical

RecipeCertification$to_list()

Serialize to list for JSON

Usage

RecipeCertification$to_list()

Returns

List representation

RecipeCertification$print()

Print certification badge

Usage

RecipeCertification$print(...)

Arguments

RecipeCertification$clone()

The objects of this class are cloneable with this method.

Usage

RecipeCertification$clone(deep = FALSE)

Arguments

See Also

Other tidy-api: RecipeCategory, RecipeUser, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

# Use recipe_certification() for the public API:
cert <- recipe_certification()
inst <- recipe_user("IECON", type = "institution")
official <- recipe_certification("official", certified_by = inst)

Description

User identity for the recipe ecosystem. Supports three account types: individual, institutional_member, and institution.

Value

An object of class RecipeUser.

Public fields

Methods

Public methods

• RecipeUser$new()

• RecipeUser$trust_level()

• RecipeUser$can_certify()

• RecipeUser$to_list()

• RecipeUser$print()

• RecipeUser$clone()

RecipeUser$new()

Create a new RecipeUser

Usage

RecipeUser$new(
  name,
  user_type,
  email = NULL,
  affiliation = NULL,
  institution = NULL,
  url = NULL,
  verified = FALSE,
  review_status = "approved"
)

Arguments

RecipeUser$trust_level()

Get trust level (1=individual, 2=member, 3=institution)

Usage

RecipeUser$trust_level()

Returns

Integer trust level

RecipeUser$can_certify()

Check if user can certify at a given level

Usage

RecipeUser$can_certify(level)

Arguments

Returns

Logical

RecipeUser$to_list()

Serialize to list for JSON

Usage

RecipeUser$to_list()

Returns

List representation

RecipeUser$print()

Print user card

Usage

RecipeUser$print(...)

Arguments

RecipeUser$clone()

The objects of this class are cloneable with this method.

Usage

RecipeUser$clone(deep = FALSE)

Arguments

See Also

Other tidy-api: RecipeCategory, RecipeCertification, add_category(), certify_recipe(), default_categories(), filter_recipes(), filter_workflows(), find_workflows_for_recipe(), list_recipes(), list_workflows(), rank_recipes(), rank_workflows(), recipe_category(), recipe_certification(), recipe_user(), remove_category(), search_recipes(), search_workflows(), set_user_info(), set_version()

Examples

# Use recipe_user() for the public API:
user <- recipe_user("Juan Perez", email = "[email protected]")
inst <- recipe_user("IECON", type = "institution")
member <- recipe_user(
  "Maria",
  type = "institutional_member",
  institution = inst
)

Description

R6 class representing a publishable workflow that captures statistical estimations applied to survey data. Workflows reference the recipes they use and document the estimation calls made.

Format

An R6 class generator (R6ClassGenerator)

Value

An object of class RecipeWorkflow.

Methods

$new(...)

Class constructor.

$doc()

Generate documentation for the workflow.

$to_list()

Serialize to a plain list for JSON export.

$increment_downloads()

Increment the download counter.

$add_category(category)

Add a category.

$certify(user, level)

Certify the workflow.

Public fields

Methods

Public methods

• RecipeWorkflow$new()

• RecipeWorkflow$doc()

• RecipeWorkflow$to_list()

• RecipeWorkflow$increment_downloads()

• RecipeWorkflow$certify()

• RecipeWorkflow$add_category()

• RecipeWorkflow$remove_category()

• RecipeWorkflow$clone()

RecipeWorkflow$new()

Create a RecipeWorkflow object

Usage

RecipeWorkflow$new(
  id = NULL,
  name,
  description = "",
  user = "Unknown",
  user_info = NULL,
  survey_type = "Unknown",
  edition = "Unknown",
  estimation_type = character(0),
  recipe_ids = character(0),
  calls = list(),
  call_metadata = list(),
  categories = list(),
  downloads = 0L,
  certification = NULL,
  version = "1.0.0",
  doi = NULL,
  created_at = NULL,
  weight_spec = NULL
)

Arguments