Terry's TMG Tips

Changes in Role Variables – Advanced Issues

This page created 10 Jul 2014

Version note: Applies to TMG 9.02 and later

This article describes issues that may arise for advanced users resulting from changes in the behavior of certain Role Variables introduced with TMG version 9.02. More general issues related to this change are describe in my Changes in Role Variables article.

The five cases described below are not addressed by the automatic conversion process, which is designed to resolve the issues that may be encountered by the vast majority of TMG users. These issues, if they exist in a user's data, must be addressed by the user. Suggestions for identifying cases are included for each issue.

Topics Included in this Article
Case 1
[Rx:rolename] Variables in Tag Types Sentences assigned to Principals
Case 2
[Rx:rolename] Variables in Local Sentences of Principals
Case 3
[Rx:rolename] Variables in Tag Memos for Principals
Case 4
[R:rolename] Variables in Tag Memos for Principals or Witnesses
Case 5
[R:rolename] Variables in Witness Memos

Case 1: [Rx:rolename] Variables in Tag Types Sentences Assigned to Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in Tag Type Sentences to refer to the subject of the Sentence, and that Role is assigned to Principals. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

If you have Tag Types with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF] in those Sentences. If you cannot recall such cases but suspect your Project may contain some you will have to review all the Tag Types in your Project for Roles which you might assign to both Principals and Witnesses. If any are found, review their Sentences to see if any use the [RF:rolename], [RG:rolename], [RL:rolename], etc. Variables to refer to the subject.

If the Roles found might sometimes have been assigned to a Principal and sometimes a Witness, there now is no way for a single Sentence to retain the old behavior of producing differing output for Principals and Witnesses, if that in fact was the intent. If you want the output to be the same in both cases, you will need to choose whether to retain the Role Variable to always output all names, or use the new Subject Variable to always output only the subject's name. If you want the option of outputting one name in some cases and all names in others, you will have to construct two separate Roles – one using the corresponding Subject Variables to output only one name, and a separate one using the Role Variables to output all names assigned this role. You will then have to assign the appropriate Role to each person to obtain the output desired.

You could do this by reviewing all the Tag Types in the Master Source List. But the review can be made considerably simpler by use of John Cardinal's TMG Utility to search for potential cases. (The TMG Utility is free, but is "donor ware," meaning John asks that you make a donation to his favorite charity if you find it useful.)

For this test, use the Export Data feature, as shown below, and then use your browser to examine the HTML file that is created:

As shown above, make the following settings:

Click the "Export Data" button, and after specifying a location for the file that is to be generated, you see this dialog:

If you use only one Language for your Sentences, choosing that Language in the "Show Language" drop-down will eliminate Sentences in Languages you don't use. Otherwise, choose All or make separate runs for each Language.

When you click the OK button a file listing all the Sentences in your Project will be generated and will open in your browser. It will show each Tag Type and the Sentences for each Role. Here is an example for one of my Tag Types:

Here I have used the "Find" function in my browser (may be "Find in this Page" depending on which browser you use) to search for "[RF:" to find Sentences using the [RF:rolename] Variables. If you use other variations you would also search for them.

When you locate a Sentence that uses these Variables, first look at the Role to see whether it is one you might use for Principals. In this case I would only use the "Principal," "one Daughter," and "one Son" Roles for Principals, so I examine only those Roles to see if the [RF:rolename] Variable refers to the subject of the Role. In each of those three Roles above the [P] Variable is used to refer to the subject, so there is no issue with this Tag Type. I would continue to examine other Tag Types.

If you know you have used Variables like [RF:rolename], [RG:rolename], etc. to refer to the subject person of a Role in a particular Tag Type, and are unsure whether you may have assigned that Role to Principals, use the List of Events report with a Filter like the following (ver. 9.02 and later only) to find any such cases:

( Field Subfield Operator Value ) Connect
  Tag Type... Label = Equals CENSUS   AND
( Principal1... Role = Equals SPOUSE   OR
  Principal2... Role = Equals SPOUSE ) END

To check for multiple Rolenames at a time, the filter could use the vertical bar (OR) separator permitted with the Equals operator (e.g. SPOUSE|CHILD), or define multiple filter conditions using the OR connector.

Note that this example filter only identifies Tags where a Principal has been assigned the role of "Spouse".  It does not identify whether a "Spouse" Role Variable is used in the Sentence to refer to the Principal, nor that if so it is of the [Rx:rolename] type as opposed to the [R:rolename] type. Both would have to be determined by examining the Sentences in the Tags identified by the report.

This filtered report can be used to identify whether a specific Role is assigned to a Principal where that Role is not intended for such assignments.  It can also be used to identify whether a specific Role is assigned to a Principal when you know that Role uses an [Rx:rolename] Variable to refer to the subject of the Role.

Case 2: [Rx:rolename] Variables in Local Sentences of Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in Local Sentences for Principals, and the Variable refers to that Principal. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

If you have Tags with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF]. If you cannot recall such cases but suspect your Project may contain some, two methods are available which can aid in the search.

The first is to use the List of Events report to create a list of Events with Sentences which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

Field Subfield Operator Value Connect
Principal1... Sentence (local) Contains RF: OR
Principal1... Sentence (local) Contains RG: OR
Principal2... Sentence (local) Contains RF: OR
Principal2... Sentence (local) Contains RG: END

If variations other than first name and given name may have been used to refer to the subject, lines should be added to the filter to search for them too. In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Principal Sentence as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

Sort Order Column Type Heading Width
2 Prin1 ID P1_ID 6
  Prin2 ID P2_ID 6
1 Tag Type Label Label 10
  Date Date 23
  Prin1 Role * P1_Role 10
  Prin1 Sentence P1 Sentence 125
  Prin2 Role * P2_Role 10
  Prin2 Sentence P2 Sentence 125
* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Local Sentences contain Variables of the type at issue. You will have to review the Sentences to determine whether that Variable refers to the Role assigned the Principals. For example, you may see this Sentence:

[PF], her daughter [RF:with Father], and [M1] Ann's half-brother [R:Other] [M2].

Examination of the Sentence in this case shows that the Principal is referred to with the Variable [PF] and that the [RF:rolename] variable refers to someone else, so this Sentence is not an issue.

Another approach, which also identifies the Role assigned the Principal, is to use John Cardinal's TMG Utility to search for potential cases. (The TMG Utility is free, but is "donor ware," meaning John asks that you make a donation to his favorite charity if you find it useful.) Newly released version 7.3.3.2 or later is required for this test, so if you are using an earlier version you must first update to the latest version.

For this test, use the Search and Replace feature, as shown below, and then examine the resulting log:

As shown above, make the following settings:

\[R.*:

to search for the characters " [R " followed by one or more characters, followed by " : "

Click the "Find All" button, and you see a log like the following:

Options:
Field: Event Sentence
Find what: \[R.*:
Replace with: <ignored; Find All only>
Contents must match Find What exactly: Unchecked
Use Pattern Matching: Checked
Match case: Unchecked
Find Whole Word Only: <na>

------------
ID, Sentence
#2, '[L=ENGLISH][RF:00003] was born <[D]> <[L]> <and was the godchild
of [R:00004]> <[M]>[:CR:][:CR:]'
Event: Birth 16 May 1781, Subject(P1) Name=George Bezanson (#2),
Subject Role=00003

#3, '[L=ENGLISH][P1] drowned in [D], leaving a widow, [RG:00004], and
children, [RG:00005].'
Event: Death Feb 1804, Subject(W) Name=Mary Millet (#3), Subject
Role=00004, P1=James Jackson Vaughan (#11)

#9, '[L=ENGLISH][P] <was|and [PO] were> [M1] <[R:00002]> <[L]>'
Event: Occupation circa 1840, Subject(P1) Name=Charles Anthony
Bezanson (#9), Subject Role=00001

Each event with local Sentences is listed, showing for each case found the local Sentence, the Tag Type and date of the event, the name and Role of the subject of the Sentence, and if the subject is not a Principal, the name of the Principals. In the log, the Roles are identified by their internal number rather than their plain-language labels.

Events with potential issues are found by identifying Sentences in which the Subject is a Principal, and a [Rx:rolenumber] is found referring to the same Role number assigned to that Principal, as marked with red above. The Sentence actually requires correction only if there may be another person assigned that Role in the Tag, which is unlikely in the example shown since only one person is likely to be assigned the same Role as the Principal in a Birth Tag.

An alternate method, if you suspect you have used Variables like [RF:rolename], [RG:rolename], etc. in local Sentences for Principals to refer to that Principal in a particular Tag Type, the List of Events report with a Filter like the following (ver. 9.02 and later only) can help identify any such cases:

( Field Subfield Operator Value ) Connect
  Tag Type... Label = Equals CENSUS   AND
( Principal1... Role = Equals SPOUSE   AND
  Principal1... Sentence (local) Contains :SPOUSE ) OR
( Principal2... Role = Equals SPOUSE   AND
  Principal2... Sentence (local) Contains :SPOUSE ) END

Note that this filter identifies Tags in which the Sentence for a Principal uses a Role Variable referring to that Principal's Role, but does not determine that the Role Variable is of the [Rx:rolename] type as opposed to the [R:rolename] type. So each case found would have to be examined to see if it uses an [Rx:rolename] Variable to refer to the Principal. Setting the Output Columns to something like the following may be helpful:

Sort Order Column Type Heading Width
1 Prin1 ID P1_ID 6
  Prin2 ID P2_ID 6
  Tag Type Label Label 10
2 Date Date 23
  Prin1 Role * P1_Role 10
  Prin1 Sentence P1 Sentence 125
  Prin2 Role * P2_Role 10
  Prin2 Sentence P2 Sentence 125

* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

Case 3: [Rx:rolename] Variables in Tag Memos for Principals

This issue arises when Variables like [RF:rolename], [RG:rolename], [RL:rolename], etc. are used in a Tag Memo, that Memo is referenced by the Sentence of a Principal, and the Variable refers to that Principal. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

If you have Tags with this issue the solution is to change the [RF:rolename], etc. Variable to the corresponding subject Variable, such as [SF]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Events report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

Field Subfield Operator Value Connect
Memo   Contains RF: OR
Memo   Contains RG: END

If variations other than first name and given name may have been used to refer to the subject, lines should be added to the filter to search for them too. In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

Sort Order Column Type Heading Width
2 Prin1 ID P1_ID 6
1 Tag Type Label Label 10
  Date Date 23
  Memo Memo 254
  Prin1 Role * P1_Role 10
  Prin2 Role * P2_Role 10

* (ver. 9.02 and later only)

The report will allow you to see which Memos contain Variables of the type at issue, but you will then have to identify whether any refer to the Role(s) assigned the Principals by examining the Memos shown in the report. For example, you may see this Memo:

[P1F] and [P2F] seem to have adopted [RF:Child], who was born three years before

Examination of the Memo in this case shows that the Principals are referred to with the Variables [P1F] and [P2F], and that the [RF:rolename] variable refers to someone else, so this Memo is not an issue.

There is an alternate method, if you suspect you have used Variables like [RF:rolename], [RG:rolename], etc. in Memos of certain Tag Types, which are then used in the Sentences for Principals to refer to that Principal. You can use the List of Events report with a Filter like the following (ver. 9.02 and later only) can help identify any such cases:

( Field Subfield Operator Value ) Connect
  Tag Type... Label = Equals CENSUS   AND
( Principal1... Role = Equals SPOUSE   OR
  Principal2... Role = Equals SPOUSE ) AND
  Memo   Contains :SPOUSE   END

This filter will identify cases where the Memo contains a Role Variable that refers to the same Role assigned to one or both of the Principals. It does not determine whether the Memo segment containing the Role Variable is used by the Sentence of the Principal with that Role. That has to be determined from examination of the Memo text and/or the Sentences of the Principals. The following arrangement of Output Columns (ver. 9.02 and later only) may be useful:

Sort Order Column Type Heading Width
1 Prin1 ID P1_ID 6
  Prin2 ID P2_ID 6
  Tag Type Label Label 10
2 Date Date 23
  Prin1 Role * P1_Role 10
  Prin2 Role * P2_Role 10
  Memo Memo 254

* (ver. 9.02 and later only)

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

Case 4: [R:rolename] Variables in Tag Memos for Principals or Witnesses

This issue arises when the [R:rolename] Variables is used in a Tag Memo, that Memo is referenced by the Sentence of a Principal or the Sentence of a Witness, and the Variable refers to that person. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

If you have Tags with this issue the solution is to change the [R:rolename] Variable to the corresponding subject Variable, [S]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Events report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

Field Subfield Operator Value Connect
Memo   Contains R: END

In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

Sort Order Column Type Heading Width
2 Witness ID Wit_ID 6
1 Tag Type Label Label 10
  Date Date 23
  Witness Memo Memo 254

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Memo contain the [R:rolename] Variable, but will not identify which refer to the subject of the Sentence. That must be determined by examination of the Memos shown in the report, a strictly manual process.

Case 5: [R:rolename] Variables in Witness Memos

This issue arises when the [R:rolename] Variables is used in a Witness Memo, that Witness Memo is referenced by the Sentence of the Witness, and the Variable refers to that Witness. The problem is that after the changes in the output of the Role Variables, if more than one person entered in the Tag is assigned that Role, a list of all of them will be output rather than just the name of the subject person.

There is no issue when:

If you have Tag Types with this issue the solution is to change the [R:rolename] Variable to the corresponding subject Variable, [S]. The difficulty is in identifying such cases. If you cannot recall such cases but suspect your Project may contain some, the following method may aid in the search.

You can use the List of Witnesses report to create a list of Events with Memos which contain the Variables in question, then examine that report to identify any which refer to the subject person. A Filter such as the following may be useful:

Field Subfield Operator Value Connect
Witness Memo   Contains R: END

In Report Options, on the Output Columns tab, specify information to identify the Tags in question, and include as much of the Memo as possible to facilitate review of the Tags found. I have found the following arrangement of Output Columns useful:

Sort Order Column Type Heading Width
2 Prin1 ID P1_ID 6
1 Tag Type Label Label 10
  Date Date 23
  Memo Memo 254

With those wide field specifications output of the report as an Excel spreadsheet seems to work best.

The report will allow you to see which Witness Memo contain the [R:rolename] Variable, but will not identify which refer to that Witness. That must be determined by examination of the Witness Memos shown in the report, a strictly manual process.


ReigelRidge Home Terry's Tips Home Contact Terry

 

 

Copyright 2000- by Terry Reigel