Epi Info™ User Guide

Analysis Commands: RELATE

Description
This command links one or more tables to the current dataset during analysis, using a common identifier to find matching records. The identifier may span several fields, in which case values in each of the fields must match.

Syntax
RELATE <table specification> [<key(s)>] {ALL}

• The <table specification> represents the type and name of a data table to be read as the Related file.
• The <key(s)> represent one or more expressions that designate keys on which the match or relate will be performed. When multiple expressions are used, they are connected with AND. These following are in the form:

<ExpressionCurrentTable> :: <ExpressionRelateTable>

• The ALL represents records in the table(s) already READ or related for which there is no corresponding record in the RELATE table will be included in the data with null values for variables in the RELATE table. If absent, only records with corresponding records in the RELATE table will be included in the data.

Program Specific Features

Analysis
If the relationship was created in Form Designer, Classic Analysis can relate the two tables without need of a key expression.

Form Designer

• Grid tables and relate buttons help create parent-child relationships.
• Grid tables have a prefix of recgrid table.

Comments
To use RELATE, at least one table must have been made active with the READ command. The table to be linked must have a key field that identifies related records in the other table. In Epi Info 7, the keys in the main and related tables or files might not have to have the same name.

The expressions in the key are the names of variables in the tables that will be used to determine which records match each other. More than one key pair (“multiple keys”) can be designated, separated by AND.

After issuing the RELATE command, the variables in the related table may be used as if they were part of the main table. Where variable names are duplicated in the related tables, the variable names will be suffixed with a sequence number. In referring to a variable in a related table, you may (optionally) use the form HOUSE.AGE to represent the variable AGE in the form HOUSE. This will distinguish it from another variable AGE that might be in the main table.

Frequencies, cross-tabulations, and other operations involving data in both the main and related tables can be performed. To preserve the linked structure, the WRITE command may be used to create a new table. More than one table may be related to the main table or related table by using successive RELATE commands.

Example

To try the code example below, copy and paste the code example into the Classic Analysis Program Editor and click Run Commands.
The records from the RHepatitis data tables are related to the Surveillance data table.

READ  {.\Projects\Sample\Sample.prj}:Surveillance 
RELATE RHepatitis GlobalRecordId :: [FKEY]