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, fingerprinted (name, dimensions, column types, content hash) so it can be verified later. 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, each fingerprinted separately. A one-element list is one frame (see frame_input_grammar). The number of frames must be one the design could be executed with, and for an executed sample the number its receipt records. For a sample built by several calls, one element per call that read frames (the first call and each continuation), in call order: that call's frame, or the list of its registers. One data frame stands for all of them when each read that same frame. For a frame_stack, a list named by component, holding what each component was drawn from, matched by name rather than position. For a shared-weight sample, the register the source selection was drawn from. vignette("serialization") states what the hash covers. The ordinary frame columns are never written, but an executed sample's receipt can still contain selected-unit identifiers in its frame digest.

...

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": 3,
#>   "schema": {
#>     "method_vocabulary": {
#>       "id": "samplyr/common-sampling-method",
#>       "version": 2
#>     }
#>   },
#>   "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",
#>             "probability_quantity": "inclusion_probability",
#>             "probability_quality": "exact",
#>             "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.9.999",
#>       "language": {
#>         "name": "R",
#>         "version": "4.6.1"
#>       },
#>       "dependencies": {
#>         "sondage": "0.11.0",
#>         "svyplan": "0.15.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