Decks 🔗

A Deck allows an ordered collection of analyses to be stored for future use or for export. Each deck belongs to a dataset and its analyses are drawn from that single dataset. A deck is personal to the user that created it unless the deck has been set “public”. Each deck contains a sequence of slides, and each slide contains an analysis. Additional analyses can be associated with a slide, but only the first one appears in the UI or on export.

Catalog 🔗

/datasets/{id}/decks/

GET 🔗

A GET request on the catalog endpoint will return all decks in this dataset that are accessible to the current user. This includes decks created by the user, as well as all public decks in the dataset.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/",
    "index": {
        "https://app.crunch.io/api/datasets/cc9161/decks/4fa25/": {
          "name": "my new deck",
          "creation_time": "1986-11-26T12:05:00",
          "id": "4fa25",
          "is_public": false,
          "owner_id": "https://app.crunch.io/api/users/abcd3/",
          "owner_name": "Real Person",
          "team": null
        },
        "https://app.crunch.io/api/datasets/cc9161/decks/2b53e/": {
          "name": "Default deck",
          "creation_time": "1987-10-15T11:45:00",
          "id": "2b53e",
          "is_public": true,
          "owner_id": "https://app.crunch.io/api/users/4cba5/",
          "owner_name": "Other Person",
          "team": "https://app.crunch.io/api/teams/58acf7/"
        }
    },
    "order": "https://app.crunch.io/api/datasets/223fd4/decks/order/"
}

The deck catalog tuples contain the following keys:

Name Type Description
name string Human-friendly string identifier
creation_time timestamp Time when this deck was created
id string Global unique identifier for this deck
is_public boolean Indicates whether this is a public deck or not
owner_id url Points to the owner of this deck
owner_name string Name of the owner of the deck (referred by owner_id)
team url If the deck is shared through a team, it will point to it. null by default

To determine if a deck belongs to the current user, check the owner_id attribute.

POST 🔗

POST a shoji:entity to create a new deck for this dataset. The only required body attribute is “name”; other attributes are optional.

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/",
    "body": {
        "name": "my new deck",
        "description": "This deck will contain analyses for a variable",
        "is_public": false,
        "team": "https://app.crunch.io/api/teams/58acf7/"
    }
}
HTTP/1.1 201 Created
Location: https://app.crunch.io/api/datasets/223fd4/decks/2b3c5e/

The shoji:entity POSTed accepts the following keys

Name Type required
name string Yes
description string No
is_public boolean No
team url No

PATCH 🔗

It is possible to bulk-edit multiple decks at once by PATCHing a shoji:catalog to the deck catalog endpoint.

{
    "element": "shoji:catalog",
    "index": {
        "https://app.crunch.io/api/datasets/cc9161/decks/4fa25/": {
          "name": "Renamed deck",
          "is_public": true
        }
    },
    "order": "https://app.crunch.io/api/datasets/223fd4/decks/order/"
}

The following attributes are editable via PATCHing this resource:

  • name
  • description
  • is_public

For decks that the current user owns, “name”, “description” and “is_public” are editable. Only the deck owner can edit the mentioned attributes on a deck even if the deck is public. Other deck attributes are not editable and will respond with 400 status if the request tries to change them.

On success, the server will respond with status code 204 (No Content).

Public decks cannot contain analyses that refer to secure variables. Attempting to create one results in a 400 response. Hidden variables, however, are permitted.

Entity 🔗

/datasets/{id}/decks/{id}/

GET 🔗

GET a deck entity resource to return a shoji:entity with all of its attributes:

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/",
    "body": {
        "name": "Presentation deck",
        "id": "223fd4",
        "creation_time": "1987-10-15T11:45:00",
        "description": "Explanation about the deck",
        "is_public": false,
        "owner_id": "https://app.crunch.io/api/users/abcd3/",
        "owner_name": "Real Person",
        "team": "https://app.crunch.io/api/teams/58acf7/"
    }
}
Name Type Description
name string Human-friendly string identifier
id string Global unique identifier for this deck
creation_time timestamp Time when this deck was created
description string Longer annotations for this deck
is_public boolean Indicates whether this is a public deck or not
owner_id url Points to the owner of this deck
owner_name string Name of the owner of the deck (referred by owner_id)
team url If the deck is shared through a team, it will point to it. null by default

PATCH 🔗

To edit a deck, PATCH it with a shoji:entity. The server will return a 204 response on success or 400 if the request is invalid.

{
    "element": "shoji:entity",
    "self": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/",
    "body": {
        "name": "Presentation deck",
        "id": "223fd4",
        "creation_time": "1987-10-15T11:45:00",
        "description": "Explanation about the deck",
        "team": "https://app.crunch.io/api/teams/58acf7/"
    },
    "catalogs": {
        "slides": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/slides/"
    },
    "views": {
        "export": "https://app.crunch.io/api/datasets/223fd4/decks/223fd4/export/"
    }
}
HTTP/1.1 204 No Content

For deck entities that the current user owns, “name”, “description”, “teams” and “is_public” are editable. Other deck attributes are not editable.

Attempting to PATCH is_public: true to a deck containing an analysis that references a secure variable will receive a 400 response.

DELETE 🔗

To delete a deck, DELETE the deck’s entity URL. On success, the server returns a 204 response.

Deck Exports 🔗

Exporting a deck initiates a download of that deck rendered as a Microsoft Excel or PowerPoint file. A JSON option is also available, which includes all the data that appears in a XLSX or PPTX download.

Two optional fields can appear in the export POST request body: filter_environment and slides.

{
  "filter_environment": [
    {
      "function": "in",
      "args": [
        {"variable": "https://app.crunch.io/api/datasets/e939/variables/5La0/"},
        {
          "column": [2],
          "type": {
            "function": "typeof",
            "args": [
              {"variable": "https://app.crunch.io/api/datasets/e939/variables/5La0/"}
            ],
          }
        }
      ],
    }
  ],
  "slides": [
    "/datasets/abcdef/decks/123456/slides/ghij7890/",
    "/datasets/fedcba/decks/654321/slides/0987jihg/",
  ]
}

A filter-environment can be specified to apply one or more filters to all slides in the deck. These filters are applied in addition to any filter(s) in the analysis of each slide.

The slides field is a list of one or more slide-URLs. If omitted, all slides in the deck are exported, in the order specified in the deck. If the “slides”: field is present, only the slides specified in that list are included in the export and they appear in the order mentioned. The slides must all come from the deck specified in the POST URL and at least one slide URL must appear in the list.

XLSX 🔗

A successful POST to /datasets/{dataset_id}/decks/{deck_id}/export/ returns a 202 (Accepted) response indicating the export job has been started.

  • The Location header of the response contains the download URL for the export file.
  • The response body contains a progress URL on which export completion status may be queried.

Clients should note the download URL, monitor progress, and when complete, GET the download location. See Progress for details.

The XLSX download format is indicated by the Accept: header on the POST. Since XLSX is the default format, if no such header is provided on the POST, this endpoint will produce an xlsx file. If desired, an Accept: application/vnd.openxmlformats-officedocument.spreadsheetml.sheet header can be used to explicitly specify Excel (xlsx) download format.

Note that very large exports may take some time.

If the same export is requested before a prior request is completed, the same 202 response will be returned, indicating the same download and progress locations. If the prior export is finished, the export will be generated again.

PPTX 🔗

A PowerPoint-format deck export is specified by the following Location header:

"Accept: application/vnd.openxmlformats-officedocument.presentationml.presentation"

JSON 🔗

Providing an Accept: application/json header for this endpoint produces a JSON export of the deck payload. This is the same JSON used to form an XLSX or PPTX deck export and contains an analysis for each slide in the deck.

{
  "slides": [
    {
      "cube": {
        "query": {
          "measures": {
            "count": {
              "function": "cube_count",
              "args": []
            }
          },
          "dimensions": [
            {
              "function": "bin",
              "args": [
                {
                  "variable": "000001"
                }
              ]
            },
            {
              "variable": "000000"
            }
          ],
          "weight": null
        },
        "query_environment": {
          "filter": []
        },
        "result": {
          "dimensions": [
            {
              "references": {
                "alias": "Age",
                "description": null,
                "name": "Age"
              },
              "derived": true,
              "type": {
                "subtype": {
                  "missing_rules": {},
                  "class": "numeric",
                  "missing_reasons": {
                    "No Data": -1
                  }
                },
                "elements": [
                  {
                    "id": 1,
                    "value": [10.0, 20.0],
                    "missing": false
                  },
                  {
                    "id": 2,
                    "value": [20.0, 30.0],
                    "missing": false
                  },
                  {
                    "id": 3,
                    "value": [30.0, 40.0],
                    "missing": false
                  },
                  {
                    "id": 4,
                    "value": [40.0, 50.0],
                    "missing": false
                  }
                ],
                "class": "enum"
              }
            },
            {
              "references": {
                "alias": "Gender",
                "description": null,
                "name": "Gender"
              },
              "derived": false,
              "type": {
                "ordinal": false,
                "class": "categorical",
                "categories": [
                  {
                    "numeric_value": null,
                    "id": 2,
                    "name": "F",
                    "missing": false
                  },
                  {
                    "numeric_value": null,
                    "id": 1,
                    "name": "M",
                    "missing": false
                  }
                ]
              }
            }
          ],
          "missing": 0,
          "measures": {
            "count": {
              "data": [1, 3, 0, 0, 1, 0, 1, 1],
              "n_missing": 0,
              "metadata": {
                "references": {},
                "derived": true,
                "type": {
                  "integer": true,
                  "missing_rules": {},
                  "class": "numeric",
                  "missing_reasons": {
                    "No Data": -1
                  }
                }
              }
            }
          },
          "n": 7,
          "counts": [1, 3, 0, 0, 1, 0, 1, 1],
          "element": "crunch:cube"
        }
      },
      "meta": {
        "table_title": "",
        "name": "Slide #1 ",
        "weight": null,
        "title": "Slide #1",
        "filters": [],
        "subtitle": "",
        "display_settings": {
          "decimalPlaces": {
            "value": 2
          }
        }
      }
    }
  ],
  "dataset": {
    "notes": "",
    "name": "New dataset"
  }
}

Order 🔗

/datasets/{id}/decks/order/

The deck order resource allows the user to arrange how API clients, such as the web application, will present the deck catalog. The deck order contains all decks that are visible to the current user, both personal and public. Unlike many other shoji:order resources, this order does not allow grouping or nesting: it will always be a flat list of deck URLs.

GET 🔗

Returns a Shoji Order response.

{
  "element": "shoji:order",
  "self": "https://app.crunch.io/api/datasets/223fd4/decks/order/",
  "graph": [
    "https://app.crunch.io/api/datasets/223fd4/decks/1/",
    "https://app.crunch.io/api/datasets/223fd4/decks/2/",
    "https://app.crunch.io/api/datasets/223fd4/decks/3/"
  ]
}

PATCH 🔗

PATCH the order resource to change the order of the decks. A 204 (No Content) response indicates success.

If the PATCH payload contains only a subset of available decks, those decks not referenced will be appended at the bottom of the top level graph in arbitrary order.

{
  "element": "shoji:order",
  "self": "https://app.crunch.io/api/datasets/223fd4/decks/order/",
  "graph": [
    "https://app.crunch.io/api/datasets/223fd4/decks/1/",
    "https://app.crunch.io/api/datasets/223fd4/decks/3/"
  ]
}

Including invalid URLs, such as URLs of decks that are not present in the catalog, will return a 400 response from the server.

The deck order should always be a flat list of URLs. Nesting or grouping is not supported by the web application. Server will return a 400 response if the order supplied in the PATCH request has nesting.

Slides 🔗

Each deck contains a catalog of slides in which analyses are saved.

Catalog 🔗

/datasets/{id}/decks/{deck_id}/slides/

GET 🔗

Returns a shoji:catalog with the slides for this deck.

{
    "element": "shoji:catalog",
    "self": "https://app.crunch.io/api/datasets/123/decks/123/slides/",
    "orders": {
        "flat": "https://app.crunch.io/api/datasets/123/decks/123/slides/flat/"
    },
    "specification": "https://app.crunch.io/api/specifications/slides/",
    "description": "A catalog of the Slides in this Deck",
    "index": {
        "https://app.crunch.io/api/datasets/123/decks/123/slides/123/": {
            "analysis_url": "https://app.crunch.io/api/datasets/123/decks/123/slides/123/analyses/123/",
            "subtitle": "z",
            "display_settings": {
                "vizType": {
                    "value": "table"
                }
            },
            "type": "analysis",
            "title": "slide 1"
        },
        "https://app.crunch.io/api/datasets/123/decks/123/slides/456/": {
            "analysis_url": "https://app.crunch.io/api/datasets/123/decks/123/slides/456/",
            "subtitle": "",
            "display_settings": {
                "vizType": {
                    "value": "table"
                }
            },
            "type": "analysis",
            "title": "slide 2"
        },
        "https://app.crunch.io/api/datasets/123/decks/123/slides/789/": {
            "title": "slide 3",
            "subtitle": "",
            "type": "markdown",
            "markdown": "# Some markdown\ntext"
        }
    }
}

Each item in the slide-catalog index contains the following keys:

Name Type Description
analysis_url url Points to the first (and typically only) analysis contained on this slide
title string Optional title for the slide
subtitle string Optional subtitle for the slide
type string Defaults to “analysis”, only other value is “markdown”
display_settings object Stores settings used to load the analysis

POST 🔗

To create a new slide, POST a slide body to the slides catalog. The body should be wrapped as a shoji:entity. On success, the server returns a 201 (Created) response with a Location header containing the URL of the newly created slide entity.

Slide type - Each slide has a type, currently one of "analysis" or "markdown", defaulting to analysis when not specified.

The body of an analysis slide must contain an analyses array item containing one or more analysis bodies as described in the Analysis section. A “regular” slide contains exactly one analysis. Only a paired-filter slide contains multiple analyses and those must occur in matched target-control pairs.

A markdown slide should contain a "markdown": item containing the markdown text as a string. If omitted, the markdown is the empty string (“”).

An "analyses": field appearing in a markdown slide payload is ignored, as is a markdown field in an analysis-slide payload. The slide type is the sole arbiter of what fields are required and used.

Because public decks cannot contain analyses that refer to secure variables, attempting to create a slide on a public deck that references a secure variable results in a 400 response. Hidden variables, however, are permitted.

{
  "type": "analysis",
  "title": "Analysis slide",
  "subtitle": "X vs. Y",
  "analyses": [
    {
      "query": {...},
      "query_environment": {...},
      "display_settings": {...}
    }
  ]
}

On each analysis, only a query field is required to create a new slide; other attributes are optional.

To add a markdown slide:

{
  "type": "markdown",
  "title": "Methodology",
  "subtitle": "Survey Methods",
  "markdown": "# Title\n##Subtitle\n\nparagraph",
}

Slide attributes:

Name Type Description
title string Optional title for the slide
subtitle string Optional subtitle for the slide
type string Defaults to “analysis”

Analysis attributes:

Name Type Description
query object Contains a valid analysis query, required
display_settings object Contains a set of attributes to be interpreted by the client to render and export the analysis
query_environment object

Contains the weight and filter applied during the analysis, they will be applied upon future evaluation/render/export.

The weight value must be a variable URL, null or the weight key may be omitted. A variable URL must correspond to a variable in the weight_variables collection for the dataset. A value of null indicates unweighted. When the weight key is omitted, the current-weight of the user making the evaluation/render/export request (not necessarily the user who created the slide) is used and can vary between users.

transform object Contains a transformations specifier object.

Entity 🔗

/datasets/223fd4/decks/slides/a126ce/

Each slide in the Slide Catalog contains a reference to its first analysis.

GET 🔗

{
    "element": "shoji:entity",
    "self": "/api/datasets/123/decks/123/slides/123/",
    "catalogs": {
        "analyses": "/api/datasets/123/decks/123/slides/123/analyses/"
    },
    "description": "Returns the detail information for a given slide",
    "body": {
        "deck_id": "123",
        "subtitle": "z",
        "title": "slide 1",
        "analysis_url": "/api/datasets/123/decks/123/slides/123/analyses/123/",
        "display_settings": {
            "vizType": {
                "value": "table"
            }
        },
        "transform": {},
        "id": "123"
    }
}

DELETE 🔗

Perform a DELETE request on the Slide entity resource to delete the slide and its analyses.

PATCH 🔗

It is possible to edit a slide entity by PATCHing with a shoji:entity.

The editable attributes are:

  • title
  • subtitle

The other attributes are considered read-only.

Order 🔗

/datasets/223fd4/decks/slides/flat/

The owner of the deck can specify the order of its slides. As with deck order, the slide order must be a flat list of slide URLs.

GET 🔗

Returns the list of all the slides in the deck.

{
    "element": "shoji:order",
    "self": "/api/datasets/123/decks/123/slides/flat/",
    "description": "Order of the slides on this deck",
    "graph": [
        "/api/datasets/123/decks/123/slides/123/",
        "/api/datasets/123/decks/123/slides/456/"
    ]
}

PATCH 🔗

To make changes to the order, a client should PATCH the full shoji:order resource to the endpoint with the new order on its graph attribute.

Any slide not mentioned on the payload will be added at the end of the graph in arbitrary order.

{
    "element": "shoji:order",
    "self": "/api/datasets/123/decks/123/slides/flat/",
    "description": "Order of the slides on this deck",
    "graph": [
        "/api/datasets/123/decks/123/slides/123/",
        "/api/datasets/123/decks/123/slides/456/"
    ]
}

This is a flat order: grouping or nesting is not allowed. PATCHing with a nested order will generate a 400 response.

Analysis 🔗

Each slide contains one or more analyses. An analysis – a table or graph with some specific combination of variables defining measures, rows, columns, and tabs; and settings such as percentage direction and decimal places – can be saved to a deck, which can then be exported, or the analysis can be reloaded in whole in the application or even exported as a standalone embeddable result. Note that while a slide can have multiple analyses, only the first analysis for each slide is used when exporting to Excel or PowerPoint.

Catalog 🔗

GET 🔗

/api/datasets/123/decks/123/slides/123/analyses/

Entity 🔗

An analysis is defined by a query, query environment, and display settings. To save an analysis, POST these to a deck as a new slide.

Display settings can be anything a client may need to reproduce the view of the data returned from the query. The settings the Crunch web client uses are shown here, but other clients are free to store other attributes as they see fit. Display settings should be objects with a value member.

{
    "query": {
        "dimensions" : [],
        "measures": {}
    },
    "query_environment": {
        "filter": [
            {"filter": "<url>"},
            {"function": "expression", "args": [], "name": "(Optional)"}
        ],
        "weight": "url"
    },
    "display_settings": {
        "decimalPlaces": {
            "value": 0
        },
        "percentageDirection": {
            "value": "colPct"
        },
        "vizType": {
            "value": "table"
        },
        "countsOrPercents": {
            "value": "percent"
        },
        "uiView": {
            "value": "expanded"
        }
    },
    "transform": {},
    "viz_specs": {}
}
Name Description
query Includes the query body for this analysis
query_environment

An object with a weight and filters to be used for rendering/evaluating this analysis

The weight item must be a variable-URL, null, or the key may be omitted. A variable-URL must correspond to a variable in the weight_variables collection for the dataset. A value of null indicates unweighted. When the weight key is omitted, the current-weight of the user making the evaluate/render/export request is used and may vary between users.

display_settings An object containing client-specific instructions on how to recreate the analysis
transform An object containing client-specific instructions on how to manipulate results, such as order and renaming
viz_specs An object containing client-specific instructions on how to display the results of the query

A deck slide contains a display_settings field and an optional viz_specs field. The table-slide export options can be added to the viz_specs field that automatically override values set in display_settings.

Here a complete example of the viz_spec object:

"viz_specs": {
    "default": {
        "format": {
            "decimal_places": {
                "percentages": 0,
                "moe": 1,
                "other": 2
            },
            "show_empty": false
        },
        "measures": ["col_percent"]
    },
    "table": {
        "format": {
            "pval_colors": false,
        },
        "measures": [
            "col_percent",
            "row_percent",
            "table_percent",
            "count_weighted",
            "count_unweighted",
            "col_base_weighted",
            "col_base_unweighted",
            "row_base_weighted",
            "row_base_unweighted",
            "table_base_weighted",
            "table_base_unweighted",
            "columns_moe",
            "columns_std_dev",
            "columns_std_err",
            "row_percent_moe",
            "row_std_dev",
            "row_std_err",
            "table_percent_moe",
            "table_std_dev",
            "table_std_err",
            "z_score",
            "p_value",
            "col_index",
            "pairwise_t_test",
            "population",
            "population_moe"
        ],
        "page_layout": {
            "rows": {
              "top": [
                  "base_unweighted",
                  "base_weighted"
              ],
              "bottom": [
                  "population",
                  "base_weighted",
                  "base_unweighted",
                  "scale_mean",
                  "scale_median",
                  "scale_std_dev",
                  "scale_std_err",
                  "significant_columns"
              ]
            },
            "measure_layout": "wide"
        },
        "pairwise_comparison": {
            "compare_by": "column",
            "sig_threshold": [0.05, 0.1],
        }
    }
}

viz_specs.default 🔗

This section includes settings that apply as a fall-back to multiple visualization types, for example both tables and charts. Certain settings here can be overridden by the same key:value pair in a visualization-specific section, such as viz_specs.table.

Name Type Description
default.format.decimal_places obj Object representing the decimal places options: {“percentages”: 0, “moe”: 1, “other”: 2}
default.format.show_empty bool Specifies whether a row or column containing no valid responses will be displayed.
default.measures array This optional array field specifies the (single) second-order analysis (SOA) measure to display in the visualization. If present, it must contain exactly one measure keyword.

viz_specs.table 🔗

This section includes settings that apply only to the “table” visualization type. A setting in this section has a higher precedence than the same setting in viz_specs.default when the visualization-type is “table”.

Name Type Description
table.format.pval_colors bool Specifies whether value-cells should be shaded red or green depending on the p-value (a statistical-significance measure) of that cell.
table.measures array This optional array field can specify multiple SOA measures to appear in a table visualization. At present, only a table visualization can display multiple measures. This field may be omitted, but if present must contain at least one measure. For the full list of available measures, refer to the fields options at https://docs.crunch.io/endpoint-reference/endpoint-multitable.html#options.
table.page_layout.measure_layout str Optional enumerated-string field containing either “wide” or “long”
table.page_layout.rows obj Optional object field specifying the summary rows to appear in the exported table.
table.pairwise_comparison obj This optional object field specifies settings that govern pairwise significance testing. In an exported table, this appears as the addition of alphabetical column headings and a pairwise_t_test measure indicating which other-column cells are pairwise-significant by their column letter, e.g. AcdGj. e.g. “pairwise_comparison”: {“sig_threshold”: [0.05, 0.1]}

PATCH 🔗

To edit an analysis, PATCH its URL with a shoji:entity.

The editable attributes are:

  • query
  • query_environment
  • display_settings
  • transform
  • viz_specs

Providing invalid values for those attributes or extra attributes will be rejected with a 400 response from the server.

Editing an analysis query on a public deck cannot add reference to a secure variable; such a request results in a 400 response. Hidden variables, however, are permitted.