Title:	Reproducible Survey Data Processing with Step Pipelines
Version:	0.0.21
URL:	https://metasurveyr.github.io/metasurvey/, https://github.com/metasurveyr/metasurvey
BugReports:	https://github.com/metasurveyr/metasurvey/issues
Description:	Provides a step-based pipeline for reproducible survey data processing, building on the 'survey' package for complex sampling designs. Supports rotating panels with bootstrap replicate weights, and provides a recipe system for sharing and reproducing data transformation workflows across survey editions.
License:	GPL (≥ 3)
Imports:	data.table (≥ 1.14.2), cli (≥ 3.0.0), glue (≥ 1.6.0), lifecycle (≥ 1.0.0), jsonlite (≥ 1.7.2), R6 (≥ 2.5.0), survey (≥ 4.2.1), methods
Suggests:	archive, convey, httr2 (≥ 1.0.0), haven, openxlsx, visNetwork (≥ 2.0.9), roxygen2 (≥ 7.1.2), testthat (≥ 3.0.0), tibble (≥ 3.1.3), dplyr (≥ 1.0.7), knitr (≥ 1.33), foreign (≥ 0.8-81), rmarkdown (≥ 2.11), parallel, rio (≥ 0.5.27), here (≥ 1.0.1), gt (≥ 0.10.0), magrittr, shiny (≥ 1.7.0), bslib (≥ 0.5.0), bsicons (≥ 0.1.0), htmltools (≥ 0.5.0), xml2 (≥ 1.3.0), eph, PNADcIBGE, ipumsr
Config/testthat/edition:	3
Encoding:	UTF-8
RoxygenNote:	7.3.3
Depends:	R (≥ 4.1)
VignetteBuilder:	knitr
NeedsCompilation:	no
Packaged:	2026-02-20 17:09:34 UTC; mauroloprete
Author:	Mauro Loprete [aut, cre], Natalia da Silva [aut], Fabricio Machado [aut]
Maintainer:	Mauro Loprete <mauro.loprete@icloud.com>
Repository:	CRAN
Date/Publication:	2026-02-25 10:30:07 UTC

metasurvey: Survey Processing with Meta-Programming

Description

The metasurvey package provides a comprehensive framework for processing complex survey data using meta-programming techniques. It integrates seamlessly with the survey package while adding powerful features for reproducible survey analysis workflows.

Key Features

Survey Objects and Classes:

• Survey: Basic survey object for cross-sectional data

• RotativePanelSurvey: Panel survey with implantation and follow-up

• PoolSurvey: Pool of multiple surveys for time series analysis

Steps and Workflows:

• step_compute: Create computed variables

• step_recode: Recode variables with multiple conditions

• workflow: Execute estimation workflows with variance adjustment

Recipes and Reproducibility:

• recipe: Create reusable recipe objects

• bake_recipes: Apply recipes to survey data

• get_recipe: Retrieve recipes from repository

Data Loading and Weights:

• load_survey: Load single survey data

• load_panel_survey: Load panel survey data

• add_weight: Add survey weights

• add_replicate: Add bootstrap/jackknife replicates

Quality Assessment:

• evaluate_cv: Evaluate coefficient of variation quality

• Built-in variance estimation with multiple engines

Supported Survey Types

The package includes built-in support for several survey types:

• ECH: Encuesta Continua de Hogares (Uruguay)

• EAII: Encuesta de Actividad, Innovación e I+D

• EAI: Encuesta de Actividades de Innovación

• Generic survey types with flexible configuration

Workflow Example

library(metasurvey)
# Note: examples use base R pipe (|>) to avoid extra dependencies

# Load survey data
survey_data <- load_survey(
  data_path = "path/to/data.csv",
  svy_edition = "2023",
  svy_type = "ech",
  svy_weight = add_weight(annual = "weight_var")
)

# Add processing steps
processed_survey <- survey_data |>
  step_recode("employed", status == 1 ~ 1, .default = 0) |>
  step_compute(unemployment_rate = unemployed / labor_force)

# Apply steps and run workflow
final_survey <- bake_steps(processed_survey)

results <- workflow(
  survey = list(final_survey),
  survey::svytotal(~employed),
  survey::svymean(~unemployment_rate),
  estimation_type = "annual"
)

Meta-Programming Features

The package leverages R's meta-programming capabilities to:

• Generate survey code dynamically based on metadata

• Create reusable workflows that adapt to different survey structures

• Validate and harmonize variable definitions across time periods

• Automatically handle complex variance estimation procedures

Author(s)

Mauro Loprete mauro.loprete@icloud.com, Natalia da Silva natalia.dasilva@fcea.edu.uy, Fabricio Machado fabricio.mch.slv@gmail.com

References

Lumley, T. (2020). "survey: analysis of complex survey samples". R package version 4.0.

See Also

• https://CRAN.R-project.org/package=survey for the survey package

• Package website: https://github.com/metasurveyr/metasurvey

• Vignettes: vignette(package = "metasurvey")

Extract downloaded ANDA file (handles ZIP, RAR, CSV, SAV)

Description

Extract downloaded ANDA file (handles ZIP, RAR, CSV, SAV)

Usage

.anda_extract_file(raw_path, dest_dir, label)

Arguments

Value

Path to the extracted data file

Find the main data file in an extracted directory

Description

Find the main data file in an extracted directory

Usage

.anda_find_data_file(dir, label)

Arguments

Value

Character path to the data file

Parse ANDA download page for resource titles and IDs

Description

Parse ANDA download page for resource titles and IDs

Usage

.anda_parse_resources(html, catalog_id)

Arguments

Value

data.frame with columns: id, title

Select resources matching the requested type

Description

Select resources matching the requested type

Usage

.anda_select_resource(resources, resource, edition)

Arguments

Value

data.frame subset of matching resources

PoolSurvey Class

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

Method new()

Initializes a new instance of the PoolSurvey class.

Usage

PoolSurvey$new(surveys)

Arguments

Method get_surveys()

Retrieves surveys for a specific period.

Usage

PoolSurvey$get_surveys(period = NULL)

Arguments

Returns

A list of surveys for the specified period.

Method print()

Prints metadata about the PoolSurvey object.

Usage

PoolSurvey$print()

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

Recipe R6 class

Description

Recipe R6 class

Recipe R6 class

Format

An R6 class generator (R6ClassGenerator)

Details

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.

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

Method 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

Method increment_downloads()

Increment the download counter

Usage

Recipe$increment_downloads()

Method certify()

Certify the recipe at a given level

Usage

Recipe$certify(user, level)

Arguments

Method add_category()

Add a category to the recipe

Usage

Recipe$add_category(category)

Arguments

Method remove_category()

Remove a category by name

Usage

Recipe$remove_category(name)

Arguments

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

Method doc()

Auto-generate documentation from recipe steps

Usage

Recipe$doc()

Returns

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

Method 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

Method 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(), explore_recipes(), get_recipe(), 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"
)

RecipeBackend

Description

Backend-agnostic factory for recipe storage and retrieval. Supports "local" (JSON-backed RecipeRegistry) and "api" (remote plumber API) backends.

Public fields

Methods

Public methods

• RecipeBackend$new()

• RecipeBackend$publish()

• RecipeBackend$search()

• RecipeBackend$get()

• RecipeBackend$increment_downloads()

• RecipeBackend$rank()

• RecipeBackend$filter()

• RecipeBackend$list_all()

• RecipeBackend$save()

• RecipeBackend$load()

• RecipeBackend$clone()

Method new()

Create a new RecipeBackend

Usage

RecipeBackend$new(type, path = NULL)

Arguments

Method publish()

Publish a recipe to the backend

Usage

RecipeBackend$publish(recipe)

Arguments

Method search()

Search recipes

Usage

RecipeBackend$search(query)

Arguments

Returns

List of matching Recipe objects

Method get()

Get a recipe by id

Usage

RecipeBackend$get(id)

Arguments

Returns

Recipe object or NULL

Method increment_downloads()

Increment download count for a recipe

Usage

RecipeBackend$increment_downloads(id)

Arguments

Method rank()

Rank recipes by downloads

Usage

RecipeBackend$rank(n = NULL)

Arguments

Returns

List of Recipe objects

Method filter()

Filter recipes by criteria

Usage

RecipeBackend$filter(
  survey_type = NULL,
  edition = NULL,
  category = NULL,
  certification_level = NULL
)

Arguments

Returns

List of matching Recipe objects

Method list_all()

List all recipes

Usage

RecipeBackend$list_all()

Returns

List of Recipe objects

Method save()

Save local backend to disk

Usage

RecipeBackend$save()

Method load()

Load local backend from disk

Usage

RecipeBackend$load()

Method clone()

The objects of this class are cloneable with this method.

Usage

RecipeBackend$clone(deep = FALSE)

Arguments

RecipeCategory

Description

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

Value

An object of class RecipeCategory.

Methods

$new(name, description, parent)

Constructor for creating a new category

$is_subcategory_of(ancestor_name)

Check if this category is a subcategory of another

$get_path()

Get full hierarchical path

$equals(other)

Check equality by name

$to_list()

Serialize to list for JSON

$print(...)

Print category information

$from_list(lst)

Class method to reconstruct from list (see details)

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

Method new()

Create a new RecipeCategory

Usage

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

Arguments

Method is_subcategory_of()

Check if this category is a subcategory of another

Usage

RecipeCategory$is_subcategory_of(ancestor_name)

Arguments

Returns

Logical

Method get_path()

Get full hierarchical path

Usage

RecipeCategory$get_path()

Returns

Character string with slash-separated path

Method equals()

Check equality by name

Usage

RecipeCategory$equals(other)

Arguments

Returns

Logical

Method to_list()

Serialize to list for JSON

Usage

RecipeCategory$to_list()

Returns

List representation

Method print()

Print category

Usage

RecipeCategory$print(...)

Arguments

Method from_list()

Deserialize a RecipeCategory from a list

Usage

RecipeCategory$from_list(lst)

Arguments

Returns

RecipeCategory object or NULL

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

Deserialize a RecipeCategory from a list

Description

Class method to reconstruct a RecipeCategory from its list representation.

Arguments

Value

RecipeCategory object or NULL

RecipeCertification

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

Method new()

Create a new RecipeCertification

Usage

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

Arguments

Method numeric_level()

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

Usage

RecipeCertification$numeric_level()

Returns

Integer

Method is_at_least()

Check if certification is at least a given level

Usage

RecipeCertification$is_at_least(level)

Arguments

Returns

Logical

Method to_list()

Serialize to list for JSON

Usage

RecipeCertification$to_list()

Returns

List representation

Method print()

Print certification badge

Usage

RecipeCertification$print(...)

Arguments

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

RecipeRegistry

Description

Local JSON-backed catalog for recipe discovery, ranking, and filtering.

Methods

Public methods

• RecipeRegistry$new()

• RecipeRegistry$register()

• RecipeRegistry$unregister()

• RecipeRegistry$search()

• RecipeRegistry$filter()

• RecipeRegistry$rank_by_downloads()

• RecipeRegistry$rank_by_certification()

• RecipeRegistry$get()

• RecipeRegistry$list_all()

• RecipeRegistry$save()

• RecipeRegistry$load()

• RecipeRegistry$list_by_user()

• RecipeRegistry$list_by_institution()

• RecipeRegistry$stats()

• RecipeRegistry$print()

• RecipeRegistry$clone()

Method new()

Create a new empty RecipeRegistry

Usage

RecipeRegistry$new()

Method register()

Register a recipe in the catalog

Usage

RecipeRegistry$register(recipe)

Arguments

Method unregister()

Remove a recipe from the catalog by id

Usage

RecipeRegistry$unregister(recipe_id)

Arguments

Method search()

Search recipes by name or description (case-insensitive)

Usage

RecipeRegistry$search(query)

Arguments

Returns

List of matching Recipe objects

Method filter()

Filter recipes by criteria

Usage

RecipeRegistry$filter(
  survey_type = NULL,
  edition = NULL,
  category = NULL,
  certification_level = NULL
)

Arguments

Returns

List of matching Recipe objects

Method rank_by_downloads()

Rank recipes by download count (descending)

Usage

RecipeRegistry$rank_by_downloads(n = NULL)

Arguments

Returns

List of Recipe objects sorted by downloads

Method rank_by_certification()

Rank recipes by certification level then downloads

Usage

RecipeRegistry$rank_by_certification(n = NULL)

Arguments

Returns

List of Recipe objects sorted by cert level then downloads

Method get()

Get a single recipe by id

Usage

RecipeRegistry$get(recipe_id)

Arguments

Returns

Recipe object or NULL

Method list_all()

List all registered recipes

Usage

RecipeRegistry$list_all()

Returns

List of all Recipe objects

Method save()

Save the registry catalog to a JSON file

Usage

RecipeRegistry$save(path)

Arguments

Method load()

Load a registry catalog from a JSON file

Usage

RecipeRegistry$load(path)

Arguments

Method list_by_user()

List recipes by author user name

Usage

RecipeRegistry$list_by_user(user_name)

Arguments

Returns

List of matching Recipe objects

Method list_by_institution()

List recipes by institution (including members)

Usage

RecipeRegistry$list_by_institution(institution_name)

Arguments

Returns

List of matching Recipe objects

Method stats()

Get registry statistics

Usage

RecipeRegistry$stats()

Returns

List with total, by_category, by_certification counts

Method print()

Print registry summary

Usage

RecipeRegistry$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

RecipeRegistry$clone(deep = FALSE)

Arguments

RecipeUser

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

Method 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

Method trust_level()

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

Usage

RecipeUser$trust_level()

Returns

Integer trust level

Method can_certify()

Check if user can certify at a given level

Usage

RecipeUser$can_certify(level)

Arguments

Returns

Logical

Method to_list()

Serialize to list for JSON

Usage

RecipeUser$to_list()

Returns

List representation

Method print()

Print user card

Usage

RecipeUser$print(...)

Arguments

Method 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 = "juan@example.com")
inst <- recipe_user("IECON", type = "institution")
member <- recipe_user(
  "Maria",
  type = "institutional_member",
  institution = inst
)

RecipeWorkflow R6 class

Description

RecipeWorkflow R6 class

RecipeWorkflow R6 class

Format

An R6 class generator (R6ClassGenerator)

Details

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.

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

Method 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

Method doc()

Generate documentation for this workflow

Usage

RecipeWorkflow$doc()

Returns

List with meta, recipe_ids, estimations, and estimation_types

Method to_list()

Serialize to a plain list for JSON export

Usage

RecipeWorkflow$to_list()

Returns

A list suitable for jsonlite::write_json

Method increment_downloads()

Increment the download counter

Usage

RecipeWorkflow$increment_downloads()

Method certify()

Certify the workflow at a given level

Usage

RecipeWorkflow$certify(user, level)

Arguments

Method add_category()

Add a category to the workflow

Usage

RecipeWorkflow$add_category(category)

Arguments

Method remove_category()

Remove a category by name

Usage

RecipeWorkflow$remove_category(name)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

RecipeWorkflow$clone(deep = FALSE)

Arguments

See Also

save_workflow, read_workflow, workflow

Other workflows: evaluate_cv(), print.RecipeWorkflow(), publish_workflow(), read_workflow(), reproduce_workflow(), save_workflow(), workflow(), workflow_from_list(), workflow_table()

Examples

wf <- RecipeWorkflow$new(
  name = "Labor workflow", description = "Unemployment rate",
  user = "test", survey_type = "ech", edition = "2023",
  estimation_type = "annual", recipe_ids = "r_001",
  calls = list("svymean(~desocupado, na.rm = TRUE)")
)

RotativePanelSurvey Class

Description

This class represents a rotative panel survey, which includes implantation and follow-up surveys. It provides methods to access and manipulate survey data, steps, recipes, workflows, and designs.

Value

An object of class RotativePanelSurvey.

Public fields

Methods

Public methods

• RotativePanelSurvey$new()

• RotativePanelSurvey$get_implantation()

• RotativePanelSurvey$get_follow_up()

• RotativePanelSurvey$get_type()

• RotativePanelSurvey$get_default_engine()

• RotativePanelSurvey$get_steps()

• RotativePanelSurvey$get_recipes()

• RotativePanelSurvey$get_workflows()

• RotativePanelSurvey$get_design()

• RotativePanelSurvey$print()

• RotativePanelSurvey$clone()

Method new()

Initializes a new instance of the RotativePanelSurvey class.

Usage

RotativePanelSurvey$new(
  implantation,
  follow_up,
  type,
  default_engine,
  steps,
  recipes,
  workflows,
  design
)

Arguments

Method get_implantation()

Retrieves the implantation survey.

Usage

RotativePanelSurvey$get_implantation()

Returns

A survey object representing the implantation survey.

Method get_follow_up()

Retrieves the follow-up surveys.

Usage

RotativePanelSurvey$get_follow_up(
  index = length(self$follow_up),
  monthly = NULL,
  quarterly = NULL,
  semiannual = NULL,
  annual = NULL
)

Arguments

Returns

A list of follow-up surveys matching the specified criteria.

Method get_type()

Retrieves the type of the survey.

Usage

RotativePanelSurvey$get_type()

Returns

A string indicating the type of the survey.

Method get_default_engine()

Retrieves the default engine used for processing.

Usage

RotativePanelSurvey$get_default_engine()

Returns

A string specifying the default engine.

Method get_steps()

Retrieves the steps applied to the survey.

Usage

RotativePanelSurvey$get_steps()

Returns

A list containing the steps for the implantation and follow-up surveys.

Method get_recipes()

Retrieves the recipes associated with the survey.

Usage

RotativePanelSurvey$get_recipes()

Returns

A list of recipes.

Method get_workflows()

Retrieves the workflows associated with the survey.

Usage

RotativePanelSurvey$get_workflows()

Returns

A list of workflows.

Method get_design()

Retrieves the design object for the survey.

Usage

RotativePanelSurvey$get_design()

Returns

A design object.

Method print()

Prints metadata about the RotativePanelSurvey object.

Usage

RotativePanelSurvey$print()

Method clone()

The objects of this class are cloneable with this method.

Usage

RotativePanelSurvey$clone(deep = FALSE)

Arguments

See Also

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

Examples

impl <- Survey$new(
  data = data.table::data.table(id = 1:5, w = 1),
  edition = "2023", type = "ech", 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 = "ech", psu = NULL,
  engine = "data.table", weight = add_weight(annual = "w")
)
panel <- RotativePanelSurvey$new(
  implantation = impl, follow_up = list(fu1),
  type = "ech", default_engine = "data.table",
  steps = list(), recipes = list(), workflows = list(), design = NULL
)

Step Class Represents a step in a survey workflow.

Description

The Step class is used to define and manage individual steps in a survey workflow. Each step can include operations such as recoding variables, computing new variables, or validating dependencies.

Details

The Step class is part of the survey workflow system and is designed to encapsulate all the information and operations required for a single step in the workflow. Steps can be chained together to form a complete workflow.

Public fields

Methods

Public methods

• Step$new()

• Step$clone()

Method new()

Create a new Step object

Usage

Step$new(
  name,
  edition,
  survey_type,
  type,
  new_var,
  exprs,
  call,
  svy_before,
  default_engine,
  depends_on,
  comment = NULL,
  bake = !lazy_default(),
  comments = NULL
)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

Step$clone(deep = FALSE)

Arguments

Survey R6 class

Description

Survey R6 class

Survey R6 class

Format

An R6 class generator (R6ClassGenerator)

Details

R6 class that encapsulates survey data, metadata (type, edition, periodicity), sampling design (simple/replicate), steps/recipes/workflows, and utilities to manage them.

Only copies the data; reuses design objects and other metadata. Much faster than clone(deep=TRUE) but design objects are shared.

Value

R6 class generator for Survey.

Main methods

$new(data, edition, type, psu, strata, engine, weight, design = NULL, steps = NULL, recipes = list())

Constructor.

$set_data(data)

Set data.

$set_edition(edition)

Set edition.

$set_type(type)

Set type.

$set_weight(weight)

Set weight specification.

$print()

Print summarized metadata.

$add_step(step)

Add a step and invalidate design.

$add_recipe(recipe)

Add a recipe (validates type and dependencies).

$add_workflow(workflow)

Add a workflow.

$bake()

Apply recipes and return updated Survey.

$ensure_design()

Lazily initialize the sampling design.

$update_design()

Update design variables with current data.

$shallow_clone()

Efficient copy (shares design, copies data).

Public fields

Active bindings

Methods

Public methods

• Survey$new()

• Survey$get_data()

• Survey$get_edition()

• Survey$get_type()

• Survey$set_data()

• Survey$set_edition()

• Survey$set_type()

• Survey$set_weight()

• Survey$print()

• Survey$add_step()

• Survey$add_recipe()

• Survey$add_workflow()

• Survey$bake()

• Survey$head()

• Survey$str()

• Survey$set_design()

• Survey$ensure_design()

• Survey$update_design()

• Survey$shallow_clone()

• Survey$clone()

Method new()

Create a Survey object

Usage

Survey$new(
  data,
  edition,
  type,
  psu = NULL,
  strata = NULL,
  engine,
  weight,
  design = NULL,
  steps = NULL,
  recipes = list()
)

Arguments

Method get_data()

Return the underlying data

Usage

Survey$get_data()

Method get_edition()

Return the survey edition/period

Usage

Survey$get_edition()

Method get_type()

Return the survey type identifier

Usage

Survey$get_type()

Method set_data()

Set the underlying data

Usage

Survey$set_data(data)

Arguments

Method set_edition()

Set the survey edition/period

Usage

Survey$set_edition(edition)

Arguments

Method set_type()

Set the survey type

Usage

Survey$set_type(type)

Arguments

Method set_weight()

Set weight specification(s) per estimation type

Usage

Survey$set_weight(weight)

Arguments

Method print()

Print summarized metadata to console

Usage

Survey$print()

Method add_step()

Add a step and invalidate design

Usage

Survey$add_step(step)

Arguments

Method add_recipe()

Add a recipe

Usage

Survey$add_recipe(recipe, bake = lazy_default())

Arguments

Method add_workflow()

Add a workflow to the survey

Usage

Survey$add_workflow(workflow)

Arguments

Method bake()

Apply recipes and return updated Survey

Usage

Survey$bake()

Method head()

Return the head of the underlying data

Usage

Survey$head()

Method str()

Display the structure of the underlying data

Usage

Survey$str()

Method set_design()

Set the survey design object

Usage

Survey$set_design(design)

Arguments

Method ensure_design()

Ensure survey design is initialized (lazy initialization)

Usage

Survey$ensure_design()

Returns

Invisibly returns self

Method update_design()

Update design variables using current data and weight

Usage

Survey$update_design()

Method shallow_clone()

Create a shallow copy of the Survey (optimized for performance)

Usage

Survey$shallow_clone()

Returns

New Survey object with copied data but shared design

Method clone()

The objects of this class are cloneable with this method.

Usage

Survey$clone(deep = FALSE)

Arguments

See Also

survey_empty, bake_recipes, cat_design, cat_recipes

Other survey-objects: cat_design(), 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:5, x = rnorm(5), w = rep(1, 5))
svy <- Survey$new(
  data = dt, edition = "2023", type = "test",
  psu = NULL, engine = "data.table", weight = add_weight(annual = "w")
)
svy

WorkflowBackend

Description

Backend-agnostic factory for workflow storage and retrieval. Supports "local" (JSON-backed WorkflowRegistry) and "api" (remote plumber API) backends.

Public fields

Methods

Public methods

• WorkflowBackend$new()

• WorkflowBackend$publish()

• WorkflowBackend$search()

• WorkflowBackend$get()

• WorkflowBackend$increment_downloads()

• WorkflowBackend$find_by_recipe()

• WorkflowBackend$rank()

• WorkflowBackend$filter()

• WorkflowBackend$list_all()

• WorkflowBackend$save()

• WorkflowBackend$load()

• WorkflowBackend$clone()

Method new()

Create a new WorkflowBackend

Usage

WorkflowBackend$new(type, path = NULL)

Arguments

Method publish()

Publish a workflow to the backend

Usage

WorkflowBackend$publish(wf)

Arguments

Method search()

Search workflows

Usage

WorkflowBackend$search(query)

Arguments

Returns

List of matching RecipeWorkflow objects

Method get()

Get a workflow by id

Usage

WorkflowBackend$get(id)

Arguments

Returns

RecipeWorkflow object or NULL

Method increment_downloads()

Increment download count for a workflow

Usage

WorkflowBackend$increment_downloads(id)

Arguments

Method find_by_recipe()

Find workflows that reference a specific recipe

Usage

WorkflowBackend$find_by_recipe(recipe_id)

Arguments

Returns

List of RecipeWorkflow objects

Method rank()

Rank workflows by downloads

Usage

WorkflowBackend$rank(n = NULL)

Arguments

Returns

List of RecipeWorkflow objects

Method filter()

Filter workflows by criteria

Usage

WorkflowBackend$filter(
  survey_type = NULL,
  edition = NULL,
  recipe_id = NULL,
  certification_level = NULL
)

Arguments

Returns

List of matching RecipeWorkflow objects

Method list_all()

List all workflows

Usage

WorkflowBackend$list_all()

Returns

List of RecipeWorkflow objects

Method save()

Save local backend to disk

Usage

WorkflowBackend$save()

Method load()

Load local backend from disk

Usage

WorkflowBackend$load()

Method clone()

The objects of this class are cloneable with this method.

Usage

WorkflowBackend$clone(deep = FALSE)

Arguments

WorkflowRegistry

Description

Local JSON-backed catalog for workflow discovery, ranking, and filtering.

Methods

Public methods

• WorkflowRegistry$new()

• WorkflowRegistry$register()

• WorkflowRegistry$unregister()

• WorkflowRegistry$search()

• WorkflowRegistry$filter()

• WorkflowRegistry$find_by_recipe()

• WorkflowRegistry$rank_by_downloads()

• WorkflowRegistry$get()

• WorkflowRegistry$list_all()

• WorkflowRegistry$save()

• WorkflowRegistry$load()

• WorkflowRegistry$stats()

• WorkflowRegistry$print()

• WorkflowRegistry$clone()

Method new()

Create a new empty WorkflowRegistry

Usage

WorkflowRegistry$new()

Method register()

Register a workflow in the catalog

Usage

WorkflowRegistry$register(wf)

Arguments

Method unregister()

Remove a workflow from the catalog by id

Usage

WorkflowRegistry$unregister(workflow_id)

Arguments

Method search()

Search workflows by name or description (case-insensitive)

Usage

WorkflowRegistry$search(query)

Arguments

Returns

List of matching RecipeWorkflow objects

Method filter()

Filter workflows by criteria

Usage

WorkflowRegistry$filter(
  survey_type = NULL,
  edition = NULL,
  recipe_id = NULL,
  certification_level = NULL
)

Arguments

Returns

List of matching RecipeWorkflow objects

Method find_by_recipe()

Find workflows that reference a specific recipe

Usage

WorkflowRegistry$find_by_recipe(recipe_id)

Arguments

Returns

List of RecipeWorkflow objects referencing this recipe

Method rank_by_downloads()

Rank workflows by download count (descending)

Usage

WorkflowRegistry$rank_by_downloads(n = NULL)

Arguments

Returns

List of RecipeWorkflow objects sorted by downloads

Method get()

Get a single workflow by id

Usage

WorkflowRegistry$get(workflow_id)

Arguments

Returns

RecipeWorkflow object or NULL

Method list_all()

List all registered workflows

Usage

WorkflowRegistry$list_all()

Returns

List of all RecipeWorkflow objects

Method save()

Save the registry catalog to a JSON file

Usage

WorkflowRegistry$save(path)

Arguments

Method load()

Load a registry catalog from a JSON file

Usage

WorkflowRegistry$load(path)

Arguments

Method stats()

Get registry statistics

Usage

WorkflowRegistry$stats()

Returns

List with total, by_survey_type, by_certification counts

Method print()

Print registry summary

Usage

WorkflowRegistry$print(...)

Arguments

Method clone()

The objects of this class are cloneable with this method.

Usage

WorkflowRegistry$clone(deep = FALSE)

Arguments

Add a category to a recipe

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

Add a recipe to a Survey

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(), explore_recipes(), get_recipe(), 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)

Configure replicate weights for variance estimation

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

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

Configure weights by periodicity for Survey objects

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

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

Search ANDA5 catalog

Description

Queries the ANDA5 REST API to list available survey datasets.

Usage

anda_catalog_search(
  keyword = "ECH",
  base_url = "https://www4.ine.gub.uy/Anda5",
  limit = 50
)

Arguments

Value

A data.frame with columns: id, title, year_start, year_end

Download ECH microdata from ANDA5

Description

Downloads microdata files for a given ECH edition from INE Uruguay's ANDA5 catalog. Automatically accepts the terms of use, parses available resources, and downloads the appropriate file.

For editions >= 2022, ANDA provides separate files for implantation, monthly follow-ups, and bootstrap replicate weights. Use the resource parameter to select which file to download.

Usage

anda_download_microdata(
  edition,
  resource = "implantation",
  dest_dir = tempdir(),
  base_url = "https://www4.ine.gub.uy/Anda5"
)

Arguments

Value

Character path (or vector of paths for monthly) to the downloaded file(s), ready to pass to load_survey() or data.table::fread().

See Also

Other anda: anda_variables(), api_get_anda_variables()

Examples

## Not run: 
path <- anda_download_microdata("2023", resource = "implantation")
svy <- load_survey(path, svy_type = "ech", svy_edition = "2023")

## End(Not run)

Fetch DDI XML from ANDA5 catalog

Description

Downloads the DDI (Data Documentation Initiative) XML file for a given catalog entry from INE Uruguay's ANDA5 catalog.

Usage

anda_fetch_ddi(
  catalog_id,
  base_url = "https://www4.ine.gub.uy/Anda5",
  dest_file = NULL
)

Arguments

Value

Character path to the downloaded DDI XML file

List available ECH editions in ANDA5

Description

Returns the known ECH editions available in INE Uruguay's ANDA5 catalog.

Usage

anda_list_editions()

Value

A data.frame with columns: edition, catalog_id

Parse variables from a DDI XML file

Description

Reads a DDI Codebook XML file and extracts variable-level metadata: name, label, type (discrete/continuous), and value labels.

Usage

anda_parse_variables(ddi_xml_path)

Arguments

Value

A list of variable metadata, each with: name, label, type, value_labels (named list or NULL), description

Get detailed metadata for a single ANDA variable

Description

Get detailed metadata for a single ANDA variable

Usage

anda_variable_detail(survey_type = "ech", var_name)

Arguments

Value

A list with: name, label, type, value_labels, description. NULL if not found.

Query ANDA variable metadata from the API

Description

Fetches variable metadata (labels, types, value labels) from the metasurvey API's ANDA endpoint.

Usage

anda_variables(survey_type = "ech", var_names = NULL)

Arguments

Value

A data.frame with columns: name, label, type

See Also

Other anda: anda_download_microdata(), api_get_anda_variables()

Examples

## Not run: 
anda_variables("ech", c("pobpcoac", "e27"))

## End(Not run)

API Client for metasurvey

Description

HTTP client for the metasurvey REST API (plumber).

The metasurvey API is a server deployed separately (Docker, Cloud Run, etc.). Users of the R package interact with it through these client functions.

Setup

# 1. Point to the deployed API
configure_api(url = "https://metasurvey-api.example.com")

# 2. Register or login
api_register("Ana Garcia", "ana@example.com", "password123")
api_login("ana@example.com", "password123")

# 3. Use the API
api_list_recipes(survey_type = "ech")
api_publish_recipe(my_recipe)

Add a comment to a recipe

Description

Post a text comment on a recipe. Requires authentication.

Usage

api_comment_recipe(id, text)

Arguments

Value

Invisibly, the API response.

See Also

Other api-comments: api_comment_workflow(), api_delete_comment(), api_get_recipe_comments(), api_get_workflow_comments()

Examples

## Not run: 
api_comment_recipe("r_1739654400_742", "Great recipe!")

## End(Not run)

Add a comment to a workflow

Description

Post a text comment on a workflow. Requires authentication.

Usage

api_comment_workflow(id, text)

Arguments

Value

Invisibly, the API response.

See Also

Other api-comments: api_comment_recipe(), api_delete_comment(), api_get_recipe_comments(), api_get_workflow_comments()

Examples

## Not run: 
api_comment_workflow("w_1739654400_123", "Very useful workflow!")

## End(Not run)

Delete a comment

Description

Delete a comment by its ID. Only the comment author can delete it. Requires authentication.

Usage

api_delete_comment(comment_id)

Arguments

Value

Invisibly, the API response.

See Also

Other api-comments: api_comment_recipe(), api_comment_workflow(), api_get_recipe_comments(), api_get_workflow_comments()

Examples

## Not run: 
api_delete_comment("c_abc123")

## End(Not run)

Increment recipe download counter

Description

Increment recipe download counter

Usage

api_download_recipe(id)

Arguments

Increment workflow download counter

Description

Increment workflow download counter

Usage

api_download_workflow(id)

Arguments

Get ANDA variable metadata from the API

Description

Get ANDA variable metadata from the API

Usage

api_get_anda_variables(survey_type = "ech", var_names = NULL)

Arguments

Value

A list of variable metadata objects

See Also

Other anda: anda_download_microdata(), anda_variables()

Examples

## Not run: 
api_get_anda_variables("ech", c("pobpcoac", "e27"))

## End(Not run)

Get recipe(s) by ID

Description

Retrieve one or more recipes from the API by their IDs.

Usage

api_get_recipe(id)

Arguments

Value

A single Recipe object (or NULL) when length(id) == 1. A list of Recipe objects when length(id) > 1 (NULLs are dropped).

See Also

Other api-recipes: api_get_recipe_dependents(), api_list_recipes(), api_publish_recipe()

Examples

## Not run: 
api_get_recipe("r_1739654400_742")

## End(Not run)

Get comments for a recipe

Description

List all comments on a recipe, sorted by creation date.

Usage

api_get_recipe_comments(id)

Arguments

Value

List of comment objects.

See Also

Other api-comments: api_comment_recipe(), api_comment_workflow(), api_delete_comment(), api_get_workflow_comments()

Examples

## Not run: 
api_get_recipe_comments("r_1739654400_742")

## End(Not run)

Get recipes that depend on a recipe

Description

Find all recipes whose depends_on_recipes field references the given recipe ID (backlinks).

Usage

api_get_recipe_dependents(id)

Arguments

Value

List of recipe summaries (id, name, user).

See Also

Other api-recipes: api_get_recipe(), api_list_recipes(), api_publish_recipe()

Examples

## Not run: 
api_get_recipe_dependents("r_1739654400_742")

## End(Not run)

Get star summary for a recipe

Description

Returns average rating, count, and the current user's rating (if authenticated).

Usage

api_get_recipe_stars(id)

Arguments

Value

List with average, count, and optionally user_value.

See Also

Other api-stars: api_get_workflow_stars(), api_star_recipe(), api_star_workflow()

Examples

## Not run: 
api_get_recipe_stars("r_1739654400_742")

## End(Not run)

Get a single workflow by ID

Description

Retrieve a workflow from the API by its ID.

Usage

api_get_workflow(id)

Arguments

Value

RecipeWorkflow object or NULL

See Also

Other api-workflows: api_list_workflows(), api_publish_workflow()

Examples

## Not run: 
api_get_workflow("w_1739654400_123")

## End(Not run)

Get comments for a workflow

Description

List all comments on a workflow, sorted by creation date.

Usage

api_get_workflow_comments(id)

Arguments

Value

List of comment objects.

See Also

Other api-comments: api_comment_recipe(), api_comment_workflow(), api_delete_comment(), api_get_recipe_comments()

Examples

## Not run: 
api_get_workflow_comments("w_1739654400_123")

## End(Not run)

Get star summary for a workflow

Description

Returns average rating, count, and the current user's rating (if authenticated).

Usage

api_get_workflow_stars(id)

Arguments

Value

List with average, count, and optionally user_value.

See Also

Other api-stars: api_get_recipe_stars(), api_star_recipe(), api_star_workflow()

Examples

## Not run: 
api_get_workflow_stars("w_1739654400_123")

## End(Not run)

List recipes from API

Description

Fetch recipes with optional search and filters.

Usage

api_list_recipes(
  search = NULL,
  survey_type = NULL,
  topic = NULL,
  certification = NULL,
  user = NULL,
  limit = 50,
  offset = 0
)

Arguments

Value

List of Recipe objects

See Also

Other api-recipes: api_get_recipe(), api_get_recipe_dependents(), api_publish_recipe()

Examples

## Not run: 
configure_api("https://metasurvey-api.example.com")
recipes <- api_list_recipes(survey_type = "ech")

## End(Not run)

List workflows from API

Description

Fetch workflows with optional search and filters.

Usage

api_list_workflows(
  search = NULL,
  survey_type = NULL,
  recipe_id = NULL,
  user = NULL,
  limit = 50,
  offset = 0
)

Arguments

Value

List of RecipeWorkflow objects

See Also

Other api-workflows: api_get_workflow(), api_publish_workflow()

Examples

## Not run: 
api_list_workflows(survey_type = "ech")

## End(Not run)

Login

Description

Authenticate with the metasurvey API. On success the JWT token is stored automatically.

Usage

api_login(email, password)

Arguments

Value

Invisibly, the API response.

See Also

Other api-auth: api_logout(), api_me(), api_refresh_token(), api_register(), configure_api()

Examples

## Not run: 
api_login("ana@example.com", "s3cret")

## End(Not run)

Logout

Description

Clear the stored API token from memory and the environment.

Usage

api_logout()

Value

Invisibly, NULL.

See Also

Other api-auth: api_login(), api_me(), api_refresh_token(), api_register(), configure_api()

Examples

api_logout()

Get current user profile

Description

Returns profile info for the currently authenticated user.

Usage

api_me()

Value

List with user fields (name, email, user_type, etc.)

See Also

Other api-auth: api_login(), api_logout(), api_refresh_token(), api_register(), configure_api()

Examples

## Not run: 
api_me()

## End(Not run)

Publish a recipe

Description

Publish a Recipe object to the API. Requires authentication (call api_login() first).

Usage

api_publish_recipe(recipe)

Arguments

Value

Invisibly, the API response with the assigned ID.

See Also

Other api-recipes: api_get_recipe(), api_get_recipe_dependents(), api_list_recipes()

Examples

## Not run: 
api_publish_recipe(my_recipe)

## End(Not run)

Publish a workflow

Description

Publish a RecipeWorkflow object to the API. Requires authentication.

Usage

api_publish_workflow(workflow)

Arguments

Value

Invisibly, the API response.

See Also

Other api-workflows: api_get_workflow(), api_list_workflows()

Examples

## Not run: 
api_publish_workflow(my_workflow)

## End(Not run)

Refresh JWT token

Description

Request a new JWT token using the current (still valid) token. The new token is stored automatically. This is called internally by api_request() when the current token is close to expiry (within 5 minutes).

Usage

api_refresh_token()

Value

The new token string (invisibly), or NULL if refresh fails.

See Also

Other api-auth: api_login(), api_logout(), api_me(), api_register(), configure_api()

Examples

## Not run: 
api_refresh_token()

## End(Not run)

Register a new user

Description

Create an account on the metasurvey API. On success the JWT token is stored automatically via options(metasurvey.api_token).

Usage

api_register(
  name,
  email,
  password,
  user_type = "individual",
  institution = NULL
)

Arguments

Value

Invisibly, the API response (list with ok, token, user).

See Also

Other api-auth: api_login(), api_logout(), api_me(), api_refresh_token(), configure_api()

Examples

## Not run: 
configure_api("https://metasurvey-api.example.com")
api_register("Ana Garcia", "ana@example.com", "s3cret")

## End(Not run)

Rate a recipe

Description

Give a star rating (1-5) to a recipe. Requires authentication. Each user can have one rating per recipe (upserts on subsequent calls).

Usage

api_star_recipe(id, value)

Arguments

Value

Invisibly, the API response.

See Also

Other api-stars: api_get_recipe_stars(), api_get_workflow_stars(), api_star_workflow()

Examples

## Not run: 
api_star_recipe("r_1739654400_742", 5)

## End(Not run)

Rate a workflow

Description

Give a star rating (1-5) to a workflow. Requires authentication.

Usage

api_star_workflow(id, value)

Arguments

Value

Invisibly, the API response.

See Also

Other api-stars: api_get_recipe_stars(), api_get_workflow_stars(), api_star_recipe()

Examples

## Not run: 
api_star_workflow("w_1739654400_123", 4)

## End(Not run)

Increment download counter (generic)

Description

Increment download counter (generic)

Usage

api_track_download(type, id)

Arguments

Bake recipes

Description

Bake recipes

Usage

bake_recipes(svy)

Arguments

Value

Survey object with all recipes applied

See Also

Other recipes: Recipe-class, add_recipe(), explore_recipes(), get_recipe(), 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)

Execute all pending steps

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_compute(), step_filter(), step_join(), 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)

Display survey design information

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)

cat_design_type

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

cat_estimation_default

Description

cat_estimation_default

Usage

cat_estimation.default(estimation, call)

Arguments

cat_recipes

Description

Cast recipes from survey

Usage

cat_recipes(self)

Arguments

Value

Character string listing recipe names, or "None".

Certify a recipe

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

Collect lines inside a loop body until closing brace

Description

Collect lines inside a loop body until closing brace

Usage

collect_loop_body(lines, start_idx)

Arguments

Value

List with body (character vector) and end_idx

Configure metasurvey API

Description

Set API base URL and optionally load stored credentials. The URL can also be set via the METASURVEY_API_URL environment variable, and the token via METASURVEY_TOKEN.

Usage

configure_api(url)

Arguments

Value

Invisibly, the previous URL (for restoring).

See Also

Other api-auth: api_login(), api_logout(), api_me(), api_refresh_token(), api_register()

Examples

configure_api(url = "https://metasurvey-api.example.com")

Default recipe categories

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

Set default engine

Description

Sets a default engine for loading surveys. If an engine is already configured, it keeps it; otherwise, it sets "data.table" as the default engine.

Usage

default_engine(.engine = "data.table")

Arguments

Evaluate estimation with Coefficient of Variation

Description

Evaluate estimation with Coefficient of Variation

Usage

evaluate_cv(cv)

Arguments

Value

Character string with the quality category (e.g. "Excellent", "Good").

See Also

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

Examples

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

Substitute loop variable in body lines

Description

Substitute loop variable in body lines

Usage

expand_loop_body(loopvar, values, body)

Arguments

Value

Character vector of expanded lines

Expand a numlist specification into numeric values

Description

Expand a numlist specification into numeric values

Usage

expand_numlist(spec)

Arguments

Value

Character vector of values

Expand STATA foreach and forvalues loops

Description

Detects foreach/forvalues blocks and unrolls them by substituting loop variables into body lines.

Usage

expand_stata_loops(lines)

Arguments

Value

Character vector with loops expanded

Expand a STATA variable range to individual variable names

Description

STATA allows variable ranges like suma1-suma4 which means suma1 suma2 suma3 suma4. This function detects and expands such ranges by incrementing the trailing numeric suffix.

Usage

expand_var_range(spec)

Arguments

Value

Character vector of individual variable names

Launch the Recipe Explorer Shiny App

Description

Opens an interactive web application to explore, search, and browse metasurvey recipes with visual documentation cards. Supports user registration and login via MongoDB Atlas.

Usage

explore_recipes(port = NULL, host = "127.0.0.1", launch.browser = TRUE)

Arguments

Value

NULL (called for side effect of launching the app).

See Also

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

Examples

## Not run: 
# Local / RStudio viewer
explore_recipes()

# Server deployment (Railway, Docker, etc.)
explore_recipes(host = "0.0.0.0", port = 3838, launch.browser = FALSE)

## End(Not run)

Extract surveys by periodicity from a rotating panel

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

## Not run: 
# Load rotating panel
panel_ech <- load_panel_survey(
  path = "ech_panel_2023.dta",
  svy_type = "ech_panel",
  svy_edition = "2023"
)

# Extract specific monthly surveys
ech_q1 <- extract_surveys(
  panel_ech,
  monthly = c(1, 2, 3) # January, February, March
)

# Extract by index
ech_first <- extract_surveys(panel_ech, index = 1)
ech_several <- extract_surveys(panel_ech, index = c(1, 3, 6))

# Quarterly analysis
ech_Q1_Q4 <- extract_surveys(
  panel_ech,
  quarterly = c(1, 4)
)

# Annual analysis (typically all surveys for the year)
ech_annual <- extract_surveys(
  panel_ech,
  annual = 1
)

# With parallel processing for large volumes
ech_full <- extract_surveys(
  panel_ech,
  monthly = 1:12,
  use.parallel = TRUE
)

# Use in workflow
results <- workflow(
  survey = extract_surveys(panel_ech, quarterly = c(1, 2)),
  svymean(~unemployed, na.rm = TRUE),
  estimation_type = "quarterly"
)

## End(Not run)

Extract time pattern

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

Filter recipes by criteria

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
)

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)

Filter workflows by criteria

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)

Find workflows that use a specific recipe

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)

Get recipe backend

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

get_data

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

Get the current survey data engine

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

Get follow-up surveys from a rotating panel

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)

Get implantation survey from a rotating 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)

get_metadata

Description

Get metadata from survey

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)

Get recipe from repository or API

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(), explore_recipes(), print.Recipe(), publish_recipe(), read_recipe(), recipe(), save_recipe(), steps_to_recipe()

Examples

## Not run: 
# Get specific recipe for ECH 2023
ech_recipe <- get_recipe(
  svy_type = "ech",
  svy_edition = "2023"
)

# Recipe for specific topic
labor_recipe <- get_recipe(
  svy_type = "ech",
  svy_edition = "2023",
  topic = "labor_market"
)

# Allow multiple recipes
available_recipes <- get_recipe(
  svy_type = "eaii",
  svy_edition = "2019-2021",
  allowMultiple = TRUE
)

# Use recipe in load_survey
ech_with_recipe <- load_survey(
  path = "ech_2023.dta",
  svy_type = "ech",
  svy_edition = "2023",
  recipes = get_recipe("ech", "2023"),
  bake = TRUE
)

# Working offline - don't use recipes
ech_offline <- load_survey(
  path = "ech_2023.dta",
  svy_type = "ech",
  svy_edition = "2023",
  svy_weight = add_weight(annual = "PESOANO")
)

# Disable recipe API globally
options(metasurvey.skip_recipes = TRUE)
# Now get_recipe() will return NULL with a warning

# For year ranges
panel_recipe <- get_recipe(
  svy_type = "ech_panel",
  svy_edition = "2020-2023"
)

## End(Not run)

get_steps

Description

Get steps from survey

Usage

get_steps(svy)

Arguments

Value

List of Step objects

See Also

Other steps: bake_steps(), step_compute(), step_filter(), step_join(), 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

Get workflow backend

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

Group dates

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

Check if survey has a design

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

Check if survey has recipes

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

Check if survey has steps

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

Check if all steps are baked

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)

Detect if a STATA replace RHS is a constant value

Description

Returns TRUE if the expression is a simple numeric constant, string literal, or negative number. Used to decide between step_recode (constants) and step_compute (expressions).

Usage

is_constant_rhs(expr)

Arguments

Value

Logical

Join broken expression lines after block comment removal

Description

After removing /* */ block comments, expressions can be split across lines. This function re-joins lines where the previous line ends with an operator or open paren, or the next line starts with an operator or close paren.

Usage

join_broken_expressions(lines)

Arguments

Value

Character vector with broken expressions re-joined

Join STATA continuation lines

Description

STATA uses /// for line continuation. This function joins continued lines into single commands.

Usage

join_continuation_lines(lines)

Arguments

Value

Character vector with continuations joined

Lazy processing

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

List all recipes

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)

List all workflows

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)

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

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

## Not run: 
# example code
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)
## Not run: 
# Example of loading a panel survey
panel_survey <- load_panel_survey(
  path_implantation = "path/to/implantation.csv",
  path_follow_up = "path/to/follow_up",
  svy_type = "ech",
  svy_weight_implantation = add_weight(annual = "w_ano"),
  svy_weight_follow_up = add_weight(monthly = "w_monthly")
)
print(panel_survey)

## End(Not run)

Load survey from file and create Survey object

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

## Not run: 
# Load ECH 2023 with recipes
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
ech_january <- load_survey(
  path = "data/ech_202301.dta",
  svy_type = "ech",
  svy_edition = "202301",
  svy_weight = add_weight(monthly = "pesomes")
)

# Create empty object for pipeline
pipeline <- load_survey(
  svy_type = "ech",
  svy_edition = "2023"
) %>%
  step_compute(new_var = operation)

# With included example data
ech_example <- load_survey(
  path = load_survey_example("ech", "ech_2022"),
  svy_type = "ech",
  svy_edition = "2022",
  svy_weight = add_weight(annual = "pesoano")
)

## End(Not run)

Load survey example data

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: 
# Load ECH 2023 example data
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)

Parse a STATA destring command

Description

Parse a STATA destring command

Usage

parse_destring_args(args, options = NULL)

Arguments

Value

List with var_name, replace (logical), force (logical), gen_var

Parse a STATA .do file into structured commands

Description

Reads a .do file and returns a list of parsed command objects. Handles comment stripping, line continuation, loop expansion, and command tokenization.

Usage

parse_do_file(do_file, encoding = "latin1")

Arguments

Value

A list of StataCommand lists, each with fields: cmd, args, if_clause, options, raw_line, line_num, capture

See Also

Other transpiler: parse_stata_labels(), transpile_coverage(), transpile_stata(), transpile_stata_module()

Examples

tf <- tempfile(fileext = ".do")
writeLines(c("gen age2 = edad^2", "replace sexo = 1 if sexo == ."), tf)
cmds <- parse_do_file(tf)
length(cmds)
cmds[[1]]$cmd

Parse a STATA egen command

Description

Parse a STATA egen command

Usage

parse_egen_args(args, by_group = NULL, options = NULL)

Arguments

Value

List with var_name, func, func_arg, by_group

Parse a STATA gen command into variable name and expression

Description

Parse a STATA gen command into variable name and expression

Usage

parse_gen_args(args)

Arguments

Value

List with var_name and expr

Parse a STATA mvencode command

Description

Parse a STATA mvencode command

Usage

parse_mvencode_args(args, options = NULL)

Arguments

Value

List with var_names and mv_value

Parse a STATA recode command

Description

Handles patterns like:

• recode var (old=new) (old=new)

• recode var (old=new), gen(newvar)

• recode var .=0

• recode var 23/38=22

Usage

parse_recode_args(args, options = NULL)

Arguments

Value

List with var_name, gen_var (or NULL), and mappings list

Parse a STATA replace command into variable name and expression

Description

Parse a STATA replace command into variable name and expression

Usage

parse_replace_args(args)

Arguments

Value

List with var_name and expr

Parse a single STATA command line into structured data

Description

Parse a single STATA command line into structured data

Usage

parse_stata_command(line, line_num = NA_integer_)

Arguments

Value

A list with cmd, args, if_clause, options, raw_line, line_num, capture, or NULL for empty/skippable lines

Parse STATA label commands from source lines

Description

Extracts variable labels, value label definitions, and value label assignments from label commands.

Usage

parse_stata_labels(lines)

Arguments

Value

A list with var_labels (named list) and val_labels (named list of named lists)

See Also

Other transpiler: parse_do_file(), transpile_coverage(), transpile_stata(), transpile_stata_module()

Examples

lines <- c(
  'label variable edad "Age in years"',
  'label define sexo_lbl 1 "Male" 2 "Female"',
  "label values sexo sexo_lbl"
)
labels <- parse_stata_labels(lines)
labels$var_labels
labels$val_labels

Print method for Recipe objects

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(), explore_recipes(), get_recipe(), 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)

Print method for RecipeWorkflow objects

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

Print provenance information

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

Print provenance diff

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)

Get provenance from a survey or workflow result

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)

Compare two provenance objects

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

Export provenance to JSON

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)

Publish Recipe

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(), explore_recipes(), get_recipe(), 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())

Publish a workflow to the active backend

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

Rank recipes by downloads

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)

Rank workflows by downloads

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