17  Graphical user interface - Shinyscan

The scan package includes a graphical user interface (GUI) that enables users to perform a wide range of operations and analyses supported by the package. This GUI is implemented as a Shiny application that runs in a standard web browser.

shinyscan was originally developed as a tool for teaching purposes. To facilitate this, the application displays the corresponding R syntax for each operation executed via the interface. Beyond its pedagogical utility, shinyscan is also well-suited for exploratory data analysis, and the visual presentation of results with immediate feedback.

17.1 Start shinyscan

To run the shiny app, you need to install two additional packages: shiny and scplot.

install.packages(c("shiny", "scplot"))

You can start the app by executing the function shinyscan() from the scan package. Based on your system settings, the app will immediately be opened within your standard browser or in R-Studios internal viewer pane:

In case the app starts within the internal viewer pane, I recommend that you click Open in Browser.
The app is organized into seven main menus (tabs), each serving a specific function:

  • Data: Create new datasets, load and save existing ones, and access example datasets.

  • Transform: Perform data selection, filtering, and other transformations.

  • Stats: Conduct statistical analyses using various single-case methods.

  • Plot: Generate and export single-case design plots.

  • Power-test: Perform power analyses tailored to single-case designs.

  • Settings: Modify the default behavior and preferences of the application.

  • Help: Access additional documentation and external resources.

By default, shinyscan opens with the Data tab selected.

17.2 Data menue

17.2.1 Input cases

The Data tab in shinyscan allows you to manually create single-case datasets (scdf, see Section 3.2). This is particularly useful for small datasets without having to write R code. The interface is divided into several input fields:

Values

Provide the central dependent variable and phase structure of the scdfs with the values of a named vector. For example, A = 1,2,3,4, B = 8,7,8,9,8,7, C = 8,7,6,7,6,5. You can use line breaks to structure your data entry (you can remove the comma at the end of each line if you wish):

A = 1,2,3,4
B = 8,7,8,9,8,7
C = 8,7,6,7,6,5

Measurement times

Here you can optionally enter measurement times. If no measurement times are specified, they are automatically set to 1, 2, 3, ..., n.

Additional variables

Add additional variables in the style: [varname] = value, value, value, value, ....

If you want to add several variables, use line breaks:

engagement = 1,5,4,3,6,5
support = 3,4,2,5,6,4

Case name

An optional case name.

The Add case button adds the new case to the existing scdf.

The button Remove case deletes a case.

The Clear all cases button deletes the entire scdf.

The Position section is useful if you want to delete (or add) a case at a specific position.

After clicking on the Add case button, you will get a summary of the current scdf in the right output area:

You can continue to add several more cases.

Use the Save scdf button to save the scdf to your local hard drive. By default the output file has the following name: scdf followed by the number of cases, followed by the phase names, the date and time: (e.g., scdf-01-ABC-250322-130744.rds). By default, files are saved in Rs standard file format rds. The file format and filename can be changed in the Settings tab.

If you want to see the R syntax, go to the Settings tab and change show output as according to syntax:

Switch back to Data –> New and the output will show R syntax:

17.2.2 Load existing data files

Switch to Data -> Load:

To open an scdf file, click Open file and choose the file from your hard disk.

Four file types are accepted:

  1. An .rds file containing the scdf (e.g., created with save scdf). See Section 3.3.

  2. An .R file containing a syntax for creating an scdf. This text file must create an object called study which contains an scdf. Here is an example:

case1 <- scdf(c(A = 58, 56, 60, 63, B = 51, 45, 44, 59, 45, 39, 83))
case2 <- scdf(c(A = 47, 41, 47, 52, 54, 65, B = 55, 37, 51, 60, 60, 65, 55, 46))

study <- c(case1, case2) 
  1. A comma separated values .csv file (see Section 3.4.1 for more information on the structure of these files).
  2. An Microsoft Excel .xlsx file (see Section 3.4.1 for more information on the structure of these files).

If your data file contains a valid scdf object, the output pane will give you specific information about the data file:

17.2.3 Load an example data file

Select an example from the drop down list:

A summary of the selected scdf is displayed in the output pane:

You can now continue with the loaded or example scdf or go to Data -> New to modify the dataset.

17.3 Transform

The Transform tab allows you to modify, create, recalculate etc. new variables from your scdf.

If you make any changes here, all operations in other tabs (stats, plot etc.) will be based on the transformed scdf.

This tab also displays the raw-data contained in the scdf.

Select cases

Select cases either by case number or by case name. Use commas to select multiple cases and a colon to select ranges of cases (e.g. 1, 7:9, 10).

Combine phases

This option is specifically designed for later analyses that compare exactly two phases (such as overlapping indices). If your scdf has more than two phases, you can define which phases are Phase A and Phase B. You can combine multiple phases into one phase by selecting multiple phases separated by commas. Select phases by number (1 for 1st, 2 for 2nd etc.) See Section 9.1.1 for more details.

Filter measurements

This takes a logical expression defining a selection of measurements. You can use variable names within your scdf and R functions. For example, if you want to select all measurements above 6 you code values > 6. If you want to select all measurements whose values are above the median of Phase B, you code values > median(values[phase == "B"]). See Section 4.2.

Transform variables

This section allows you to create and modify variables in a complex way. For example, for create a new variable with standardised values code values_std = scaled(values). See Section 4.3 for a detailed description of the syntax.

Set dependent variable

If your scdf has multiple dependent variables, you can switch them for the further analysis and display in this field (see Chapter 6).

Clicking on Save transformed scdf will save the transformed scdf to your hard drive.

17.4 Stats

The purpose of this tab is to select and refine analyses procedures. The following section will provide an explanation of the functionality of the GUI. For more detailed descriptions and explanations of the statistical procedures, refer to the respective sections of this book.

The Statistic field serves as the gateway to a range of procedures. By default, teh descriptives of the scdf are presented.

Output format allows to switch to html output which possible for some, but not all functions (see Chapter 16 for details):

For some outputs it is possible to flip rows and columns for a better overview:

For some procedures, specific output arguments can be set (either for their respective print() - text output - or export() - html output - functions). For example most html outputs allow to specify the number of decimals (e.g. decimals = 3).

Save output saves the output content. The save format (text, html, or docx) is based on the setting defined in the Settings tab.

17.4.1 Function arguments

If you choose a statistical procedure which takes additional arguments, a list of the available arguments will be provided on the left pane. Here is an example for the hierarchical piecewise regression function. All arguments are provided with their respective default settings (please refer to the respective section in this book ot the help files for detailed explanations of the arguments):

17.5 Plots

Within the plot tab you can create graphs based on the scplot function (see Chapter 5 for details).

If you have a valid loaded/ created a valid scdf, a standard scplot will e shown here.

The Arguments section is textfield that allows to specify the plot. It takes one line for each scplot function.

  add_statline("mean")
  add_legend()

scplot has an extensive range of options. The three dropdown menus provide a selection of syntax examples. By clicking an example, it is added to the Arguments text field and can be specified for your specific needs. Clicking an argument does not replace previous arguments. If you want to remove a plot element, you have to remove the line from the Arguments text field.

Stats templates provides syntax for adding statistical lines and curves to the graph.

Design templates adds syntax for changing various design elements like a title, footnotes, a legend etc. It also has examples to specify colours and themes.

Annotate templates gives examples to add text, marks etc. to the plot.

By clicking Save plot, a png file of the plot will be exported. In the Settings tab, filename and size of the plot can be specified.

17.6 Settings

The Settings tab allows users to customize various aspects of shinyscan’s behavior. The available options are grouped by functional area:

17.6.1 Data

Show output as defines whether the output in the Data tab is shown as R syntax (print(scdf)) or as a summary (summary(scdf)).

Syntax phase structure specifies the coding of the phase structure when Show output as is set to Syntax.

Prefix save filename defines a prefix used for automatically generated filename when exporting the scdf.

Save format sets the export format of the scdf file.

17.6.2 Transform

Show output as defines whether the scdf is displayed in hml or text format.

Prefix save filename defines a prefix used for automatically generated filename when exporting the transformed scdf.

Save format sets the export format of the scdf file.

17.6.3 Stats

Syntax with defaults If set to Yes, the generated R syntax includes all function arguments, including those set to their default values. This can be useful for teaching and documentation.

Rename predictors allows choosing among three naming conventions for predictors in the regression output.

Prefix save filename defines a prefix filenames generated when exporting statistical results.

Save format sets the export format.

17.6.4 Plot

Prefix save filename defines a prefix for filenames when exporting plots.

Export width / height / dpi set the dimensions and resolution of the exported .png file.

17.6.5 General

Html_engine specifies the internal engine used to generate HTML tables, either via the gt or kableExtra package (for scdf and statistical results). Only gt currently supports exporting tables in .docx format. The kableExtra engine is retained for compatibility purposes but may be deprecated in future versions of the package.