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, a tbl_sample (the stored design is saved along with an execution receipt), a frame_stack, or a sample carrying shared weights.

frame

Optional sampling frame. A data frame is the one frame the design was built against. An ordered list of data frames is the stage registers, in the order execute() received them, and each is fingerprinted separately. One frame written as a one-element list is still one frame and is recorded identically. The number of frames must be one the design could be executed with, and for an executed sample must be the number its receipt records, so a file cannot say it was drawn from one frame and carry fingerprints for three. When supplied, a fingerprint (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. For a frame_stack, a list named by component, holding what each component was drawn from. Matched by name rather than position, since a list in the wrong order would fingerprint each component against another's register. For a shared-weight sample, the register the source selection was drawn from.

...

These dots are for future extensions and must be empty. pretty follows ..., so it is matched exactly and must be named.

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

Other serialization: as.list.sampling_design(), replay_design(), write_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.9.1",
#>         "svyplan": "0.12.0"
#>       },
#>       "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