Convert a sampling design to JSON

Renders a design (or the design carried by a tbl_sample) as a JSON string in the same format written by write_design(). Useful for storing designs in databases or sending them over APIs. read_design() accepts the resulting string as well as file paths.

Usage

design_json(x, frame = NULL, pretty = FALSE)

Arguments

x

A sampling_design, or a tbl_sample (the stored design is saved along with an execution receipt).

frame

Optional sampling frame (data frame). When supplied, a fingerprint of the frame (name, dimensions, column types, content hash) is stored so the frame can be verified later. The frame data is never written. The content hash covers column names, column values, and row order; it does not depend on the class of the data frame (tibble or data frame) or on the order of its columns.

pretty

Whether to pretty-print the JSON. Defaults to TRUE for files and FALSE for design_json().

Value

A JSON string (class json).

See also

write_design(), read_design()

Examples

design <- sampling_design() |>
  stratify_by(region) |>
  draw(n = 100)

json <- design_json(design, pretty = TRUE)
json
#> {
#>   "format": "samplyr/design",
#>   "format_version": 1,
#>   "schema": {
#>     "method_vocabulary": {
#>       "id": "samplyr/common-sampling-method",
#>       "version": 1
#>     }
#>   },
#>   "design": {
#>     "stages": [
#>       {
#>         "strata": {
#>           "vars": ["region"]
#>         },
#>         "draw": {
#>           "n": 100,
#>           "method": {
#>             "id": "simple_random_without_replacement",
#>             "family": "equal_probability",
#>             "algorithm": "simple_random",
#>             "replacement": "without_replacement",
#>             "sample_size": "fixed",
#>             "probabilities": "equal",
#>             "standards": [
#>               {
#>                 "vocabulary": "DDI SamplingProcedure",
#>                 "version": "1.1.4",
#>                 "code": "Probability.SimpleRandom",
#>                 "uri": "http://rdf-vocabulary.ddialliance.org/cv/SamplingProcedure/1.1.4/38e8e88"
#>               }
#>             ]
#>           },
#>           "round": "up",
#>           "certainty_overflow": "error",
#>           "on_empty": "error"
#>         }
#>       }
#>     ]
#>   },
#>   "frame": {
#>     "required_variables": [
#>       {
#>         "name": "region",
#>         "role": "strata",
#>         "stage": 1
#>       }
#>     ]
#>   },
#>   "tools": {
#>     "samplyr": {
#>       "version": "0.8.9999",
#>       "language": {
#>         "name": "R",
#>         "version": "4.6.0"
#>       },
#>       "dependencies": {
#>         "sondage": "0.8.8",
#>         "svyplan": "0.8.9"
#>       },
#>       "design": {
#>         "stages": [
#>           {
#>             "method": {
#>               "name": "srswor",
#>               "registry_type": null,
#>               "fixed_size": null,
#>               "variance_family": null,
#>               "probabilities": "exact",
#>               "implementation": null
#>             }
#>           }
#>         ]
#>       }
#>     }
#>   }
#> } 

# read_design() accepts the JSON string directly
restored <- read_design(json)
identical(
  execute(restored, bfa_eas, seed = 7)$ea_id,
  execute(design, bfa_eas, seed = 7)$ea_id
)
#> [1] TRUE