REDCap: Project Dashboards, Smart Functions and Smart Charts
Overview of Project Dashboards
Project Dashboards are pages with dynamic content that can be added to a project. In combination with Smart Variables, Smart Functions, Smart Tables and Smart Charts to produce simple aggregation or visualization of data collected in a project.
Project Dashboards can be set with a public URL, allowing you to display information to people who are not REDCap users on the project, without needing to utilize surveys. However, if you do choose to use a Public Dashboard do not include PHI on the report. Anyone with the public dashboard link will be able to view the data, even if they are not the intended recipient of the information.
There is a menu on the left-hand navigation in REDCap where you can set up Project Dashboards. You can set up new dashboards and manage existing ones. If you have existing dashboards in a project, you will see a list of them. You can choose to view them, edit, copy or delete.
Tip: If you are creating complex dashboards that have a similar structure, using the "Copy" feature can save you significant setup time!
Getting Started with Project Dashboards
In the left-side menu of REDCap there is an option for Project Dashboards. Clicking into this link will open up the page shown below that will let you add and customize your dashboards.
There is a setup wizard to help you with creating a dashboard using the dashboard smart variables. The syntax for using the smart variables can be quite complex. The wizard provides an intuitive editor allowing you to select the variables you are interested in and how to filter them. The wizard will output the syntax that you need to insert into the dashboard. Make sure to copy the generated Smart Variable syntax before you exit the wizard. You can then paste into the location on the dashboard that you want the information to display. You can use the wizard to help you set up any type of smart function, chart or table. Note: Advanced formatting may require that you manually add parameters, especially if you are setting multiple parameters for a single smart variable.
Data May be Slightly Out-of-Date in Dashboards: Project dashboards may be querying significant amounts of data in your project in order to give the results for aggregate functions or charts/tables. In order to not impact the overall performance of REDCap, project dashboards only check for updated data once every 10 minutes. At the top right of a dashboard, there will be an indicator showing when the data was last cached. If you are logged in to REDCap and viewing a dashboard, you will see a "Refresh" link at the top right to automatically update to the most current data. You will only see the refresh button when the data is at least 30 seconds old. For public dashboards, there is no refresh link available.
Project dashboards are able to exported to a single-page PDF. Note: You can disable export of specific charts or tables by setting an optional parameter.
Note: Project Dashboards and Smart Functions, Smart Charts and Smart Tables do NOT currently work in the REDCap Mobile App (for offline data collection.) The REDCap development team is planning to eventually add these features to the mobile app, but at this time they will not function in the mobile app. (Reminder: The mobile app is intended for offline data collection. Dashboards will still be able to load within a browser on a mobile device that is connected to the internet.)
Organizing Dashboards
The Organize option is available to organize your project dashboards into different sub-folders. These folders are collapsible to reduce the number of dashboards displayed at one time. This can help make specific dashboards or groups of dashboards easier to find.
Privacy and User Rights in Project Dashboards
User Rights in Project Dashboards
You are able to set user-specific rights to access a dashboard. You can choose either specific users or specific Data Access Groups (DAGs)who can view a specific dashboard. This is similar to the access you can set for specific reports. Important notes on user access:
- DAG Permissions are NOT applied by default: For a user assigned to a DAG, they will see all data for the project except for in these cases:
- When a Smart Function/Table/Chart uses a unique report name as a parameter- if that report is filtered by DAG.
- When using the optional parameter ":user-dag-name", then a user who is assigned to a DAG will only see data from their DAG.
- A user does not need access to a report to see a dashboard based on the report. You must also restrict access to the specific dashboard to not allow users to view the data filtered by the report. This applies even if a user does not have access to the report.
Data Privacy in Project Dashboards
Smart Functions/Tables/Charts are intended to display aggregate data. However, if there are a small number of records for a particular filter, then displaying values in a scatter plot could represent a threat to an individual's privacy if the information is displayed on a public dashboard. For this reason, the minimum number of records required to display Smart Functions/Tables/Charts is 11. If a public dashboard is loaded when there are very few records for certain categories, then a message reading [INSUFFICIENT AMOUNT OF DATA FOR DISPLAY] will display instead. If the message is clicked on, a pop-up about the minimum data requirements will display.
This setting does not apply for logged-in users and non-public dashboards. Smart Functions/Tables/Charts will always display for users who are authenticated (logged in), even if there are less than 11 records.
Make Your Dashboard Public:
When you are editing a dashboard, there is a section at the top that allows you to set the dashboard as "public":
A public dashboard will have an automatically generated URL that you can copy and paste to share with others. You can also set a custom short link, which will start with https://redcap.link/.
A dashboard that is public will load for anyone who has the correct URL. However, a public dashboard will not show up in search engine search results.
Smart Functions, Smart Tables, Smart Charts
Smart Functions, Tables and Charts are new types of Smart Variables that can provide aggregate information across records. See our full reference of Smart Variables in REDCap for other types of smart variables that load contextual information.
Note:The new aggregate smart variables are able to aggregate simple information across records. However, they can also be used within a specific record (e.g. to create an average of a variable that is collected multiple times for one participant.) To do this you would set the optional parameter ":record-name" which would pull data only for the current record.
Smart Functions
Smart Functions are smart variables that evaluate data in a context-dependent way, but produce aggregate results. You can use Smart Functions to produce project-level aggregates (e.g. average and standard deviation for age of all participants) or to aggregate information within a record (e.g. aggregate
List of Aggregate Smart Functions:
The following Smart Functions will aggregate data for you. Specify one or more fields, and any optional parameters where indicated:
- [aggregate-min:fields:parameters]: The minimum value of a field across all records in a project.
- [aggregate-max:fields:parameters]: The maximum value of a field across all records in a project.
- [aggregate-mean:fields:parameters]: The mean/average of a field across all records in a project.
- [aggregate-median:fields:parameters] The median value of a field across all records in a project.
- [aggregate-sum:fields:parameters]: The sum of all values for a field across all records in a project.
- [aggregate-count:fields:parameters]: The count of all values in a field across all records in a project.
- [aggregate-stdev:fields:parameters]: The standard deviation of a field across all records in a project.
- [aggregate-unique:fields:parameters]: The number of unique values in a field across all records in a project.
Multiple fields may be used in each Smart Function, which will aggregate the values across all values for all of the fields. (e.g. if you have two different "height" fields for participants in different arms of a study, then you could list both variable names to get the average of all participants.)
Record Counts: Using the aggregate-count Smart Function on the unique record ID for a project will function in a special way - it will not count the literal number of data values in a field but will return the count of the total number of records in the field. This avoids artificially inflated record counts because of your project having a longitudinal setup or repeating instruments. This is an easy way to quickly display the total number of records in a project.
Smart Functions can be used in anywhere in a project where piping is permitted, including inside calculations, branching logic or report filters.
Smart Tables
Smart Tables are tables that automatically display aggregate descriptive statistics. A Smart Table will list the results of any or all of the following stats functions:
- minimum
- maximum
- mean/average
- median
- sum
- count
- standard deviation
- count of missing values
- count of unique values
Smart Tables can be inserted with the Smart Variable [stats-table]. List the variables you would like to display as a parameter, separated by commas. (e.g. [stats-table: variable1, variable2] will display a table with variable1 and variable2 in separate rows.
Display Only Some Columns: By default, all columns are displayed in a Smart Table. If you would only like some columns displayed, then you can list them as a parameter using the following designations separated by commas: count, missing, unique, min, max, mean, median, stdev, sum. For example, [stats-table:field1,field2,field3:mean,max].
Prevent Export:By default, each table will have an "Export table (CSV)" link underneath it to allow download of the data displayed. If you would like to disable this feature for a specific table, attach ":no-export-link" to the Smart Variable. For example, [stats-table: variable1, variable2: no-export-link].
Smart Charts
Smart Charts allow you to display simple plots and charts utilizing aggregate Smart Function data. Note: Smart Charts have limited ability to display data that requires multiple filters or to track data over time. Smart Functions and Smart Charts do not have the power of statistical analysis or data visualization software. Smart Charts are most useful for simple categorical data.
- Colors are preset and are not modifiable.
- Accessibility: Smart Charts are automatically enabled with the option to switch to a color-blind friendly display.
- When to Use: Smart Charts can be used anywhere in a project where piping is allowed
- Click to Enlarge: When viewing a dashboard Smart Chart, it can always be enlarged by clicking on it.
Bar Charts
| Description / Syntax | Chart Display |
|---|---|
|
Bar Chart with a Single Multiple Choice Variable Smart Variable syntax for this chart: |
 |
|
Vertical Bar Chart, Grouped by Another Variable Smart Variable syntax for this chart: |
 |
Line Charts
| Description / Syntax | Chart Display |
|---|---|
|
Line Chart with Two Fields Smart Variable snytax for this chart: |
 |
|
Line Chart with a Third Variable for Grouping Smart Variable syntax for this chart: |
 |
Scatter Plots
| Description / Syntax | Chart Display |
|---|---|
|
Scatter Plot of Two Fields Smart Variable syntax for this chart: |
 |
|
Scatter Plot with a Third Variable for Grouping Smart Variable syntax for this chart: |
 |
Pie Charts
| Description / Syntax | Chart Display |
|---|---|
|
Pie Chart Smart Variable syntax for this chart: |
 |
Donut Charts
| Description / Syntax | Chart Display |
|---|---|
|
Donut Chart Smart Variable syntax for this chart: |
 |
Optional Parameters for Smart Functions, Smart Tables and Smart Charts
There are a number of optional parameters that can be used with Smart Functions/Tables/Charts:
- :R-XXXXXXXXXX Unique Report Name - For Aggregate Functions, Charts, and Tables, filter the data being used by appending a Unique Report Name. Next to each report on the 'My Reports & Exports' page is its unique report name, which has 'R-' following by alphanumeric characters. By default, all Aggregate Functions, Charts, and Tables will use the values of all records in the project, but if a unique report name is appended to any of them, only data from that specific report will be used. Using a report as a surrogate to filter data is a very useful technique of performing complex filtering logic for Aggregate Functions, Charts, and Tables.
- :record-name - For Aggregate Functions, Charts, and Tables, filter the data being used to the *current record* by using the literal value 'record-name'. Note: This parameter will only work in a context where a single record is being viewed/accessed, such as on a survey page, data entry form, etc. This parameter can be used with any of the other parameters except unique report names.
- :event-name - For Aggregate Functions, Charts, and Tables, filter the data being used to the *current event* (longitudinal projects only) by using the literal value 'event-name'. Note: This parameter will only work in a context where a single record/event is being viewed/accessed, such as on a survey page, data entry form, etc. This parameter can be used with any of the other parameters except unique report names.
- :unique-event-names Unique Event Names - For Aggregate Functions, Charts, and Tables, filter the data being used to specific events (longitudinal projects only) by providing an event's unique event name (found on the Define My Events page). You may use one or more unique event names (comma-separated). Note: This parameter can be used with any of the other parameters except unique report names.
- :user-dag-nameFor Aggregate Functions, Charts, and Tables, filter the data being used to the records assigned to the *current user's Data Access Group* by using the literal value 'user-dag-name'. Note: This parameter will only work in a context where an authenticated user belongs to a project and has been assigned to a DAG in the project (this excludes survey pages and public project dashboards). This parameter can be used with any of the other parameters except unique report names.
- :unique-dag-names Unique DAG Names - For Aggregate Functions, Charts, and Tables, filter the data being used to the records assigned to specific Data Access Groups by providing a DAG's unique group name (found on the Data Access Groups page). You may use one or more unique DAG names (comma-separated). Note: This parameter can be used with any of the other parameters except unique report names.
- :bar-vertical - Display a bar chart with the bars going vertically instead of horizontally (the default) by using the literal value 'bar-vertical'. Note: This parameter can be used with any of the other parameters.
- :bar-stacked - Only for bar charts using two fields, display the bar chart with the bars stacked on top of one another for each choice. Whereas the default view is that the bars of each field are displayed side by side to show the color grouping. To enable this, use the literal value 'bar-stacked'. Note: This parameter can be used with any of the other parameters.
- :no-export-link - Only for bar charts using two fields, display the bar chart with the bars stacked on top of one another for each choice. Whereas the default view is that the bars of each field are displayed side by side to show the color grouping. To enable this, use the literal value 'bar-stacked'. Note: This parameter can be used with any of the other parameters.