Requirement	Line Listing
Section	3.2.2.3
JIRA Task	EIR-59 - Getting issue details... STATUS

Reviewed For	Date
Monospace use for key seqs, math, parameters	2016-08-17
Cross references for acronyms	2016-08-17
Maximum heading depth: six	2016-08-31
Conventional spacing between sections	2016-08-31

Introduction

Line Listing is another tool for querying and displaying records in tabular format. The Printable (HTML) and MS Excel options for Line Listing produce tabular output for all records in a format suitable for printing, using a Web browser or MS Excel respectively. The interactive option in Line Listing is a more sophisticated tool that enables the grouping and filtering of records and permits control of display parameters for a clear and informative rendering of database records. The interactive option enables the user to navigate to a specific record in Enter when that record is double-clicked in the Interactive Line List.

Line Listing - Interactive Option

Objective

Use Line Listing in interactive mode to create a tabular display using a subset of fields from a project form, group the data by a categorical field while filtering and sorting on others, and open the selected record in the form in Enter`.

Preconditions

Enter is open and running on a sample project such a "EColi" (...\Epi Info 7\Projects\EColi\EColi.prj). This project contains two forms, "FoodHistory" and "FoodHistory_NoCheckCode", each containing two pages, "Page 1" and "Page 2". The "FoodHistory" form contains several categorical fields, useful for demonstrating grouping (e.g., "Was the patient ill?"), sub-grouping (e.g., "Sex"), and fields for sorting (e.g., "Last Name").

Note: Any variable type can be used for grouping or sub-grouping; however, categorical variables (e.g., Legal Value, Comment Legal, Option, Yes/No, and Checkbox fields) work best because the limited number of values they can take limits the number of resulting groups. Yes/No and Checkbox fields set Boolean variables (the former allowing for missing data); the remaining three field types can take one to many values, the upper limit determined by the practical length of the values table, or in the case on Option variables, by the space available on the form for the radio buttons and corresponding labels. The user should avoid grouping by date or a continuous numeric field, such as a subject's age or weight; this may result in nearly as many groups or sub-groups as individual records,

Postconditions

A table is rendered based on the available data, according to the parameters used. If a record is double-clicked, Enter is brought to the foreground with the selected record shown in the form.

Note: Data for Checkboxes, Yes/No fields, and other field types with missing data is shown in the table according to their representation of Yes, No, and Missing as customized on the Options→Analysis dialog.

Functional Requirements

As a program for collecting data, Epi Info™ 7 shall enable the user to:

select the variables to display in the table,
group the data using a specified variable,
sub-group the data in the previously-defined groups using (another) specified variable,
sort the data with the groups or, if defined, the sub-groups using zero or more variables, ascending or descending, on a per-variable basis,
specify the following display parameters:
1. Title, in a large font, left-justified, in the center panel directly above the Line Listing table,
2. Description, in a smaller font, in the same panel, directly below the Title,
3. Line List table dimensions: maximum width and height, in pixels; maximum variable name length in characters, and maximum rows to display;
4. the following Boolean variables (Checkboxes) controlling output options:
  1. sort variables by tab order (as defined in Form Designer),
  2. use field prompts (instead of variable names),
  3. display list labels (for Comment Legal fields and Option fields),
  4. show line (number) column,
  5. show column headings, and
  6. show missing representation (displayed value is dependent on how "missing" is defined in Options,
select (filter) for records using zero or more of the following:
1. numeric variables (including Single, Double, DateTime, Int32), subject to the following criteria:
  1. is (NOT) equal to X,
  2. is between X and Y,
  3. is less than (or equal to) X,
  4. is greater than (or equal to) X,
  5. is (NOT) missing;
2. string variables (String), subject to the following criteria:
  1. is (NOT) equal to S,
  2. is like S,
  3. is (NOT) any of (S₁, S₂, S₃, ..., S_n),
  4. is (NOT) missing;
3. variables from Yes/No fields (Byte), subject to the following criteria:
  1. is equal to Yes, No, or Missing, and
  2. is (NOT) missing;
4. variables from Checkbox fields (Boolean), subject to the following criteria:
  1. is equal to Yes, and
  2. is equal to No;
5. each variable and criterion joined to the next by the logical operators AND or OR, evaluated left to right with no parenthetical grouping of terms;
select variables for display based on predefined aliases for variable groups.

Stimulus/Response Sequence

Line Listing

1

Stimulus:

Response:

From a project currently open in Enter, user clicks on the center of the Line Listing menu on the button bar, or selects the first ("Interactive") option from the Line Listing pull-down list.

A full-screen window labeled "Line List - <Form Name>" opens, containing a table consisting of lines of records and columns of variables corresponding to fields from the original form. On the left and right of the screen are tabs to access interfaces to define variables and create data filters, respectively. In the upper right is a purple box containing a gear; clicking on it will open the main Line List interface, as described below.

2

Stimulus:

Response:

User clicks the down arrow to the right edge of the “Line Listing” button in the button bar near the top of the Enter application window and selects “Interactive”.

A full-screen window appears with the title "Line Listing - <FormName>". The window contains a table of the default dimensions (500 px high, 800 px wide) with the title "Line List". The table contains field variables in columns with all (non-deleted) records arranged in rows. By default, only variables on the form's first page are shown (see step 4). There are tabs in the middle of the extreme left and right edges of the window labeled "Defined Variables (0)" and "Data Filters (0)", respectively. There is a purple box in the top right corner containing a gear with the mouse-over comment, "Opens the gadget configuration panel."

3

Stimulus:

Response:

User clicks on the purple box containing a gear, the "gadget configuration icon."

The table is covered by a blue configuration panel on the left with four clickable regions or buttons labeled for the property panels containing the parameters or properties to be configured. The property panels are: Variables, Grouping and Sorting, Display, and Data Filters. The right side of the configuration panel shows the property panel that is selected on the left and one or more of the properties that can be configured on that panel.

4

Stimulus:

Response:

User selects "Variables" on the left panel.

To the right, below the title "Variables", is a table labeled "Variables to display:". This table contains two columns, Name and Data Type. The rows are broken into three collapsible sections, Field, followed by the name of each field and system variable; Group, followed by each group defined in Form Layout (if any); and Page, followed by the name of each page of the form. By default, the first page of the form is selected.

5

Stimulus: .

Response:

User selects the field variables to display in the table by holding down the Ctrl key and selecting the variables of interest from the list. When complete, the user clicks "OK" in the lower right of the window.

The window returns to the view of the Line Listing table, displaying only the selected variables.

6

Stimulus:

Response:

User clicks the gadget configuration icon, and then selects "Display" from the blue configuration panel.

The white region to the right (the Display Property Panel) displays the title "Display", followed by a series of text and numerical entry fields and check boxes, as listed in Configuration Parameters (below).

7

Stimulus: .

Response:

User provides a Gadget Title and Gadget Description in their respective fields, sets Max rows to display: to 500 (a number that exceeds the total number of records), Max width: to 1500 and Max height to 1000, then clicks the "OK" button.

A larger (1500 x 1000) table is rendered with the Title and Description provided, in the order that the records were entered. Deleted records are not displayed. (Deleted records are visible in Enter but all data-entry fields are grayed out; in the button bar, Undelete is visible () and Delete is grayed-out ()).

8

Stimulus:

Response:

User clicks the gadget configuration icon, then selects the "Grouping and Sorting" button from the blue configuration panel.

The "Grouping and Sorting" property panel is displayed, followed by grouping menus Group By and Sub-Group By, containing field and system variables; followed by the Sorting parameter Method, containing a menu with Ascending or Descending choices; and two Sorting list options, Available Variables and Sort Order.

9

Stimulus:

.

Response:

User selects Group By "Sex" and Sub-Group By "ILL"; leaves the sorting Method set to the default ("Ascending"); double-clicks on "LastName" in the Available Variables list (which moves the variable name to the Sort Order box as "LastName (ascending)"), then clicks "OK".

The table is rendered with the same dimensions, title, and description as in the step 6 response. This time, the rows of the table are divided into two groups, with purple bars separating the groups and labeled "F-Female" and "M-Male" (corresponding to the Sex variable, which is no longer shown as a column). Each group is further divided by light-blue bars according to the ILL variable (e.g., ”Yes” and “No”). Within each ILL sub-grouping, the rows are sorted by LastName. The record counts for each group and sub-group are shown to the right of each label. In this case, the counts are, from top to bottom: F-Female, 186; Yes, 147; No, 39; M-Male, 173; Yes, 129; No, 44.

Note: The group and sub-group counts are dependent on the total number of records displayed, as set by the Max rows to display: parameter. If the parameter is set to a number, n, less than the actual number of rows in the database, the first n records will be selected and grouped and sorted accordingly. Since the record input order is likely to be arbitrary, the user is cautioned against making any inferences from the absolute numbers or proportions in these circumstances. To obtain numbers based on the entire database, the user must set Max rows to display: to a number greater than the total number of records.

10

Stimulus:

Response:

While viewing the Line List table, the user double-clicks on a line representing a record of interest.

The line of the table is highlighted (in cyan) and the form displayed in Enter is redrawn to show the record of interest.

Configuration Parameters

Variables
1. Table containing items to select, labeled: "Variables to display:"
2. Table columns: Name, Data Type
3. Row Groups
  1. Field, contents: all field and system variables in the form
  2. Group, contents: groups defined using the Group field in Form Designer
  3. Page, contents: name of each page in form
Grouping and Sorting
1. Grouping
  1. Group By: drop-down menu containing all field variables and system variables
  2. Sub-Group By: drop-down menu containing all field variables and system variables
2. Sorting
  1. Method (defines direction of sort for key selected below): drop-down menu to select "Ascending" or "Descending"
  2. Sort Order (defines sort keys): two boxes labeled "Available Variables" (left) and "Sort Order" (right)
    1. Initially, all field and system variables are in a list in the left box.
    2. Double-clicking on a variable name moves it to the right with current Method in parentheses to the right of the name.
    3. Double-clicking on a variable name in the right box moves it back to the left, removing the variable as a sort key.
Display
1. Title and Description (displayed immediately above the table when rendered)
  1. Gadget Title [Text field]
  2. Gadget Description [Text field]
2. Dimensions (govern the size of the rendered table)
  1. Max width [Numerical field]
  2. Max height [Numerical field]
  3. Max variable name length [Numerical field]
  4. Max rows to display [Numerical field]
3. Output Options
  1. Sort variables by tab order [Check box]
  2. Use field prompts [Check box] (replace field variable names in column headings with field prompts [the field labels as they appear on the form])
  3. Display list Labels [Check box] (for comment legal variables, display long text in addition to one-letter code; for option fields, display option button text)
  4. Show line column [Check box, checked by default]
  5. Show column headings [Check box, checked by default]
  6. Show missing representation [Check box, checked by default]
Data Filters
1. Parameters
  1. The value of Field Name: drop-down menu of variables
  2. Operator: drop-down menu of comparison operators
  3. Value: data entry field [format dependent on variable and operator]

Functional Requirements (Interactive and Other Modes)

The system shall enable the user to generate a table of form data (a "Line Listing") using the following modes or formats:

"Interactive", which supports the following operations:
1. choosing (or removing) specific field variables from the display.
2. grouping and sub-grouping (creating collapsible, nested headings and subheadings with the number of records in each category) based on the values of specified field variables.
3. sorting records by one or more field values (variables) into ascending or descending order on a per-variable basis.
4. setting or selecting the following display parameters:
  1. title of the table, displayed in bold blue letters above the description.
  2. table description, displayed in black between title and table header.
  3. dimensions:
    1. max width,
    2. max height,
    3. max variable name length, and
    4. max rows to display.
  4. output options:
    1. sort variables by Tab Order,
    2. use field prompts,
    3. display list labels,
    4. show line (number) column,
    5. show column headings, or
    6. show missing representation (display "missing" in place of the unavailable data).
"Printable (HTML)"
1. There are no arguments or parameters associated with this format.
2. The table is encoded in HTML.
3. The HTML code is rendered in the default browser.
"MS Excel"
1. There are no arguments or parameters associated with this format.
2. The table is encoded in HTML (the <table> portion is identical to 2a; the associated CSS code differs).
3. The HTML code is opened in MS Excel.

Data Filters

Functional Requirements

Line List shall enable the user to:

Create Data Filters by:
1. identifying a field or system variable,
2. selecting one of the following operators:
  1. equal to [Boolean, text, numerical, datetime],
  2. is like [text],
  3. is less than (or equal to) [numerical, datetime],
  4. is greater than (or equal to) [numerical, datetime],
  5. is between [numerical, datetime],
3. supplying the appropriate parameter or parameters (between), and
4. join multiple filters using logical ANDs or ORs,
Edit (existing) Data Filters, and
Remove (existing) Data Filters.

Future Development

Functional Requirements - Defined Variables

Line List shall enable users to:

Define New Variable with user-specified data type using:
1. Recoded Value, which allows:
  1. ranges of values from a numeric or date/time source variable to be mapped to discrete text, numeric or Yes/No values,
  2. individual strings or wild-card expressions from a source variable to be mapped to discrete text, numeric or Yes/No values,
  3. values from a categorical source variable to be mapped to discrete text, numeric or Yes/No values,
2. Simple Assignment, which allows the following assignment types:
  1. difference in minutes, hours, days, months, or years;
  2. round a number,
  3. convert text data to numeric data,
  4. find the length of a string (text data),
  5. find the location of text data (using GIS),
  6. extract a substring of length n from text field, starting at position m,
  7. convert text to uppercase and lowercase,
  8. add days to a date field,
  9. determine if a drop-down list field contains a value not present in its code table,
  10. count the number of checked checkboxes in a group,
  11. count the number of Yes-marked Yes/No fields in a group,
  12. determine if more than n checkboxes are checked in a group,
  13. determine if more than n Yes/No fields are marked Yes in a group,
  14. count the number of numeric fields with values (not) between x and y in a group,
  15. for all numeric fields in a group, calculate the:
    1. sum,
    2. mean,
    3. maximum, and
    4. minimum,
  16. count the number of fields with/without missing values in a group,
  17. determine if more than n fields have missing values in a group,
  18. convert numeric data to text data
  19. ignore the time component of a datetime field,
  20. convert text data to date data,
  21. convert numeric data to date data,
3. Conditional Assignment, which assigns a value based on one or more AND-or-OR-joined conditional expressions including:
  1. is (not) equal to [text, numerical, datetime],
  2. is like [text],
  3. is (not) any of [text],
  4. is (not) missing [text, numerical, datetime],
  5. is less than (or equal to) [numerical, datetime],
  6. is greater than (or equal to) [numerical, datetime],
  7. is between [numerical, datetime],
4. Formatted Value, which formats a datetime field into:
  1. the day,
  2. the (abbreviated) day name,
  3. the month,
  4. the (abbreviated) month name,
  5. the month and four-digit year,
  6. the standard date,
  7. the long date,
  8. the four-digit year,
  9. the two-digit year,
  10. the hour,
  11. the RFC 1123 (section 5.2.14) date, and
  12. the sortable date,
5. AssignedExpression, which uses variable names, functions and operators using Check Code syntax,
Create Variable Group by creating a group field name and associating one or more field variable to it,
Edit (existing) Variable definitions,
Delete (existing) Variable definitions.

Functional Requirements - Short Term

The Line Listing gadget, as accessed from Enter, can only display Undeleted records. For consistency with the functionality in Classic Analysis, Enter's Line Listing shall support three modes for record display:
1. Undeleted (currently available mode),
2. Deleted, and
3. Both (Undeleted and Deleted, i.e., all records in the database).
The current implementation supports the creation of defined variables that only persist for the life of the Line List process. Enter's implementation of Line Listing shall have a means of creating persistent defined variables.

Functional Requirements - Long Term

Currently, the "sort-on-demand" feature accessed by double-clicking on column headings in the Line List table is incompatible with the grouping and sub-grouping feature. Sort-on-demand shall sort by the indicated column within each existing group or sub-group, maintaining the groupings unchanged.