sdstudio

A companion package as GUI support for surveydown.

Website GitHub CRAN R-univ

Paper

Journal Paper - JOSS (Under Review)

Hu, P., Bunea, B., & Helveston, J. P. (2025). sdstudio: A Companion Package for Designing and Managing surveydown Surveys. Journal of Open Source Software (Under Review).

JOSS Review PDF

Video

Below is a brief walkthrough video of the sdstudio package:

Intro to sdstudio

Getting Started

Installation

Installing sdstudio:

# Option 1: install from CRAN
install.packages("sdstudio")

# Option 2: install from GitHub
pak::pak("surveydown-dev/sdstudio", ask = FALSE)

Make sure to install surveydown as well:

# Option 1: install from CRAN
install.packages("surveydown")

# Option 2: install from GitHub
pak::pak("surveydown-dev/surveydown", ask = FALSE)

Launch

Simply call the launch() function to start the studio:

sdstudio::launch()

The sdstudio interface is organized into three main tabs that follow the natural survey workflow:

• 🏗️ Build: Visual survey creation with side-by-side structure and scripts
• 👁️ Preview: Real-time survey testing
• 📊 Responses: Data collection, analytics, and export capabilities

The “Build” Tab

Start from a Template

The “Build” tab is your workspace of survey construction. You can either start from a prepared template or continue with your own survey files. The “Directory” will show your current working directory, but you can change it to any directory where your survey files are stored.

Note

We currently have 16 templates to choose from. The default template contains a minimum basic structure for a clean start. You might also try the question_type template for a showcase of all question types, or try some advanced features with conditional_display, conditional_navigation, etc. For a full list of templates, go to the surveydown-dev GitHub site and search for any repo starting with “template_”.

Start from a Template in the Build Tab

Build Your Survey

After you’ve selected your template, or if you already have an existing survey, you’ll see the dual panel of survey constructions on the “Build” tab. The “Structure” section on the left shows the page-content structure of your survey. The “Code” section on the right displays the survey scripts in a code editor.

Dual Panel of the Build Tab

The Structure Section

The “Structure” section on the left gives you 2 hierarchies: page and content. The pages can be toggled on to show the content, or toggled off. There are two types of content: questions and texts, with labels of “Q” and “T”, respectively.

There are buttons on each page and content which self-explain their capabilities. The “Add A New Page” button at the bottom allows you to create a new page.

The question content shows question ID, question type, and question label. You can review the full question details with the edit button, or view the full question definition code on the code section. The text content shows the first 5 words of the full piece of text.

Click on the +T/+Q button to add a text/question

All elements support drag-n-drop operations. After each operation, the structure will refresh and update the code editor on the right. If you move two test elements together, they will merge in to one text element.

Dragging two texts together will merge them

The Code Section

Note

For now the surveydown Studio has powerful support to survey.qmd because it is meant to be the main file for survey construction. However, even though app.R is directly editable, we still recommend that you edit it using your IDE or other text editors. All our templates have the app.R file ready to run, which can be a good starting point.

The “Code” section on the right is an integrated code editor that allows you to edit the survey scripts directly, with the survey.qmd file opened by default. It also reflects any operation you’ve done on the “Structure” section. The other file, app.R, is available for direct editing as well.

The “Preview” Tab

The “Preview” tab is where your survey comes to life. It provides a real-time, interactive preview of your survey as you build it, allowing you to see exactly how respondents will experience your survey.

Live Rendering

Every time you make changes in the Build tab, the survey is live-rendered and revealed in the Preview tab. It takes a couple of seconds to render, so if you switch to the Preview tab too early, you’ll see message of survey being rendered. After rendering is done, the survey will be available.

The survey preview is live and interactive

Desktop and Mobile Views

You can toggle between “Desktop View” and “Mobile View” using the pair of buttons at the top right corner:

Toggling between desktop and mobile views

New Sessions

You might have noticed there is a green refresh button on the top right as well. This is for you to manually refresh the preview if you want to restart a session:

Restart a new session using the refresh button

The “Responses” Tab

We built sdstudio for two purposes: for designing surveys and for managing survey response data. You can use the studio for either or both purposes.

The “Responses” tab is used to view two forms of survey response data:

1. Local Mode: This mode allows you to view “preview data” while locally previewing your survey without having a database connection. The preview data are stored in a local “preview_data.csv” file and are purely available for the purposes of previewing what your data will look like once you have a database connection.
2. DB Mode: After creating and testing your survey, you can add a database connection to start collecting survey responses in your live database.

Lets go through each of these use cases in details.

Local Mode

All our templates have Local Mode enabled by default, because we recommend you to start from local testing. To start with your local testing, you can simply go through all 3 tabs in order: Build, Preview, and then Responses.

Below is a brief walkthrough of the process:

Build, Preview, and Responses in Sequence

DB Mode

Note

For instructions on how to obtain your database credentials, see the Storing Data documentation page.

To get started with viewing your database response data, you need to firstly switch to DB Mode by clicking the “DB Mode” button on the top right corner. This is available in all 3 tabs. Then, in your “Responses” tab, you’ll see a “Database Connection” section on the top. Toggle on the “Settings” button and fill in your database credentials. You can test the connection by clicking the “Test Connection” button. If you have already set up your database credentials using sd_db_config() to create a local .env, then your credentials should show here.

In order to have a clean start, we recommend you to name a new table in the “Table” field of “Database Connection”. Upon clicking “Test Connection”, this table will only be a placeholder, and the database will create such table once you start your first survey run.

Input your credentials and create a new table

If the connection is successful, you will see a “Connected” status message in green. The “Choose a table to view” section will show the new table you just created, but all fields will be empty. They will be filled in once you run your survey in the Preview tab.

After you’ve taken care of the database connection, you can go back to the Build tab and proceed with your survey construction, following the exact same steps. The only difference is that now, when you run the survey in the Preview tab, your responses will be stored in the database table you just created instead of the local “preview_data.csv” file.

Viewing other tables

It is important to note that you can use the “Responses” tab to view all tables stored in your database. For example, if you have multiple surveys you are working on (each in a separate folder) that share the same database, you can select other tables to view from the “Responses” tab.

Input your database credentials

If the connection is successful, you will see a “Connected” status message in green. You can choose your desired response table from the dropdown menu, review its progress and details, and download the csv file if needed:

Fill in your database credentials and click on the “Test Connection” button

Data Security

The .env File

When you input your database credentials in the “Responses” tab, it creates a local .env file in your current working directory, which is a hidden file. This file is used to store environment variables securely. Along with this file, there will be a .gitignore file created with .env added to prevent it from being accidentally pushed to your git repository. This is a good practice to keep your credentials safe.

In this .env file, you will find the following variables:

# Database connection settings for surveydown
SD_HOST="your-database-host"
SD_PORT="your-database-port"
SD_DBNAME="your-database-name"
SD_USER="your-database-username"
SD_PASSWORD="your-database-password"
SD_TABLE="your-database-table"

The editing of this file is bi-directional, so you can either edit on this file, or use the sdstudio interface.

GSSAPI Encryption

The sdstudio::launch() function allows the gssencmode argument. It controls the encryption mode for database connections. This is crucial for ensuring secure communication with your database, especially when handling sensitive survey data.

By default, we set gssencmode = "auto", which attempts to use GSSAPI encryption if available, falling back to a plain connection if not. This is the recommended mode for most users. The connection status will show a green “Connected (GSSAPI enabled)” message if GSSAPI is successfully enabled, or a yellow “Connected (GSSAPI disabled)” message if it falls back to plain connection:

# Auto mode (recommended) - tries GSSAPI first, falls back if needed
sdstudio::launch()

However, if you want to explicitly control the encryption mode, you can set gssencmode to one of the following values:

# Prefer mode - only use GSSAPI
sdstudio::launch(gssencmode = "prefer")

# Disable mode - forces plain connection (useful for VPN environments)
sdstudio::launch(gssencmode = "disable")

Conclusion

As a companion GUI for the surveydown platform, sdstudio significantly simplifies the survey creation process. It allows users to build, preview, and manage surveys through an intuitive interface, without requiring extensive programming skills. The three-tab workflow - Build, Preview, and Responses - provides a comprehensive solution that covers the entire survey lifecycle.

If you have any questions or feedback you’d like to share, please drop us a line using GitHub Discussions.

---

For more information, visit the sdstudio documentation or explore the surveydown platform.