Canvas

Owned by Eric E. Snyder (Unlicensed)
Last updated: Sep 01, 2016
10 min read

RequirementCanvas
Section3.2.4.2
JIRA Task

EIR-65 - Getting issue details... STATUS

Reviewed ForDate
Conventional spacing between sections2016-08-31

Introduction

In Visual Dashboard, the Canvas is the area where the dashboard gadgets are positioned after configuration. These gadgets display the output of the analyses carried out on the current project data, including any Defined Variables and subject to the active Data Filters. Canvas data can be exported to MS Excel or Word files, preserving most of the internal structure and organization of the individual gadgets. The Canvas can also be saved independently of the data, keeping a link to the data source, and storing the configuration of every gadget, Data Filter and Defined Variable in the canvas file. Functionally, the right mouse button accesses the Options Menu, where the user may select gadgets to deploy. The Defined Variables and Data Filters tools are accessed from tabs located on the left and right edges of the Canvas, respectively. Their interfaces open into the Canvas when selected using the tab or the corresponding Toolbar button.

 

Canvas Properties

Overview

As described in Navigation, the Visual Dashboard Canvas has three modes (or views) controlled by a pull-down menu on the Toolbar: Analysis, Data, and Variables. The Data mode displays a listing of all records in the database, subject to the currently selected Data Filters. The Variables mode displays a data dictionary describing those variables. The Analysis mode, which is the default and most frequently used canvas view, displays the actual "dashboard". Commands and menu options associated with gadgets or the dashboard as a whole only operate in Analysis mode.   Because the Canvas is primarily a location onto which gadgets are placed, it has little functionality of its own that is not available from the Toolbar or Options Menu commands. The requirements for those tools are discussed in their respective sections. It may be more convenient, however, to think of accessing the commands from the location where they operate. Consequently, the Options menu, which enables the user to add gadgets to the Canvas, is accessible from the right mouse button.  Defined Variables and Data Filters can be created using their interfaces, which "slide out" onto the Canvas from labeled tabs at each side of the Canvas screen.

Functional Requirements

When in Analysis mode, the Canvas shall enable the user to:

  1. select a data source using a button that is part of a message displayed prominently on the Canvas when the Visual Dashboard module is first opened,
  2. select a gadget from the Options Menu and configure it according to the Configuration Options for Analytical Gadgets table,
  3. place a gadget selected from the Options Menu onto the Canvas after it has been configured,
  4. have the newly placed gadget execute its intended analysis and render it according to the parameters set during configuration,
  5. reposition a gadget or set of anchored gadgets by clicking and holding the left mouse button on any part within the bounds of the gadget, or the topmost or leftmost gadget in a set, and dragging to a new location (unless the Vertical Arrange button on the Status Bar is activated),
  6. open the Defined Variables interface,
  7. open the Data Filters interface,
  8. scroll vertically,
  9. scroll horizontally (if the window size has been reduced from the default (full screen)), and
  10. increase its vertical size ("add space").


Create New Variables

Overview

The user can access the tools for creating new variables by selecting the Defined Variables tab from the middle-left side of the Canvas, or by using the Variables icon button on the Toolbar. Either action expands the tab to reveal a Variable Definitions field above three buttons, labeled "New Variable", "Edit Variable", and "Delete Variable". Clicking on the New Variable button opens a menu with five options for defining a variable and one for creating a variable group.  These options are similar in some respects to variable definition and assignment in Classic Analysis (refer to Section 3.2.3.2: Data Processing). As new variables are defined, they are added to the Variable Definitions field, where individual definitions may be selected for further editing or deletion. These newly created variables can be used in any of the analysis gadgets but do not persist after termination of the program or when a new data source is selected.

Functional Requirements

The Defined Variables tool shall enable the user to define and assign values in the following ways:

  1. With Recoded Value:
    1. map a continuous numeric variable to a finite number of discrete values corresponding to ranges of numeric values;
    2. map a continuous date, date/time, or time variable to a finite number of discrete values corresponding to date, date/time, or time intervals;
    3. map a text variable containing arbitrary values to a finite number of discrete values that correspond to ranges based on lexicographic order; and
    4. map a variable with a number of discrete values to an equal or smaller number of discrete values in a variable of the same or different type, potentially using wildcards.
  2. With Simple Assignment, using one of the following assignment types:
    1. difference in years,
    2. difference in months,
    3. difference in days,
    4. difference in hours,
    5. difference in minutes,
    6. round a number,
    7. convert text data to numeric data,
    8. find the length of text data (number of characters),
    9. find the location of text data (identify the offset in a target string to the first occurrence of a query string),
    10. substring (extract a substring from a text variable given the position of the first character of the substring and its length),
    11. convert text characters to uppercase,
    12. convert text characters to lowercase,
    13. add days to a date field,
    14. determine if a drop down list field contains a value not present in its code table,
    15. count the number of checked checkboxes in a group (of variables),
    16. count the number of Yes-marked Yes/No fields in a group,
    17. determine if more than N checkboxes are checked in a group,
    18. determine if more than N Yes/No fields are marked Yes in a group,
    19. count the number of numeric fields with values between X and Y in a group,
    20. count the number of numeric fields with values outside (the range of) X and Y in a group,
    21. find the sum of all numeric fields in a group,
    22. find the mean of all numeric fields in a group,
    23. find the maximum value of all numeric fields in a group,
    24. find the minimum values of all numeric fields in a group,
    25. count the number of fields with missing values in a group,
    26. count the number of fields without missing values in a group,
    27. determine if more than N fields have missing values in a group,
    28. convert numeric data into text data,
    29. ignore the time component of a date/time field, 
    30. convert text data to date data, and
    31. convert numeric data to date data.
  3. With Conditional Assignment, assign a value to a newly defined variable of numeric, text, or Yes/No type, based on one or more of the following logically joined conditions:
    1. is equal to [tbk][1],
    2. is not equal to [tk],
    3. is between [n],
    4. is less than [n],
    5. is greater than [n],
    6. is less than or equal to [n],
    7. is greater than or equal to [n],
    8. is like [tk],
    9. is any of [t],
    10. is not any of [t],
    11. is missing [tk], and
    12. is not missing [tk].
  4. With Formatted Value, convert a Date, Date/Time, or Time variable to one of the following formats:
    1. the day,
    2. the day name,
    3. the abbreviated day name,
    4. the month,
    5. the month and four-digit year,
    6. the month name,
    7. the abbreviated month name,
    8. the standard date,
    9. the long date,
    10. the epi week (the number of the week, counting from week 1, which begins on the first Sunday in January of each calendar year),
    11. the four-digit year,
    12. the two-digit year,
    13. the hour,
    14. the RFC 1123 date (a date in the format: ddd, dd MMM yyyy HH':'mm':'ss 'GMT', where ddd and MMM are the 3-letter English abbreviations for the day of the week (e.g., "Thu", for Thursday) and month (e.g., "Apr" for April)), and

    15. the sortable date (a date in a specific format, e.g., "2016-08-02T17:38:13" for August 8th 2016 at 5:38:13 PM where lexicographic and chronological sorts coincide).

  5. With Assigned Expression, create a numeric or text variable using zero or more existing variables and a subset of the functions and operators referred to in the links.
  6. Using Create Variable Group, to create a variable alias referring to a group of one or more variables.

Notes:

  1. The available conditionals depend on the variable type to which they are applied: [t] text, [n] numeric, [b] Boolean (Yes/No), [k] foreign key.


Data Filters

Overview

The user can access the Data Filters tool by selecting the Data Filters tab from the middle-right side of the Canvas or by clicking the Filters icon on the Toolbar. Either action expands the tab to reveal a Data Filters table immediately above three buttons labeled "Remove Selected", "Clear All", and "Advanced Mode". The first two buttons refer to actions to be applied to filters previously created using the interface at the top of the window. The interface enables the user to create a filter by completing the sentence, "The value of (Field Name:) <Variables> (Operator:) <Operators> (Value) [DataEntryField]", where the text in parentheses represents labels for the pull-down menus, shown in angle brackets, and the data entry field, shown in square brackets. Once the filter is completed, clicking the "Add Filter" button adds it to the list in the "Data Filters:" table.  Before the addition of each subsequent filter, the user is prompted for an operator (OR or AND) to indicate how the individual filters will be logically combined.

The user may toggle between the default data filter interface ("Guided Mode") and the "Advanced Mode". The Advanced Mode uses the .NET DataView.RowFilter syntax, a shorthand language for defining filters similar to a basic SELECT clause in SQL. Numerous examples of the syntax are provided in the Filter window when Advanced Mode is selected; see the Data Filters page of the Epi Info™ User Guide for more information.  It is important to note that only one type of filter is in effect at a given time: those created in Guided Mode or those in Advanced Mode.  Users can refer to the filter status bar, immediately below the Toolbar, to confirm how the data are being filtered at a given moment. This information is also reflected in the table displayed when the canvas mode is changed to Data using the Toolbar's pull-down menu (Analysis/Data/Variables).

Functional Requirements

The Data Filters tool shall enable the user to: 

  1. filter (i.e., select) records based on the values of
    1. field variables from the original data source, and 
    2. new variables created using the Defined Variables tool.
  2. create filters using
    1. an interactive ("Guided") process that prompts the user to create expressions by supplying:
      1. a pull-down menu containing the names of accessible variables;
      2. a pull-down menu containing comparison operators appropriate for that variable type; and
      3. a field (or fields, if the operator requires more than one argument) appropriate for that variable type, specifically:
        1. vartype = numeric, a numeric data entry field;
        2. vartype = formatted numeric, data entry field, prepopulated with format characters at their appropriate locations and that will accept only digits in the remaining positions (e.g., a US telephone number entry field, "(___) ___-____");
        3. vartype = text, a text or string data entry field;
        4. vartype = legal value or comment legal, a drop-down list of permissible values; and
        5. vartype = Yes/No, a drop-down list consisting of "yes" and "no".
    2. a standardized expression syntax in which variables can be compared to constants or other variables and joined using logical operators (advanced mode).
  3. join filters constructed in "guided mode" with the logical operators AND and OR.
  4. see the currently active filters in the status bar (e.g., with the text, "The following canvas filters are in effect: The value of [MannerOfDeath] is equal to Suicide."). 
  5. see the effect of the filter reflected in the data table displayed on the canvas when "Data" is selected from the mode menu on the Toolbar.


Future Development

Defined Variables

In Visual Dashboard (VD), the means of assigning values to newly created variables departed from the formulaic approach of Classic Analysis (CA) in favor of a more interactive, menu-driven interface.  In places where expressions are still appropriate, however, the repertoire of functions and operators introduced in CA is no longer available. The context in which the expressions occur are similar enough to create the expectation of similar functionality.  In Epi Info™ 7.2, the functions and operators available in CA for variable manipulation are more sophisticated and flexible than their VD equivalents. For example, it would be difficult to code a variable for BMI, normally calculated as w/h2, without using w/(h*h).  Other CA functions failed as well, including log(), ln(), rnd(), and round().  Logarithms, arbitrary exponents, and random numbers should be considered essential functions for a scientific application.  The Canvas also lacked documentation describing the allowed operators (for example, the modulus operator, %, is not supported) and functions (if any exist).  Also, errors in expression syntax are not trapped in the dialog where they are entered or even inside the Defined Variables tool as a whole; the consequence of such errors are only visible when the data in the gadgets disappear and are replaced with an error message.

The following recommendations should be considered to enhance the functionality of Defined Variables in VD:

  1. Syntax errors in expressions shall be caught and reported immediately, when the New/Edit Variable dialog closes.
  2. In assignments involving expressions, Defined Variables shall permit the use of the following: 
    1. the full set of C-style binary operators: +, -, *, /, %, and ^ for numeric variables;
    2. the logical operators: &, |, and ! for Boolean variables; and
    3. parentheses to group and force priority of operations.
  3. Conditional Assignment shall permit the assignment of values and expressions to the "assign field".
  4. The group variable operations that appear in "Simple Assignment" should be maintained in VD and implemented in CA, if possible.
  5. The documentation of Defined Variables needs to be improved in the following areas:
    1. Assigned Expression: list and describe the allowed operators and functions for text and numeric expressions; and
    2. Conditional Assignment: modify to be consistent with changes recommended in item 2.

Data Filters

The biggest challenge with the VD Data Filters is the dichotomy between "guided" and "advanced" modes. The latter holds promise of potentially enabling CA-like flexibility in variable definitions; however, the inability to use both methods to create a set of filters that can be active simultaneously limits the utility of having multiple options.  It would seem possible to use the guided mode to configure a filter that is then translated into advanced mode and placed into a common filter pool. This would allow users familiar with the advanced syntax to write filters rapidly while reverting to the guided system for more complex cases, in lieu of having to consult reference material.

Tabs for Accessing Filters and Variables

When the VD is run in full-screen mode with the zoom level at exactly 100%, the access tabs for Data Filters and Defined Variables are consistently visible and work as expected. If the user changes the zoom level and/or reduces the size of the window, however, the tabs are typically lost from view and can be difficult to reacquire.  The underlying issue appears related to the fact that the tabs are not positioned relative the edges of the window, but rather to specific X and Y coordinates on the Canvas itself. With vertical and horizontal scroll bars, as well as the zoom level and an anomaly that occurs when the level passes through 100%, there are too many free parameters to use the Variable and Filter tools in anything but the default window configuration.