Defining Named Relations

This section includes:

• About Named Relations
  
• Types of Named Relations
  
• Defining Named Relations
  
• Defining Dictionary NRLs
  
• Writing Named Relation Activation Rules
  

About Named Relations

Standard-type named relations create a structure for weak dictionary folders by describing the nature of relations between terms. You can define named relations as being one-directional or bi-directional, as shown in the figure below.

Figure 7-1 Figure 7-1 One-directional and Bi-directional Relationships

Bi-directional relationships like the one above between "United States" and "California" have two components, an Indicator relationship and a Reciprocal Indicator relationship. Indicator relationships describe the link from the source term to the reference term, and Reciprocal Indicators describe the reverse relation. If "United States" is the source term for the above relation, "Broader Term Than" is the Indicator for this relationship and "Narrower Term Than" is the Reciprocal Indicator.

One-directional named relations have Indicator relationships only. Thus, in the example one-directional relation above, no relationship is defined from "state" to "California."

Named relations also define the cardinality of the relation between terms. The cardinality of a relationship determines the maximum number of reference terms (one or many) to which a term may be linked. If you specify Many Cardinality for the Indicator relationship but Single Cardinality for the Reciprocal Indicator, then source terms can be linked to many reference terms, and each reference term must link to only one source term.

Because named relations create a dynamic dictionary structure, you cannot enforce that named relations be mandatory. You can, however, enforce mandatory relations between levels in a strong dictionary; see Mandatory Relations.

TMS does not allow circular named relations of the same type among terms. That is, if you define an Indicator relationship of a particular type (such as Related Term) between Term A and Term B, and another Indicator relationship of the same type between Term B and Term C, you cannot define an Indicator relationship of the same type between Term C and Term A. Activation of the final relationship in the circle fails. (The reason for this restriction is that the ANSI/NISO Z39.19-1993 standards for thesauri specify that you must be able to represent a thesaurus structure using a flat display, which is impossible with circular relations.)

You can introduce a named relationship into your installation using the Define Named Relationships window, or by loading the relationship directly into the repository with a load script (see About Load Scripts). TMS stores named relations in the tms_def_named_rels table, and enables you to use any named relation to link terms in any dictionaries throughout the TMS installation.

See Defining Named Relations and Creating Named Relations Between Terms for more information, including information on other types of named relations.

Types of Named Relations

You can use named relations to create browsable relations between dictionary terms.

There are three types of named relations:

• Standard. Use standard named relations to create relations among terms in weak dictionary folders or to supplement existing relations among terms in strong dictionaries.

  After you define a standard named relation, you can create standard named relations between terms in the Repository Authoring window under the Repository Maintenance menu.

• Translation. Use named relations of type Translation to define a relationship between a term in one dictionary and a term with the same meaning in another dictionary in a different language. TMS allows named relations of type Translation only between terms in different dictionaries, each of which must have a different language defined.

  After you define a Translation named relation, you can create Translation named relations between terms in the Repository Authoring window under the Repository Maintenance menu.

• Release Label. Use named relations of type Release Label to create relations between terms in the same or different dictionaries at different points in time.

  This is especially useful for maintaining an audit trail of complex changes to a term from one dictionary version to another; for example, where two terms are merged, or one term is split into two or more terms, or one term is substituted for another.

  After you define a Release Label named relation, you can create Release Label named relations between terms in the Release Label Authoring window under the Repository Maintenance menu; see Using the Release Label Authoring Window.

Release Label Named Relation Example 1

The MedDRA 7 high level terms "Liver and spleen infections" and "Gallbladder infections" were merged in MedDRA 8 into a single term, "Hepatobiliary and spleen infections."

If you are currently using MedDRA 7 in TMS, do the following:

1. After upgrading to TMS 4.6, define a label prefix for MedDRA 7: 7.0.

2. Create a virtual dictionary of MedDRA 7. TMS creates a Release Label for the virtual dictionary.

3. Define a named relation called "is merged into;" see Defining Named Relations.

4. Update the label prefix to 8.0.

5. Load data for MedDRA 8 into the predictionary tables.

6. Define two named relations in the Release Label Authoring window, one from "Liver and spleen infections" to "Hepatobiliary and spleen infections" and one from "Gallbladder infections" to "Hepatobiliary and spleen infections." In both cases, given the definition "is merged into," "Hepatobiliary and spleen infections" must appear in the Reference section of the screen. See Creating Named Relations Between Terms. Use the NEXT setting for "Hepatobiliary and spleen infections," which is in the predictionary tables and does not yet have a Release Label.

7. Activate the data (MedDRA 8).

Release Label Named Relation Example 2

If you have already loaded and activated MedDRA 8, do the following to trace the relationship between MedDRA 7 high level terms "Liver and spleen infections" and "Gallbladder infections" the single MedDRA 8 high level term, "Hepatobiliary and spleen infections":

1. Create label prefixes for MedDRA 7 and MedDRA 8.
2. Create virtual dictionaries for MedDRA 7 and MedDRA 8. TMS creates a Release Label for each.
3. Define the "is merged into" named relation as above.
4. Define named relations between the two terms in MedDRA 7 and the term they are merged into in MedDRA 8.

Defining Named Relations

To create a new named relation:

1. From the Definition menu, select Define Named Relations. The Define Named Relations window opens, with the Named Relation tab displayed.

   Note:

   By clicking the Multi Display Named Relations tab, you can view all of the named relations defined in this TMS installation. Examine the existing named relations before creating a new named relation to avoid creating similar but extraneous relationships.

2. Define the Indicator relationship:

   1. In the Name field, enter the relationship name that will appear for relations from a term to its referenced term.

   2. Select the Many Cardinality box to allow multiple source terms to relate to one (or more) reference terms using the Indicator relationship.

3. Define the Reciprocal Indicator:

   1. In the Name field, enter the relationship name that will appear for relations from the reference term back to the source term. If the relationship does not have a reciprocal, leave the Name field blank.

   2. Select the Many Cardinality box to allow multiple reference terms to relate to one (or more) source terms using the Reciprocal Indicator relationship.

4. Define the relationship details. All the fields in the Details block are optional except for the Type field.

   1. In the Relationship Code field, you can enter an optional code about this named relation. For example, when loading named relations into TMS via the API, you could populate the Relationship Code with the vendor-supplied dictionary from which you loaded the relationship, or the relationship's ID in that dictionary.

   2. Select a Type.

      Standard. Use for normal named relations between terms. TMS does not enforce any special behavior.

      Translation. TMS validates that the two terms in the relation are from dictionaries that have different languages specified. Because translation relationships must be between dictionaries of different languages, you can only instantiate such relations as cross-dictionary relations. See Creating Cross-Dictionary Relations Between Terms for instructions on using these relationships in the Repository Authoring window.

      Release Label. Release Label named relations create links between terms in the same or different dictionaries at different points in time; see Types of Named Relations.

   3. In the Short Name field, enter a unique value for the short name of this relationship. TMS allows names containing up to ten bytes of alphanumeric text. If you leave this field blank and save the record, TMS supplies a default, unique value.

   4. In the Activation Rule field, you can specify a function that you want to use as the Activation Rule for this relationship. Writing Named Relation Activation Rules.

   5. In the Category field, you can enter a category to define further this named relation.

   6. In the Description field, you can provide more information about this named relation. Information entered here could help other TMS users.

5. Save. TMS records the named relation in the repository, and updates the audit fields in the bottom of the window.

You can modify many attributes of named relations in the same manner. Because TMS only uses the internal ID of the relationship to identify which named relation is associated with a particular relation, you can change any information about an existing named relation except its ID, cardinality, and type.

Defining Dictionary NRLs

For each named relation you define, you must specify the dictionaries and dictionary combinations where it should be available for creating named relations between terms.

To specify the dictionaries where a named relation is available for use, do the following:

1. In the Define Named Relations window, with the named relation for which you want to specify dictionaries selected, click Dictionary NRLs. The Define Dictionary Named Relationships window opens.
2. Click in the first empty row. The fields become enterable.
3. In the From Dictionary column, from the list, select a dictionary in which you want the named relation to be available.
4. In the To Dictionary column, from the list, select a dictionary:

   • To make the named relation available to define relations between terms in a single dictionary, choose the same dictionary you specified in the From Dictionary column.

   • To make the named relation available to define relations between terms in the dictionary you specified in the From Dictionary column and a second dictionary, choose the name of the second dictionary.

     Note:

     In the To Dictionary list of values, TMS displays:

     • The From Dictionary; you can always define relations between terms in the same dictionary.

     • Dictionaries that have a filter dictionary link with the From Dictionary; one is a filter of the other.

     • Dictionaries with a cross-dictionary link defined to the From Dictionary. To define a dictionary link, go to the Define Dictionaries window, select a dictionary, and click the Dictionary Link tab. See Defining Links Between Dictionaries.

5. Leave Status set to Active.

   You can set the status to Retired in the future to prevent this named relation definition's being used to create additional relations in this dictionary or dictionary combination. This is the only modification possible.

   You can set the status back to Active only if the To and From Dictionaries have one of the relationships described in the above Note.

6. Save.

Writing Named Relation Activation Rules

Named relation Activation Rules can perform further validation of the terms and their relationship(s) before Activation. For example, if you create a named relation "Abbreviation for," you could write a function to verify that the reference term you plan to use as the abbreviation is, in fact, shorter in length than the original term.

Named relation Activation Rules must be part of database packages, and the proper format for definition is package_name.function_name.

The function must use the parameters described in the following table.

Table 7-1 Parameters Required for Named Relation Activation Rules

Parameter (In/Out)	Datatype (Size)	Description
pRelId (in)	NUMBER(10)	ID number of the relation.
pGroupId (in)	NUMBER(10)	ID number of the Activation Group.
pNRLId (in)	NUMBER(10)	ID number of the named relation you are using for this relation.
pConId (in)	NUMBER(10)	ID number of the first term in the relation.
pConRefId (in)	NUMBER(10)	ID number of the reference term in the relation.
pDomId (in)	NUMBER(10)	ID number of the domain in which you are creating this relation.
pCreatedBy (in)	VARCHAR2(30)	The user name of the TMS user who created this relation.
pLevelId (in)	NUMBER(10)	ID number of the level in which the first term resides.
pLevelRefId (in)	NUMBER(10)	ID number of the level in which the reference term resides.
pDML (in)	VARCHAR2(15)	The requested Action you want to perform on the TMS preproduction repository. Values are 'I' (Insert), 'U' (Update), and 'D' (Delete).
pDefDictId (in)	NUMBER(10)	ID number of the dictionary in which the first term resides.
pDefDictRefId (in)	NUMBER(10)	ID number of the dictionary in which the reference term resides.
pRelType (in)	VARCHAR2(15)	The type of relation you are loading: DT – Dictionary Term DPL – Domain Primary Link PPL – Primary Path Link VTA – Verbatim Term Assignment
pRelSubtype (in)	VARCHAR2(15)	If the RelType is VTA, the subtype can either be AC (Accepted) or MS (Misspelled). For any other relation type, possible subtype values are E (External), C (Company), and D (Domain).
pActivationId (in)	NUMBER(10)	Internal ID used to track the Activation process.
pTransId (in)	NUMBER(10)	Not used in this release.
pStatus (in)	VARCHAR2(15)	An optional description of the status of this term.
pCommentText (in)	VARCHAR2(200)	Comment about this Activation Rule.
pErrorMsg (in/out)	VARCHAR2(200)	Error message associated with this record. This is the only part of a production record that you can change with this function.