Requirement	Linked Records
Section	3.2.2.4
JIRA Task	EIR-47 - Getting issue details... STATUS

Reviewed For	Date
Conventional spacing between sections	2016-08-31

Introduction

The Linked Records component of Enter is used to record exposure information for contact tracing using Social Network Analysis (SNA). SNA is an investigative tool for examining social structures using network and graph theory. Network structures are characterized in terms of nodes and edges. In the context of Epi Info™ 7, nodes correspond to subjects (typically people, although identifiable animal vectors such as pets could be relevant [e.g., turtles in the transmission of Salmonella]) as well as places [e.g. an Operating Room in a healthcare acquired infections study] or objects [e.g. an improperly stored sample of a known carcinogen], and edges represent interactions between them. The value of SNA lies in its ability to trace exposure relationships through many individuals, although only individual pairwise interactions are recorded.

Understanding Linked Records

Epi Info™ 7 supports directed edges, meaning that subject A exposed to subject B is different from B exposed to A. In the first instance, using a case of an individual’s exposure to a contagious patient as an example, A exposed to B, B is the patient infected with the contagion at the time of the interaction and A is not known to be infected prior to exposure. When the user creates an A exposed to B relationship, the system automatically creates the reciprocal relationship, B exposed from A, This relationship is visible in the Linked Records panel in Enter when viewing the record for individual B.

The Figure to the right illustrates the relationships between subjects connected by different exposure relationships. This is the view from the perspective of subject A (in red), which is the current record being viewed in Enter.

Subject A exposed to (←) Subject B

Subject B exposed from (→) Subject A

Subject A exposed from (→) Subject D

Subject D exposed to (←) Subject A

Note that the arrow points from the point of origin to the entity that is the potential recipient. One can think of the arrow as representing the direction of potential transmission of an infectious agent or contaminant.

Again, the value of this analysis is in its ability to trace exposure relationships through many entities, although only the current entities’ pairwise interactions are shown. In this example, the infection originated with Subject C but spread to eight others, either directly (to Subject B) or through intermediates, B and A for Subject D.

Creating Linked Records

Objective

Given a group of subjects from a real or simulated disease outbreak, collect clinical and contact information from symptomatic individuals and other asymptomatic subjects who may (or may not) have been exposed to infected individuals. Use the interface on the Linked Records panel to enter exposure information.

Preconditions

Enter is running and open on a form designed for collecting clinical and demographic information about the disease of interest. [In this requirement, the nature of the form is largely irrelevant because the Linked Records function of Enter operates independently of any user-defined fields or check code in the form. It is sufficient that uniquely identifiable records are created during data entry to enable them to be linked.]

Postconditions

A record for each individual in the study has been created that includes a linkage ("Exposed From") to each infected/symptomatic subject with whom the individual has had contact.

Functional Requirements

The system shall enable the user to create links between records using the Linked Records panel in Enter.
1. The system shall enable the user to create "Exposed To" links to the current record by clicking on the "Exposed To" tab, then clicking "Add Exposure..."
2. The system shall enable the user to create "Exposed From" links to the current record by clicking on the "Exposed From" tab, then "Add Exposure..."
The system shall enable the user to query for the target of the linkage relationship using Find.
1. After the target of an "Exposed To" linkage is selected, the system shall:
  1. add it to the list of records under the "Exposed To" tab of the original record, and
  2. create the reciprocal relationship such that, when the target record is displayed in the form, the original record is listed under the "Exposed From" tab.
2. After the target of an "Exposed From" linkage is selected, the system shall:
  1. add it to the list of records under the "Exposed From" tab of the original record, and
  2. create the reciprocal relationship such that, when the target record is displayed in the form, the original record is listed under the "Exposed To" tab.
When the user clicks "View SNA Graph," the system shall render:
1. the current record as a red circle,
2. the linked record(s) as gray circle(s),
3. an "Exposed To" relationship between linked and current records shall be displayed as a gray arrow pointing from the current record to the linked record, and
4. an "Exposed From" relationship between linked and current records shall be displayed as a gray arrow pointing to the current record from the linked record.

Viewing SNA Graph

Objective

Given a form that has been fully populated with "exposure" information (reflecting linked records), use the SNA graph function of Epi Info™ 7 to identify a likely candidate for patient zero, the original source of infection.

Preconditions

Enter is running and open on a form designed for collecting clinical and demographic information about the disease of interest. [In this requirement, the nature of the form is largely irrelevant because the Linked Records function of Enter operates independently of any user-defined fields or check code in the form. It is sufficient that uniquely identifiable records are created during data entry to enable them to be linked.]

Postconditions

If all individuals with contacts are part of the same SNA graph, following the arrows in the reverse direction to a unique individual will identify patient zero. If the subjects are split amongst multiple graphs and/or a unique terminal node cannot be identified, the identity of patient zero remains ambiguous.

Functional Requirements

The system shall enable the user to view an SNA graph from the point of view of any subject/record that is a member of a graph (i.e., that has at least one relationship, "Exposed To" or "Exposed From").
The system shall render the graph with the following properties:
1. the view shall be centered on the node representing the current record,
2. all nodes representing records shall be drawn as shapes large enough to be clicked on,
3. the node representing the current record shall be distinctly shaped or colored, and
4. Nodes with a direct relationship to the current node (one degree of separation) shall be:
  1. drawn an approximately equal distance from the current node,
  2. drawn in a predictably smaller size or different color from the current node, and
  3. the current node shall be connected to each of its linked nodes with an arrow reflecting the direction implied by their relationship ("Exposed To/From").
5. Nodes with additional degrees of separation from the current node shall apply the above rules recursively until all nodes are terminal (having no "Exposed To" relationships).

Future Development

Functional Requirements - Short Term

The system shall enable the user to create linked records in Find while using "Add Exposure..." in fewer operations by:
1. enabling the selection of multiple records from an individual query to create multiple linkages in a single step,
2. creating an option to save the selected fields and search strings between successive invocations as they appear when the option is selected.
3. adding options to clear saved fields and individual or all search strings from an individual invocation or all future queries.
The system shall enable the user to create a list of variables to be displayed for:
1. a record corresponding to a node on an SNA graph, and
2. a pair of records corresponding to a pair of nodes connected by an edge (corresponding to an exposure interaction/linkage) in an SNA graph.
The system shall enable the user to interrogate an SNA graph by using the mouse to:
1. display a list of predefined variables from a record by clicking on its corresponding node, and
2. display a list of predefined variables from a pair of records by clicking on the edge connecting their corresponding nodes.

Functional Requirements - Long Term

The system shall enable the user to view a list of all discrete networks associated with the current form.
1. Each row of the list shall consist of:
  1. a graphical rendering of each network scaled such that all can be displayed in a single (scrolling) window,
  2. the number of nodes in the graph, as an integer and as a percentage of all records in the database,
  3. the identity of the root node (the node with no "Exposed From" connections) and a link to the corresponding record,
  4. the depth of the network corresponding to the maximum degrees of separation between the root node and its most distal linked node, and
  5. the average number of "Exposed To" relationships per record.
2. The list shall have a summary row containing the following:
  1. the total number of nodes in all graphs, as an integer and as a percentage of all records in the database, and
  2. the global average number of "Exposed To" relationships per record.
The system shall enable the user to determine the identifier of the network to which a given record belongs, if any, from the main Enter interface.
The system shall notify the user if, when editing an "Exposure," networks merge or split as a result.
1. The system shall identify the corresponding:
  1. record,
  2. "Exposure" type, and
  3. list the network identifier(s):
    1. in the before state and
    2. in the after state.
The system shall support the mapping of variables to drawing parameters of the SNA graph such as:
1. inter-node line/arrow length, width and color, and labeling,
2. node shape, size and color, and labeling, and
3. grouping of nodes and arrows around a specific node.
The system shall support printing the SNA graph or exporting the SNA graph to a format (e.g. Word document or image file) that can be printed and used in other documents or media.
The system shall support one or more modes or options for viewing the SNA graph to emphasize properties such as:
1. distance from current node (as described above),
2. distance from patient zero,
3. elapsed time between subject's first exposure to an infected individual and the onset of symptoms in another individual exposure to the original subject (incubation period), and
4. type of exposure event (exchange of bodily fluid (by type), casual physical contact, physical proximity, handling items touched by infected individual, etc.)

Browser not supported