Provides a chart drawing feature for data entries and surveys. Integrates REDCap with third-party chart libraries - currently Charts.js and Chartist are supported. Piping can be used on field configuration, so charts may display facts to survey participants based on their previous answers.

• REDCap >= 8.0.3

• Clone this repo into <redcap-root>/modules/redcap_chart_field_v<version_number>.
• Go to Control Center > Manage External Modules and enable REDCap Chart Field.

Two amazing third-party chart libraries are supported by this module - Chart.js and Chartist.

This section will walk you through a few steps to setup a Charts.js chart, dynamically populated via Piping.

The following fields will be used to provide data to populate our chart example. Note the variable names - they will be referenced later on.

To configure a chart it helps to have data in the input fields. For this example we'll use the data shown here.

To create a chart field, access Online Designer's field creation modal, and then select Descriptive Text. You may see a checkbox named Is chart.

Once you click on Is chart checkbox, a few extra fields are shown:

To fill these fields out it is very important to get familiar with the documentation provided by the third-party chart library you chose. The inputs are expected to be Javascript objects that follow a particular structure defined by the library. The better you understand the configuration syntax the richer your charts can be.

Though this sounds very technical, no software development skills are required to manipulate these parameters. For most of cases you need only copy & paste a suitable example from documentation. Then make slight changes to adapt it to your needs.

Let's create a bar chart by using the main example from Chart.js official documentation as base.

<canvas id="myChart" width="400" height="400"></canvas>
<script>
var ctx = document.getElementById("myChart").getContext('2d');
var myChart = new Chart(ctx, {
    type: 'bar',
    data: {
        labels: ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
        datasets: [{
            label: '# of Votes',
            data: [12, 19, 3, 5, 2, 3],
            backgroundColor: [
                'rgba(255, 99, 132, 0.2)',
                'rgba(54, 162, 235, 0.2)',
                'rgba(255, 206, 86, 0.2)',
                'rgba(75, 192, 192, 0.2)',
                'rgba(153, 102, 255, 0.2)',
                'rgba(255, 159, 64, 0.2)'
            ],
            borderColor: [
                'rgba(255,99,132,1)',
                'rgba(54, 162, 235, 1)',
                'rgba(255, 206, 86, 1)',
                'rgba(75, 192, 192, 1)',
                'rgba(153, 102, 255, 1)',
                'rgba(255, 159, 64, 1)'
            ],
            borderWidth: 1
        }]
    },
    options: {
        scales: {
            yAxes: [{
                ticks: {
                    beginAtZero:true
                }
            }]
        }
    }
});
</script>

Note the sections above labeled type, data, and options. Those map to the REDCap Chart Field properties Chart type, Chart data, and Chart options, respectively. The canvas_width and canvas_height fields map to the Chart width and Chart height REDCap Chart Field properties.

1. Type: Bar
2. Data:

{
    labels: ["Red", "Blue", "Yellow", "Green", "Purple", "Orange"],
    datasets: [{
        label: '# of Votes',
        data: [12, 19, 3, 5, 2, 3],
        backgroundColor: [
            'rgba(255, 99, 132, 0.2)',
            'rgba(54, 162, 235, 0.2)',
            'rgba(255, 206, 86, 0.2)',
            'rgba(75, 192, 192, 0.2)',
            'rgba(153, 102, 255, 0.2)',
            'rgba(255, 159, 64, 0.2)'
        ],
        borderColor: [
            'rgba(255,99,132,1)',
            'rgba(54, 162, 235, 1)',
            'rgba(255, 206, 86, 1)',
            'rgba(75, 192, 192, 1)',
            'rgba(153, 102, 255, 1)',
            'rgba(255, 159, 64, 1)'
        ],
        borderWidth: 1
    }]
}

3. Options:

{
    scales: {
        yAxes: [{
            ticks: {
                beginAtZero:true
            }
        }]
    }
}

4. Canvas width: 400
5. Canvas height: 400

Here's how those values look pasted into the REDCap Chart Field properties.

Note the highlighted area on image above - Piping is being used in order to dynamically populate the chart data ([data_1], [data_2], etc) - so each record entry or survey has its own chart results.

Obs.: as the example above, Piping wildcards must be used between quotes (single or double), e.g. '[data_1]'.

Note also that piping data from a REDCap field is optional. You could present a chart with static data or use a mix of static and piped data.

For this particular case - recall the input given on Chart source data section - we have the following result chart when accessing the field in a survey:

In this section we will go through the analogous example for Chartist library, using the same source data. This time we'll draw a line chart.

The process of mapping a Chartist example is similar to the previous section on Chart.js

/* Add a basic data series with six labels and values */
var data = {
  labels: ['1', '2', '3', '4', '5', '6'],
  series: [
    {
      data: [1, 2, 3, 5, 8, 13]
    }
  ]
};

/* Set some base options (settings will override the default settings in Chartist.js *see default settings*). We are adding a basic label interpolation function for the xAxis labels. */
var options = {
  axisX: {
    labelInterpolationFnc: function(value) {
      return 'Calendar Week ' + value;
    }
  }
};

/* Now we can specify multiple responsive settings that will override the base settings based on order and if the media queries match. In this example we are changing the visibility of dots and lines as well as use different label interpolations for space reasons. */
var responsiveOptions = [
  ['screen and (min-width: 641px) and (max-width: 1024px)', {
    showPoint: false,
    axisX: {
      labelInterpolationFnc: function(value) {
        return 'Week ' + value;
      }
    }
  }],
  ['screen and (max-width: 640px)', {
    showLine: false,
    axisX: {
      labelInterpolationFnc: function(value) {
        return 'W' + value;
      }
    }
  }]
];

/* Initialize the chart with the above settings */
new Chartist.Line('#my-chart', data, options, responsiveOptions);

Again, you don't need to be a developer to manipulate this information. You need only to copy and paste the correct sections of some example code into the appropriate form fields and make some minor edits:

1. Type: Line
2. Data:

{
  labels: ['1', '2', '3', '4', '5', '6'],
  series: [
    {
      data: [1, 2, 3, 5, 8, 13]
    }
  ]
}

3. Options:

{
  axisX: {
    labelInterpolationFnc: function(value) {
      return 'Calendar Week ' + value;
    }
  }
}

3. Responsive options:

[
  ['screen and (min-width: 641px) and (max-width: 1024px)', {
    showPoint: false,
    axisX: {
      labelInterpolationFnc: function(value) {
        return 'Week ' + value;
      }
    }
  }],
  ['screen and (max-width: 640px)', {
    showLine: false,
    axisX: {
      labelInterpolationFnc: function(value) {
        return 'W' + value;
      }
    }
  }]
]

As we've done on Chart.js section, we are using Piping to make chart data dynamic.

Note that the configuration for Chartist is slightly different - there are no canvas dimension fields, and Chart responsive options field is added. Check the official Chartist documentation to understand how it works.

In our example, width and height are specified to the Chart options field to show that is also possible to define chart dimensions with Chartist.

Here is a line chart drawn using Chartist