https://gramps-project.org/wiki/api.php?action=feedcontributions&user=DouginIT&feedformat=atomGramps - User contributions [en]2024-03-28T12:02:05ZUser contributionsMediaWiki 1.31.3https://gramps-project.org/wiki/index.php?title=Example_filters&diff=81927Example filters2020-12-27T19:06:02Z<p>DouginIT: /* Example 1. People with surname Doe who lived in Illinois State */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_{{man version}}_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Filter|Filter Gramplet]] in the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar]] visible. This allows testing the filter on real data before putting the filter in general use. Test each filter individually... don't set up a 2nd stage filter until the 1st stage has been tested. To test: in the Filter tab of the sidebar, select the custom filter you made; then click the {{man button|Find}} button.<br />
<br />
'''Create a custom filter with the following steps:''' <br />
<!--<br />
* {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}}<br />
:shows the {{man label|Define filter}} dialog and adds a new (as yet unnamed) custom filter framework.<br />
* {{man button| {{icon|stock_edit}}}}&nbsp;{{man tooltip|Edit the selected filter}}<br />
:opens the {{man label|Define filter}} dialog and loads your existing custom filter for editing.<br />
* {{man button|Clone}}&nbsp;{{man tooltip|Clone the selected filter}}<br />
:makes an exact copy of the selected filter<br />
* {{man button|Test}}&nbsp;{{man tooltip|Test the selected filter}}<br />
:brings up the {{man label|Filter Test}} results dialog containing a list of matches following a successful test. If the filter test is invalid, an error may be shown instead.<br />
* {{man button| {{icon|stock_remove}}}}&nbsp;{{man tooltip|Delete the selected filter}}:<br />
:removes the selected filter from the Gramps collection of custom filters.<br />
{{-}}<br />
--><br />
* Click on {{man menu|Edit}} in the menu bar to display the drop-down list<br />
: The last item is the {{man menu|____ Filter Editor}} and it is contextual, changing the filter editor to only show filters for the category of the current View<br />
* Click on the {{man menu|Filter Editor}}<br />
* Click on {{man label|Filter Editor}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}} to start creating a new filter<br />
* Give your filter a unique '''name'''<br />
* Click on {{man label|Define Filter : Rule List}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add another rule to the filter}} to see the filter rules ([[Gramps_{{man version}}_Wiki_Manual_-_Filters#Which_filters_in_which_Category.3F|limited to those available in the current View]])<br />
* Select an appropriate filtering '''rule'''<br />
<br />
* Add further rules as needed<br />
<br />
* Select the appropriate {{man label|Define Filter : Options}} pop-up menu item to define how the rules interact. ''The [[man menu|All rules must apply}} option is selected by default.'' This is only necessary when there are multiple rules.<br />
* Click on the {{man label|Define Filter}} {{man button| OK}}<br />
* Click on the {{man label|Filter Editor}} {{man button| Close}} ''Note that new custom filters (or changes) only take effect after closing the Filter Editor.''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
{{man warn|Custom Filters are resource hungry|Very large databases may encounter resource limitations when handling some complex filters}}<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
<br />
=='''''4-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
<br />
''Comment: previous Filter A written for gramps 4.1 does not work in gramps 5 with the new Place hierarchy. It needs to be replaced by new<br />
'''''Filter A:'''''<br />
General filters=><br />
Places enclosed by another place: Name:= "Illinois"; Place type:= "State"<br />
Inclusive:="1" <br />
[NOTE "Include selected Gramps ID" - this is important or the filter excludes events where "Illinois" is the first part of the place address title]<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Birth"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: Filter name:= "B"<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People with a name matching <text>: Text:= "Doe"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter D> in Person View.'''<br />
<br />
<br />
<br />
<br />
''== '''WARNING: According to bugtracker reports (27/12/20) filters using the Place hierarchy may not work properly''' ==''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Talk:Portal:Developers&diff=81892Talk:Portal:Developers2020-12-17T16:43:58Z<p>DouginIT: /* Filters and Dated Places */ new section</p>
<hr />
<div>== Filters and Dated Places ==<br />
<br />
I've come across a bug or complication, I'm afraid, relating to filters acting on Dated Places.<br />
<br />
I created a single-stage filter in my db for People born in Germany<br />
{People with the <birth data>: Place="Germany"} <br />
<br />
The individuals selected by the filter include a person who was born in Schleswig-Holstein in 1854.<br />
At this period it was part of Denmark; Germany itself did not exist before 1871. <br />
<br />
A similar filter for people born in Denmark<br />
{People with the <birth data>: Place="Denmark"} <br />
fails to show this person.<br />
<br />
The Place hierarchy for Schleswig-Holstein in the database is <br />
Schleswig-Holstein< Denmark before 1865; <Prussia from 1867 to 1871; <Germany after 1871. The name Germany is set valid after 1871.</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=81887Example filters2020-12-15T16:00:00Z<p>DouginIT: </p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_{{man version}}_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Filter|Filter Gramplet]] in the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar]] visible. This allows testing the filter on real data before putting the filter in general use. Test each filter individually... don't set up a 2nd stage filter until the 1st stage has been tested. To test: in the Filter tab of the sidebar, select the custom filter you made; then click the {{man button|Find}} button.<br />
<br />
'''Create a custom filter with the following steps:''' <br />
<!--<br />
* {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}}<br />
:shows the {{man label|Define filter}} dialog and adds a new (as yet unnamed) custom filter framework.<br />
* {{man button| {{icon|stock_edit}}}}&nbsp;{{man tooltip|Edit the selected filter}}<br />
:opens the {{man label|Define filter}} dialog and loads your existing custom filter for editing.<br />
* {{man button|Clone}}&nbsp;{{man tooltip|Clone the selected filter}}<br />
:makes an exact copy of the selected filter<br />
* {{man button|Test}}&nbsp;{{man tooltip|Test the selected filter}}<br />
:brings up the {{man label|Filter Test}} results dialog containing a list of matches following a successful test. If the filter test is invalid, an error may be shown instead.<br />
* {{man button| {{icon|stock_remove}}}}&nbsp;{{man tooltip|Delete the selected filter}}:<br />
:removes the selected filter from the Gramps collection of custom filters.<br />
{{-}}<br />
--><br />
* Click on {{man menu|Edit}} in the menu bar to display the drop-down list<br />
: The last item is the {{man menu|____ Filter Editor}} and it is contextual, changing the filter editor to only show filters for the category of the current View<br />
* Click on the {{man menu|Filter Editor}}<br />
* Click on {{man label|Filter Editor}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}} to start creating a new filter<br />
* Give your filter a unique '''name'''<br />
* Click on {{man label|Define Filter : Rule List}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add another rule to the filter}} to see the filter rules ([[Gramps_{{man version}}_Wiki_Manual_-_Filters#Which_filters_in_which_Category.3F|limited to those available in the current View]])<br />
* Select an appropriate filtering '''rule'''<br />
<br />
* Add further rules as needed<br />
<br />
* Select the appropriate {{man label|Define Filter : Options}} pop-up menu item to define how the rules interact. ''The [[man menu|All rules must apply}} option is selected by default.'' This is only necessary when there are multiple rules.<br />
* Click on the {{man label|Define Filter}} {{man button| OK}}<br />
* Click on the {{man label|Filter Editor}} {{man button| Close}} ''Note that new custom filters (or changes) only take effect after closing the Filter Editor.''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
{{man warn|Custom Filters are resource hungry|Very large databases may encounter resource limitations when handling some complex filters}}<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
<br />
=='''''4-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
<br />
''Comment: previous Filter A written for gramps 4.1 does not work in gramps 5 with the new Place hierarchy. It needs to be replaced by new<br />
'''''Filter A:'''''<br />
General filters=><br />
Places enclosed by another place: Name:= "Illinois"; Place type:= "State"<br />
Inclusive:="1" <br />
[NOTE "Include selected Gramps ID" - this is important or the filter excludes events where "Illinois" is the first part of the place address title]<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Birth"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: Filter name:= "B"<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People with a name matching <text>: Text:= "Doe"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter D> in Person View.'''<br />
<br />
<br />
----<br />
<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=81886Example filters2020-12-15T15:29:18Z<p>DouginIT: </p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_{{man version}}_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Filter|Filter Gramplet]] in the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar]] visible. This allows testing the filter on real data before putting the filter in general use. Test each filter individually... don't set up a 2nd stage filter until the 1st stage has been tested. To test: in the Filter tab of the sidebar, select the custom filter you made; then click the {{man button|Find}} button.<br />
<br />
'''Create a custom filter with the following steps:''' <br />
<!--<br />
* {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}}<br />
:shows the {{man label|Define filter}} dialog and adds a new (as yet unnamed) custom filter framework.<br />
* {{man button| {{icon|stock_edit}}}}&nbsp;{{man tooltip|Edit the selected filter}}<br />
:opens the {{man label|Define filter}} dialog and loads your existing custom filter for editing.<br />
* {{man button|Clone}}&nbsp;{{man tooltip|Clone the selected filter}}<br />
:makes an exact copy of the selected filter<br />
* {{man button|Test}}&nbsp;{{man tooltip|Test the selected filter}}<br />
:brings up the {{man label|Filter Test}} results dialog containing a list of matches following a successful test. If the filter test is invalid, an error may be shown instead.<br />
* {{man button| {{icon|stock_remove}}}}&nbsp;{{man tooltip|Delete the selected filter}}:<br />
:removes the selected filter from the Gramps collection of custom filters.<br />
{{-}}<br />
--><br />
* Click on {{man menu|Edit}} in the menu bar to display the drop-down list<br />
: The last item is the {{man menu|____ Filter Editor}} and it is contextual, changing the filter editor to only show filters for the category of the current View<br />
* Click on the {{man menu|Filter Editor}}<br />
* Click on {{man label|Filter Editor}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}} to start creating a new filter<br />
* Give your filter a unique '''name'''<br />
* Click on {{man label|Define Filter : Rule List}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add another rule to the filter}} to see the filter rules ([[Gramps_{{man version}}_Wiki_Manual_-_Filters#Which_filters_in_which_Category.3F|limited to those available in the current View]])<br />
* Select an appropriate filtering '''rule'''<br />
<br />
* Add further rules as needed<br />
<br />
* Select the appropriate {{man label|Define Filter : Options}} pop-up menu item to define how the rules interact. ''The [[man menu|All rules must apply}} option is selected by default.'' This is only necessary when there are multiple rules.<br />
* Click on the {{man label|Define Filter}} {{man button| OK}}<br />
* Click on the {{man label|Filter Editor}} {{man button| Close}} ''Note that new custom filters (or changes) only take effect after closing the Filter Editor.''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
{{man warn|Custom Filters are resource hungry|Very large databases may encounter resource limitations when handling some complex filters}}<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
<br />
''Comment: previous Filter A written for gramps 4.1 does not work in gramps 5 with the new Place hierarchy. It needs to be replaced by new<br />
'''''Filter A:'''''<br />
General filters=><br />
Places enclosed by another place: Name:= "Illinois"; Place type:= "State"<br />
Inclusive:="1" <br />
[NOTE "Include selected Gramps ID" - this is important or the filter excludes events where "Illinois" is the first part of the place address title]<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Birth"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: Filter name:= "B"<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People with a name matching <text>: Text:= "Doe"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter D> in Person View.'''<br />
<br />
<br />
----<br />
<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=81885Example filters2020-12-14T12:39:02Z<p>DouginIT: </p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_{{man version}}_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the [[Gramps_{{man version}}_Wiki_Manual_-_Gramplets#Filter|Filter Gramplet]] in the [[Gramps_{{man version}}_Wiki_Manual_-_Main_Window#Bottombar_and_Sidebar|sidebar]] visible. This allows testing the filter on real data before putting the filter in general use. Test each filter individually... don't set up a 2nd stage filter until the 1st stage has been tested. To test: in the Filter tab of the sidebar, select the custom filter you made; then click the {{man button|Find}} button.<br />
<br />
'''Create a custom filter with the following steps:''' <br />
<!--<br />
* {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}}<br />
:shows the {{man label|Define filter}} dialog and adds a new (as yet unnamed) custom filter framework.<br />
* {{man button| {{icon|stock_edit}}}}&nbsp;{{man tooltip|Edit the selected filter}}<br />
:opens the {{man label|Define filter}} dialog and loads your existing custom filter for editing.<br />
* {{man button|Clone}}&nbsp;{{man tooltip|Clone the selected filter}}<br />
:makes an exact copy of the selected filter<br />
* {{man button|Test}}&nbsp;{{man tooltip|Test the selected filter}}<br />
:brings up the {{man label|Filter Test}} results dialog containing a list of matches following a successful test. If the filter test is invalid, an error may be shown instead.<br />
* {{man button| {{icon|stock_remove}}}}&nbsp;{{man tooltip|Delete the selected filter}}:<br />
:removes the selected filter from the Gramps collection of custom filters.<br />
{{-}}<br />
--><br />
* Click on {{man menu|Edit}} in the menu bar to display the drop-down list<br />
: The last item is the {{man menu|____ Filter Editor}} and it is contextual, changing the filter editor to only show filters for the category of the current View<br />
* Click on the {{man menu|Filter Editor}}<br />
* Click on {{man label|Filter Editor}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add a new filter}} to start creating a new filter<br />
* Give your filter a unique '''name'''<br />
* Click on {{man label|Define Filter : Rule List}} {{man button| {{icon|stock_add}}}}&nbsp;{{man tooltip|Add another rule to the filter}} to see the filter rules ([[Gramps_{{man version}}_Wiki_Manual_-_Filters#Which_filters_in_which_Category.3F|limited to those available in the current View]])<br />
* Select an appropriate filtering '''rule'''<br />
<br />
* Add further rules as needed<br />
<br />
* Select the appropriate {{man label|Define Filter : Options}} pop-up menu item to define how the rules interact. ''The [[man menu|All rules must apply}} option is selected by default.'' This is only necessary when there are multiple rules.<br />
* Click on the {{man label|Define Filter}} {{man button| OK}}<br />
* Click on the {{man label|Filter Editor}} {{man button| Close}} ''Note that new custom filters (or changes) only take effect after closing the Filter Editor.''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
{{man warn|Custom Filters are resource hungry|Very large databases may encounter resource limitations when handling some complex filters}}<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
<br />
''Comment: previous Filter A written for gramps 4.1 does not work in gramps 5 with the new Place hierarchy. It needs to be replaced by new<br />
'''''Filter A:'''''<br />
General filters=><br />
Places enclosed by another place: Name:= "Illinois"; Place type:= "State"<br />
Inclusive:="1" <br />
[NOTE "Include selected Gramps ID" - this is important or the filter excludes events where "Illinois" is the first part of the place address title]<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=57799Example filters2015-08-25T12:33:55Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
<br />
''Bugnotes1: A bug in 4.1.3 interferes with filter creation. The bug report (#8643) provides a patch to correct it''<br />
<br />
''Bugnotes2: A bug in gramps 4.0 - 4.1 prevents custom filters working with Notes. There is a patch in bug report #7595. Recent versions of 4.2 work correctly'' <br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55751Example filters2015-07-27T13:26:09Z<p>DouginIT: /* Example 5. Show birthplaces of all people with the surname Whitesmith */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
''Note: A bug in 4.1.3 interferes with filter creation. The bug report (#8643) provides a patch to correct it''<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55750Example filters2015-07-27T13:24:46Z<p>DouginIT: /* Example 5. Show birthplaces of all people with the surname Whitesmith */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
''Note: A bug in 4.1.3 interferes with filter creation. The bug report (#8643) provides a patch to correct it''<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
<br />
''[Acknowledgement: thanks to S. Noiraud for pointing out this very useful combination of filter and Geography View]<br />
''<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55749Example filters2015-07-27T13:19:48Z<p>DouginIT: /* Example 4. End of the line ancestors from a particular person X (Jones) */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
''Note: A bug in 4.1.3 interferes with filter creation. The bug report (#8643) provides a patch to correct it''<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
----<br />
=== Example 5. Show birthplaces of all people with the surname Whitesmith ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
<br />
General filters=><br />
People with the <name> : Full family name:="Whitesmith"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Events Filter Editor'''''<br />
'''''Filter B:'''''<br />
<br />
General filters=> <br />
Events of persons matching the <person filter>: Filter name:="A" <br />
General filters=> <br />
Events with the particular type: Event type:="Birth"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Places Filter Editor'''''<br />
'''''Filter C:'''''<br />
<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:="B"<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter C> in Place View''' to check''<br />
<br />
<br />
<br />
<br />
These Places can be displayed in '''Geography View'''<br />
<br />
Select '''All Known Places''', but use '''Filter sidebar''' with '''Custom filter "C"''' to restrict the places shown to birthplaces of the Whitesmith family<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55206Example filters2015-06-30T10:51:38Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover Gramps versions 3.4.x to 4.1x<br />
<br />
''Note: A bug in 4.1.3 interferes with filter creation. The bug report (#8643) provides a patch to correct it''<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55128Example filters2015-06-20T10:45:35Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
<br />
Most of the following examples appeared on the Gramps-Users mailing list in response to posts from users and cover ''Gramps versions 3.4.x to 4.1x''<br />
<br />
<br />
----<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55127Example filters2015-06-20T10:32:28Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_4.1_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
There are rules to allow you to use filters defined for another View. In this way you can build up complex filtering involving several Views.<br />
<br />
''Note that very large databases may encounter resource limitations when handling some complex filters''<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55105Example filters2015-06-19T19:10:38Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_3.4_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
Some rules allow you to use filters defined for another View and so build up complex filtering with several Views.<br />
<br />
''Note that very large databases may encounter resource problems in handling some complex filters''<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55104Example filters2015-06-19T19:00:27Z<p>DouginIT: /* Unconnected/unrelated people */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_3.4_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
Some rules allow you to use filters defined for another View and so build up complex filtering with several Views.<br />
<br />
<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55103Example filters2015-06-19T19:00:00Z<p>DouginIT: /* Example: All married males with family name containing rechter/richter */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_3.4_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
Some rules allow you to use filters defined for another View and so build up complex filtering with several Views.<br />
<br />
<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
<br />
== Unconnected/unrelated people ==<br />
This is a filter to determine which people in your tree have no direct connection to you.<br />
<br />
=== List all unconnected people===<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''General filters->Disconnected people''.<br />
*Save the filter with a name<br />
*In the People view, turn on the filter sidebar and apply the new filter.<br />
<br />
The People view will now only display people who are not connected to any other people.<br />
<br />
Note that only individually-disconnected people will be shown, not families. (See the [[Unsupported Plugins#Not_Related|Not Related plugin]] to find both people and families that are disconnected.)<br />
<br />
=== List all people not related to you ===<br />
If you want people that are not related to you, do this:<br />
<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''Ancestral filters->People with a common ancestor with <person>''. (choose yourself as the person)<br />
*Check the option marked ''Return values that do not match the filter rules''<br />
*Save the filter with a name<br />
In the People view, turn on the filter sidebar and apply the new filter.<br />
*The People view will now only display people who are not related to you.<br />
<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55102Example filters2015-06-19T18:59:30Z<p>DouginIT: /* Example: All female descendants of Joan Doe */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_3.4_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
Some rules allow you to use filters defined for another View and so build up complex filtering with several Views.<br />
<br />
<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
<br />
==Example: All married males with family name containing rechter/richter==<br />
Three possibilities are given. Although one might be inclined to use one of the first two, the third filter, using the family object, is clearly the easiest, and most straightforward.<br />
=== Use the Marriage event ===<br />
* With Person Filter Editor, create a custom filter with name ''MarriageFamEventMale''. Add the rule 'People with Family <event>', event "Marriage". Next add the rule 'Males' <br />
* In the Filter dialog, make sure the option 'all rules must apply' is checked.<br />
* In the Filter sidebar, type in Name field: r<nowiki>[ei]</nowiki>chter, select Custom Filter: ''MarriageFamEventMale'', and check the box 'User regular expressions'. Click Find. <br />
<br />
=== Allow for relationship Married ===<br />
We adopt the previous filter, by also looking at relationship Married, even if no event marriage is present.<br />
* With Person Filter Editor, create a custom filter with name ''MarriedRelMale''. Add the rule ''People with the <relationships>'' to the filter, and select as value for relationship: Married. Next add the rule ''Males''. Make sure the option ''all rules must apply'' is checked<br />
* With Person Filter Editor, create a custom filter, name ''MarriedMale''. Add the rule ''People matching the <filter>'' twice, once with filter ''MarriageFamEventMale'', once with filter ''MarriedRelMale''.<br />
* Make sure that for this filter, the option ''at least one rule must apply'' is selected<br />
* In the Filter sidebar, type in Name field: r<nowiki>[ei]</nowiki>chter, set Gender: Male, Custom Filter: ''MarriedMale'', and check the box ''Use regular expressions''. Click Find. <br />
<br />
=== Use a Family filter instead ===<br />
Alternatively, one can find an answer to this query by looking in the Family list view at relationship Married, or event Marriage. <br />
* With Family Filter Editor, create custom filter, name ''MarriedFamily''. Add the rule ''Families with the <event>'', and set event to "Marriage". Next add the rule ''Family with relationship type'', with value ''Married''. <br />
* For the filter ''MarriedFamily'' select the option: ''at least one rule must apply''<br />
* In the Family List view, go to the Filter Sidebar, and type for father name ''r<nowiki>[ei]</nowiki>chter'', select as custom filter ''MarriedFamily'', and select the ''Use regular expressions'' checkbox, and click find.<br />
* Set the columns of the family view to only view the father (in the edit menu, select column editor).<br />
* Optional: The name of the father can be added to the custom filter with the rule 'Families with father with the <name>', however, in that case the name of the custom filter is better changed to eg. ''MarriedRechterFamily'', and in the rules with <name> no regular expressions can be used, making it not usefull to find variants like ''richter'' at the same time<br />
<br />
== Unconnected/unrelated people ==<br />
This is a filter to determine which people in your tree have no direct connection to you.<br />
<br />
=== List all unconnected people===<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''General filters->Disconnected people''.<br />
*Save the filter with a name<br />
*In the People view, turn on the filter sidebar and apply the new filter.<br />
<br />
The People view will now only display people who are not connected to any other people.<br />
<br />
Note that only individually-disconnected people will be shown, not families. (See the [[Unsupported Plugins#Not_Related|Not Related plugin]] to find both people and families that are disconnected.)<br />
<br />
=== List all people not related to you ===<br />
If you want people that are not related to you, do this:<br />
<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''Ancestral filters->People with a common ancestor with <person>''. (choose yourself as the person)<br />
*Check the option marked ''Return values that do not match the filter rules''<br />
*Save the filter with a name<br />
In the People view, turn on the filter sidebar and apply the new filter.<br />
*The People view will now only display people who are not related to you.<br />
<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Example_filters&diff=55101Example filters2015-06-19T18:58:39Z<p>DouginIT: /* Introduction */</p>
<hr />
<div>{{languages|Example filters}}<br />
{{out of date|check}}<br />
A collection of examples of filters. <br />
<br />
==Introduction==<br />
For more info, see [[Filter]] and also [[Gramps_3.4_Wiki_Manual_-_Filters|the wiki manual on Filters]].<br />
When creating custom filters, always make sure you have the Filter sidebar visible so you can test them before use: either click on the Filter tab on the right, or click on 'Add a Gramplet' and select 'Filter'. To test, select the custom filter you made; then click Find.<br />
<br />
You create a custom filter by taking the following steps: <br />
<br />
Click on '''Editor''' in the top bar to display the drop-down list<br />
The last item is the '''Filter Editor''' for your current View<br />
Click on the '''Filter Editor'''<br />
Click on ''''+'''' to start creating a new filter<br />
Give your filter a '''name'''<br />
Click on ''''+'''' to see the filter rules available to you in your current View<br />
Select an appropriate '''rule'''<br />
<br />
Add further rules as needed<br />
<br />
Set the necessary '''Option'''<br />
'''OK'''<br />
'''Close''' ''[Note that custom filters or changes only take effect after Closing the Filters window]''<br />
<br />
<br />
Some rules allow you to use filters defined for another View and so build up complex filtering with several Views.<br />
<br />
<br />
<br />
== Construction of custom filter examples ==<br />
<br />
<br />
<br />
Please note these conventions for the construction of Filters:<br />
<br />
'''''<Viewname> Filter Editor'''''.................Editor for this particular View<br />
'''''Filter <filtername>:'''''...........................................................................................................Name of new filter<br />
<rule name> ........................................................Filter rule selected<br />
<br />
OR<br />
<br />
<rule group name> => <br />
<selected rule name> ..........................................Filter rule selected from a drop-down group of rules<br />
<br />
'''Option selected''' ................................................................................................................. All/At least one rule must be obeyed<br />
<br />
'''Use regular expressions''' ................................................................................................. Blank if not required<br />
<br />
'''<Run Filter <filtername> in <Viewname> View>''' .....................................................Where to run the new filter<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''1-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All sources that have no repository ===<br />
<br />
'''''Source Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Sources with <count> Repository references; Number of instances:="1"; Number must be:="lesser than"<br />
''OR''<br />
Sources with a reference count of <count>; Reference count must be:= "lesser than"; Reference count:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Source View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. All individuals with no name ===<br />
<br />
''Comment: In Person View, click on the Name column to get the names in alphabetical order. All blank surnames will be at the top of the list''<br />
<br />
The following filter will display '''only''' the blank given names and/or surnames<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <name>; Given Name:=^$; Full Family Name:=^$<br />
<br />
'''Use regular expressions'''<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 3. All female descendants of Joan Doe ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=><br />
Descendants of <person>: <''here find the ID of Joan Doe''> ; Include original person<br />
General filters=><br />
Females<br />
<br />
'''All rules must apply'''<br />
<br />
'''<Run Filter A> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''2-stage FILTERS'''''==<br />
<br />
<br />
=== Example 1. All people with only one parent recorded ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Persons with the <name>; Given name:="(^$|[uU]known)"; Full Family Name:="(^$|[uU]known)"<br />
<br />
'''**Use regular expressions**'''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: If both parents are unknown you probably won't have any gramps ID assigned for them''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. Individuals with siblings named “John” ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
People with the <name>: Given Name:="John"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filter=> <br />
Siblings of <filter> match: Filter name:="A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 3.“Timeline” of all people associated with a particular place ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Places matching the parameters ;Name : <''here insert name of place''><br />
<br />
'''All rules must apply'''<br />
'''''Event Filter Editor'''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Events matching the place filter: Place filter name:=”A”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Events view'''<br />
<br />
''Configure the View to show columns for Type, Description, Date, Place.''<br />
'' Order the items by Date to get a timeline.''<br />
<br />
<br />
OR Alternative 2:<br />
'''''Event Filter Editor'''<br />
'''''Filter A:'''''<br />
General filters=> <br />
Events with data : Place:= <''here insert placename''><br />
''Comment: if the Event type default is "Birth"., just delete it'' <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter A> in Events View'''<br />
<br />
<br />
''For an ordered list of the people '''add''' the following filter:''<br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=> <br />
Persons with events matching the events filter: Events filter name:= "A".<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 4. All marriage events on the ancestral tree dated after 1837 for a named individual ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the personal <event>; Personal event:= Marriage; Date:= after 1837<br />
Event filters=><br />
People with the family <event>; Family event:= Marriage; Date:= after 1837 <br />
<br />
'''**At least one rule applies**'''<br />
<br />
'''''Filter B:'''''<br />
General filters=> <br />
People with the name; <''here insert name of individual''><br />
General filters=><br />
People matching the <filter>; Filter name:=”A”.<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 5. All persons called "serge" having some connection with London ===<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Events with <data>: Place:="London"<br />
<br />
'''All rules must apply''' <br />
'''''Person Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Persons with events matching the <event filter>: Event filter name:= "A"<br />
People with the <name>: Given name:="serge"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View'''<br />
<br />
<br />
<br />
''Comment1: There is no way of going between people and places except by way of events they were involved in at those places''<br />
<br />
''Comment2: What looks like a minor bug appears when Person filtering on names: a few extraneous individuals appear.''<br />
''They are spouses, included because their married name (or occasionally spouse) is recorded in the database as their Alternative Name'' <br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
<br />
=== Example 6. Obtain a ‘focused’ descendant chart containing only a subset of the people ===<br />
<br />
''Select the subset by tagging manually in your direct ancestral line up from your living relative. Call the tag, say, LINE 1.''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
People with the <tag>; Tag:="LINE 1"<br />
<br />
'''All rules must apply'''<br />
<br />
'''''Filter B:'''''<br />
Family filters=><br />
Children of <filter> match: Filter name:="A"<br />
Family filters=><br />
Spouses of <filter> match: Filter name:="A"<br />
Family filters=><br />
Siblings of <filter> match: Filter name:="A"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <run Filter B> in Person View''' to display the “focussed” tree<br />
<br />
''OR:''<br />
''Reports=> Graphs=> Relationship Graph=> Report Options=> Filter "B"'' to obtain a chart. Save as SVG for further manipulation<br />
''OR:''<br />
''Family Trees=> Export=> Forward=> select Gramps XML package=> Forward=> Person Filter.'' <br />
Click the drop-down list and ''select filter B'' to save the filter results as another family tree. <br />
Name and export that gpkg; then you can create a new family tree and import the gpkg back into it.<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 7. All people related to me but not my wife ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Ancestral filters=><br />
Ancestors of <person> ID:= <here find YOUR ID>; Inclusive:=0 ''i.e.note: don't include yourself''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter A"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
''Comment: note the difference between the UP filter ("Ancestors") which is '''restrictive''''' <br />
''and the DOWN filter ("Descendant family members of filter) which is '''inclusive'''.'' <br />
The former keeps the line of relationship away from the wife; the latter brings in your own in-laws<br />
("Matches people that are descendants or the spouse of anybody matched by the filter")<br />
<br />
''Comment 2: the filter falls down on people who are not strictly connected to you by marriage but only indirectly''<br />
i.e. people who were married at some time to one of your in-laws, i.e.."in-laws of in-laws".<br />
<br />
''If you want to incorporate those links as well, add a further filter as follows:''<br />
<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <filter> match; Filter name:="Filter B"<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''THEN <Run Filter C> in Person View'''<br />
<br />
''Comment 3: you can widen the reach of the links further by adding more filters in the same form as filter C'' - until your patience runs out<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 8. All married males with family name containing rechter/richter ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=><br />
People with the family <event>: Family event=> Family:= Marriage<br />
General filters=><br />
Males<br />
<br />
'''All rules must apply'''<br />
<br />
'''''<Run Filter A> in Person View''''' ''to check''<br />
<br />
THEN in the '''Filter sidebar''', enter ''r[ei]chter'' in the '''Name''' field, for the '''Custom filter''' select ''Filter A'', check '''Use regular expressions'''. Click '''Find'''.<br />
<br />
<br />
<br />
----<br />
<br />
<br />
=== Example 9. All descendants of Joan Doe of female or unknown sex ===<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Males<br />
<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Descendant filters=><br />
Descendants of person:=<here find the ID of Joan Doe>; Include original person<br />
<br />
'''All rules must apply'''<br />
<br />
'''THEN <Run Filter B> in Person View'''<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
=='''''3-stage FILTERS'''''==<br />
<br />
<br />
<br />
<br />
<br />
=== Example 1. All marriages where the event is a "Personal" event but not part of a Family ===<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Event filters=> <br />
People with the family <event>; Family Event:="Marriage"<br />
<br />
'''All rules must apply'''<br />
<br />
'''**Return values that do *not* match the filter rules**'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Event filters=> <br />
People with the personal <event>; Personal Event:="Marriage"; Primary role:="1"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=><br />
People matching the <filter>; Filter name:= "A"<br />
General filters=><br />
People matching the <filter>; Filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<Run Filter C> in Person View'''<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 2. People with events with place, to show an ancestor's descendants with no known birthplace ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
Position filters=> <br />
Places with no latitude or longitude given<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events with the particular type: Event type:="Birth"<br />
General filters=><br />
Events of Places matching the <place filter>: Place filter name:=”A” <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
Descendant filters=><br />
Descendant family members of <person>:= <''here select the particular ancestor ID''> <br />
General filters=> <br />
Persons with events matching the <event filter>: Event Filter name:=”B”<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Person View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
<br />
=== Example 3. All direct ancestors (and their siblings) of some person in set periods, e.g. 50 yrs ===<br />
<br />
<br />
''Comment: For example, to show when the migration from country to town took place''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Descendant filters=> <br />
Descendant family members of <person>; select the person's ID; Include the original person<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filter => <br />
Events of persons matching the <person filter>: Person filter name:= "A"<br />
General filter=><br />
Events with <data>: Event type:= "Birth"; Date:="between 1650 and 1750" ''(say)''<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
Places of events matching the <event filter>: Event filter name:= "B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''<run Filter C> in Place View'''<br />
<br />
<br />
<br />
----<br />
<br />
<br />
<br />
=== Example 4. End of the line ancestors from a particular person X (Jones) ===<br />
<br />
<br />
''Deal with the father's and mother's side separately.''<br />
<br />
'''[father's side]'''<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter A:'''''<br />
Family filters=><br />
People missing parents<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter B:'''''<br />
Ancestral filters=><br />
Ancestors of <person>: ID := <''here find ID of person X''><br />
General filters=> <br />
Males<br />
General filters=><br />
People with the <name>:Full Family Name:="Jones"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter C:'''''<br />
General filters=> <br />
People matching the filter; Filter name:="A"<br />
General filters=><br />
People matching the filter; Filter name:="B"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
<br />
'''<Run Filter C> in Person View.'''<br />
<br />
'''[mother's side]'''<br />
<br />
repeat A, B, C but in Filter B substitute the ID of the mother of X for the ID of X, and the family name of the mother of X for the name “Jones”.<br />
<br />
''Comment: if the spelling of the surname has changed over the generations, you'll need to use a regular expression for the Full Family Name in Filter B and enable “Use regular expressions”''<br />
<br />
<br />
<br />
----<br />
<br />
----<br />
<br />
----<br />
<br />
<br />
== '''''5-stage FILTERS''''' ==<br />
<br />
<br />
<br />
=== Example 1. People with surname Doe who lived in Illinois State ===<br />
<br />
'''''Place Filter Editor'''''<br />
'''''Filter A:'''''<br />
General filters=><br />
Places matching parameters: Name:= "Illinois"; Place type:= "State"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Event Filter Editor'''''<br />
'''''Filter B:'''''<br />
General filters=><br />
Events of places matching the <place filter>: Place filter name:="A" <br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Person Filter Editor'''''<br />
'''''Filter C:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Residence"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter D:'''''<br />
General filters=><br />
People with events matching the <event filter>: event filter name:= "B"<br />
Event filters=><br />
People with the personal <event>: Personal event:="Death"<br />
<br />
'''All rules must apply'''<br />
<br />
<br />
'''''Filter E:'''''<br />
General filters=><br />
People matching the <filter>: Filter name:= "C"<br />
General filters=><br />
People matching the <filter>: Filter name:= "D"<br />
<br />
<br />
'''**At least one rule must apply**'''<br />
<br />
<br />
'''<Run Filter E> in Person View.'''<br />
<br />
<br />
----<br />
<br />
== Example: All female descendants of Joan Doe==<br />
=== Simple implementation ===<br />
The following does exactly what is asked:<br />
*In the Edit view, go to Joan Doe, and note the GRAMPS ID.<br />
*In the View menu, select ''Person Filter Editor''<br />
*Click on ''Add a New Filter''. In the Define filter dialog, give the filter the name ''Female descendants of Joan Doe''<br />
*Next to the rule list, click on ''Add another rule to the filter'', which opens the ''Add Rule'' Dialog.<br />
*Go to Descendant filters, and select the rule ''Descendants of <person>''. Give as value the GRAMPS ID, and select the box ''include original person''<br />
*Click again on ''Add another rule'', and now go to ''General filters'', and select the rule ''females''<br />
*In the options section of the Define filter dialog, make sure ''all rules must apply'', is selected<br />
<br />
=== A variation: also return unknown sex ===<br />
You might want to add the people with unknown sex to the output. For this, you need to combine two filters:<br />
*Make a filter: ''female or unknown'', consisting of one general filter: ''males'', and in the options you select: ''return values that do not satisfy the filter rules''<br />
*Make a second filter: ''female or unknown descendants of Joan Doe'', with as rules ''Descendants of <person>'' where the value is the GRAMPS ID of Joand Doe, and as second rule the general filter ''People matching the <filter>'', with as value for <filter> ''female or unknown''<br />
*Again, in the Define filter dialog, ''all rules must apply'' must be checked<br />
<br />
=== Slightly different: only female line===<br />
In this case, you only want to see the female line, so a female child of a male descendants of Joan Doe should '''not''' be present. <br />
<br />
As far as I can tell, this is not possible in Gramps version 2.2.6. You should do a feature request if you need this.{{bug|???}}<br />
<br />
==Example: All married males with family name containing rechter/richter==<br />
Three possibilities are given. Although one might be inclined to use one of the first two, the third filter, using the family object, is clearly the easiest, and most straightforward.<br />
=== Use the Marriage event ===<br />
* With Person Filter Editor, create a custom filter with name ''MarriageFamEventMale''. Add the rule 'People with Family <event>', event "Marriage". Next add the rule 'Males' <br />
* In the Filter dialog, make sure the option 'all rules must apply' is checked.<br />
* In the Filter sidebar, type in Name field: r<nowiki>[ei]</nowiki>chter, select Custom Filter: ''MarriageFamEventMale'', and check the box 'User regular expressions'. Click Find. <br />
<br />
=== Allow for relationship Married ===<br />
We adopt the previous filter, by also looking at relationship Married, even if no event marriage is present.<br />
* With Person Filter Editor, create a custom filter with name ''MarriedRelMale''. Add the rule ''People with the <relationships>'' to the filter, and select as value for relationship: Married. Next add the rule ''Males''. Make sure the option ''all rules must apply'' is checked<br />
* With Person Filter Editor, create a custom filter, name ''MarriedMale''. Add the rule ''People matching the <filter>'' twice, once with filter ''MarriageFamEventMale'', once with filter ''MarriedRelMale''.<br />
* Make sure that for this filter, the option ''at least one rule must apply'' is selected<br />
* In the Filter sidebar, type in Name field: r<nowiki>[ei]</nowiki>chter, set Gender: Male, Custom Filter: ''MarriedMale'', and check the box ''Use regular expressions''. Click Find. <br />
<br />
=== Use a Family filter instead ===<br />
Alternatively, one can find an answer to this query by looking in the Family list view at relationship Married, or event Marriage. <br />
* With Family Filter Editor, create custom filter, name ''MarriedFamily''. Add the rule ''Families with the <event>'', and set event to "Marriage". Next add the rule ''Family with relationship type'', with value ''Married''. <br />
* For the filter ''MarriedFamily'' select the option: ''at least one rule must apply''<br />
* In the Family List view, go to the Filter Sidebar, and type for father name ''r<nowiki>[ei]</nowiki>chter'', select as custom filter ''MarriedFamily'', and select the ''Use regular expressions'' checkbox, and click find.<br />
* Set the columns of the family view to only view the father (in the edit menu, select column editor).<br />
* Optional: The name of the father can be added to the custom filter with the rule 'Families with father with the <name>', however, in that case the name of the custom filter is better changed to eg. ''MarriedRechterFamily'', and in the rules with <name> no regular expressions can be used, making it not usefull to find variants like ''richter'' at the same time<br />
<br />
== Unconnected/unrelated people ==<br />
This is a filter to determine which people in your tree have no direct connection to you.<br />
<br />
=== List all unconnected people===<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''General filters->Disconnected people''.<br />
*Save the filter with a name<br />
*In the People view, turn on the filter sidebar and apply the new filter.<br />
<br />
The People view will now only display people who are not connected to any other people.<br />
<br />
Note that only individually-disconnected people will be shown, not families. (See the [[Unsupported Plugins#Not_Related|Not Related plugin]] to find both people and families that are disconnected.)<br />
<br />
=== List all people not related to you ===<br />
If you want people that are not related to you, do this:<br />
<br />
*Create a new custom person filter using ''Edit->Person Filter Editor''.<br />
*Add a rule to the new filter: ''Ancestral filters->People with a common ancestor with <person>''. (choose yourself as the person)<br />
*Check the option marked ''Return values that do not match the filter rules''<br />
*Save the filter with a name<br />
In the People view, turn on the filter sidebar and apply the new filter.<br />
*The People view will now only display people who are not related to you.<br />
<br />
{{languages|Example filters}}<br />
<br />
[[Category:Gramps Examples]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46564Custom Event Types2013-10-03T11:11:09Z<p>DouginIT: /* Other */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Origin<br />
* Stillbirth<br />
* Circumcision<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Liquidation<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Court Case<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Medical ==<br />
<br />
* Injury<br />
* Illness<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
* Commendation<br />
* Disciplinary Action<br />
* Desertion<br />
* Escape<br />
* Evacuation<br />
* Internment<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
* Expedition<br />
<br />
== Other ==<br />
<br />
* Apprenticeship<br />
* Award (Prize, honour, decoration etc...)<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
* Family Gathering<br />
* Wedding Dinner<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46563Custom Event Types2013-10-03T11:09:03Z<p>DouginIT: /* Travel */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Origin<br />
* Stillbirth<br />
* Circumcision<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Liquidation<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Court Case<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Medical ==<br />
<br />
* Injury<br />
* Illness<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
* Commendation<br />
* Disciplinary Action<br />
* Desertion<br />
* Escape<br />
* Evacuation<br />
* Internment<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
* Expedition<br />
<br />
== Other ==<br />
<br />
* Apprenticeship<br />
* Award (Prize, honour, decoration etc...)<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46562Custom Event Types2013-10-03T11:07:33Z<p>DouginIT: /* Military */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Origin<br />
* Stillbirth<br />
* Circumcision<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Liquidation<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Court Case<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Medical ==<br />
<br />
* Injury<br />
* Illness<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
* Commendation<br />
* Disciplinary Action<br />
* Desertion<br />
* Escape<br />
* Evacuation<br />
* Internment<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Apprenticeship<br />
* Award (Prize, honour, decoration etc...)<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46561Custom Event Types2013-10-03T11:06:08Z<p>DouginIT: /* Legal */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Origin<br />
* Stillbirth<br />
* Circumcision<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Liquidation<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Court Case<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Medical ==<br />
<br />
* Injury<br />
* Illness<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
* Commendation<br />
* Disciplinary Action<br />
* Desertion<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Apprenticeship<br />
* Award (Prize, honour, decoration etc...)<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46560Custom Event Types2013-10-03T11:04:35Z<p>DouginIT: /* Life Events */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Origin<br />
* Stillbirth<br />
* Circumcision<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Medical ==<br />
<br />
* Injury<br />
* Illness<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
* Commendation<br />
* Disciplinary Action<br />
* Desertion<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Apprenticeship<br />
* Award (Prize, honour, decoration etc...)<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46546Custom Event Types2013-10-02T10:46:05Z<p>DouginIT: /* Legal */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46545Custom Event Types2013-10-02T10:44:41Z<p>DouginIT: /* Travel */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Naturalization<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46544Custom Event Types2013-10-02T10:44:28Z<p>DouginIT: /* Travel */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Naturalization<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigaration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
* Port of Call<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46543Custom Event Types2013-10-02T10:43:34Z<p>DouginIT: /* Military */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Naturalization<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
* Partisan service<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigaration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46542Custom Event Types2013-10-02T10:41:23Z<p>DouginIT: /* Legal */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Naturalization<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigaration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46541Custom Event Types2013-10-02T10:40:36Z<p>DouginIT: /* Life Events */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigaration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Custom_Event_Types&diff=46540Custom Event Types2013-10-02T10:39:53Z<p>DouginIT: /* Life Events */</p>
<hr />
<div>This page lists custom event types.<br />
<br />
These are event types that are currently used by some users. They are not necessarily recommended, but may be a useful starting point.<br />
<br />
== Life Events ==<br />
<br />
* Stillbirth<br />
* Separation<br />
* Name Change<br />
* Transition (Sex change)<br />
* Naturalization<br />
<br />
== Legal ==<br />
<br />
* Bankruptcy<br />
* Civil Lawsuit<br />
* Civil Appeal<br />
* Criminal<br />
* Indictment<br />
* Conviction<br />
* Criminal Appeal<br />
* Declaration of Intention (First Papers in the naturalization process in the US)<br />
* Trial<br />
* Inquest<br />
<br />
== Military ==<br />
<br />
* Battle<br />
* [[Draft_lottery|Draft Registration]] (US only?)<br />
<br />
== Political ==<br />
<br />
* Appointed<br />
<br />
== Travel ==<br />
<br />
Travel other than Immigaration and Emigration.<br />
<br />
* Arrival<br />
* Departure<br />
* Travel<br />
<br />
== Other ==<br />
<br />
* Publication (Publication of a book, article, academic paper etc...)<br />
* Yahrzeit (Hebrew calendar anniversary of death)<br />
<br />
[[Category:Events]]<br />
[[Category:Gramps terminology]]<br />
[[Category:Translators/Categories]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=GEPS_006:_Better_Place_handling&diff=40018GEPS 006: Better Place handling2012-10-21T13:59:42Z<p>DouginIT: /* Good definition of place and address/residence event in Gramps */</p>
<hr />
<div>== Changes already implemented ==<br />
<br />
;New hierarchical place view for Gramps version 3.2.<br />
A new hierarchical place view was introduced in Gramps version 3.2.<br />
<br />
The place object was left unchanged, but the existing location fields were interpreted as a hierarchy. The location fields are as follows:<br />
* Country<br />
* State<br />
* County<br />
* City<br />
* Street<br />
The new view displays Country, State and County as a tree.<br />
<br />
;New Locality Field for Gramps version 3.3<br />
A Locality field has been added to the location for Gramps version 3.3. The new hierarchy is as follows:<br />
* Country<br />
* State<br />
* County<br />
* City<br />
* Locality<br />
* Street<br />
<br />
== Proposed changes ==<br />
<br />
=== Integration with online map tools ===<br />
Which online map tools? - NH<br />
* Openstreetmap, we need free data in a free application. GeoView already allows a view based on places, also to set lat/lon<br />
<br />
=== Good definition of place and address/residence event in Gramps ===<br />
* For UK data, an extra Locality field between City and Street would be useful.<br />
* For Dutch data, an extra Municipality field between County and City would be useful. (Feature Request {{bug|4231}})<br />
* Japanese use block names, instead of street names: [http://en.wikipedia.org/wiki/Japanese_addressing_system]<br />
<br />
We could re-define each field for each country, or we could try to keep each field maintaining similar data. I think that I prefer adding a couple of extra fields. This is less complex than a list structure with definable number of tiers (less complex to program, but also less complex to use by the user)<br />
<br />
{| {{Prettytable}}<br />
|-<br />
! Existing !! New structure!! General Name!! USA !! England !! France !! Netherlands !! Germany !! China<br />
|-<br />
| State || Tier 1 || Region || State || Not Used || Region || Not Used || Province || Province<br />
|-<br />
| County || Tier 2 || District || County || County || Department || Province || District || County<br />
|-<br />
| City || Tier 3 || City || City || City || City || Municipality/City || City || City<br />
|-<br />
| / || Tier 4 || Locality || Locality || Locality || Hamlet/Lieu-dit || City/community/hamlet || Locality || Locality<br />
|-<br />
| Street || Tier 5 || Street || Street || Street || Street || Street || Street || Street<br />
|-<br />
|}<br />
<br />
Definitions:<br />
* ''' Tier 1 & 2''': Between a country and the smallest administrative section, we allow for two levels.<br />
* ''' Tier 3 ''': A settlement consisting of a number of dwellings varying in size from a hamlet to a city. In some countries this will be a division of the country with a mayor.<br />
* ''' Tier 4 ''': The locality people identify themselves with. This further classifies tier 3. Examples would include a neighbourhood within a town or city, or a village or hamlet on the outskirts of a town or city.<br />
* ''' Tier 5 ''': Street or block, so the lowest division needed for postal information.<br />
<br />
Tiers 3, 4, and 5 look quite consistent between countries so far. - NH<br />
<br />
Comment (DB)<br />
* UK: the Church Parish field we have at present may be redundant for current places but it's often the only information given in early historical records. This may also be true outside the UK.<br />
<br />
<br />
<br />
We would need a country table. This would hold the field definitions for each country including the field names, 'not used' flags, and which fields should be used in the place tree view. <br />
<br />
This data could then be used to dynamically create fields in the place editor, place filter and place tree view.<br />
<br />
Suggestion (BM)<br />
* we should not work with 'not used' flags. Eg, some people in Wales might want to enter it. A not used flag would make it impossible. In the USA, people from Clairemont [http://en.wikipedia.org/wiki/Clairemont,_San_Diego,_California] might like to indicate that, however it is a neighbourhood. Instead I would suggest perhaps a address format default. For UK this would be I suppose:<br />
Street<br />
Locality<br />
City<br />
County<br />
Post Code<br />
Country<br />
: for Belgium this format would be<br />
Country<br />
ZIP Locality (City)<br />
street<br />
: with a format field and people seeing this format, they will understand how they are supposed to enter the place information (note that if Locality equals city it obviously must not be repeated.<br />
<br />
Your example of Clairemont is exactly what I intended the Locality field for. Its use is not limited to the UK. - NH<br />
<br />
'''Questions and Design Decisions'''<br />
* Do we need 2 or 3 tiers between the level with a mayor and the country? We only take 2 tiers. Most countries have more than 2 tiers, but they have little importance for the inhabitants or genealogy. What about Feature Request 4231?<br />
* Many countries have different sub-levels depending on the country. Yes, but Gramps is not a place storing application. In Countries like China you have province or autonomous region or .. as Tier 1. We can only provide one label, the users must himself understand that a locality in an autonomous region should put the name of the region in the Tier 1 (Labeled province) field. Or we could make the label read "Province/Region" if appropriate.<br />
<br />
'''Issues specific to the UK'''<br />
* When entering data into the country field there are a few possibilities. "UK" could be used as the country, or one of the constituent countries may be used (England, Wales, Scotland, Northern Ireland). Other terms such as GB, Britain or British Isles may also be used. A thread on the mailing list discussed this [http://gramps.1791082.n4.nabble.com/How-to-imput-UK-address-td2283137.html] and three different methods are used at the moment (UK, GB and constituent countries).<br />
* If constituent countries are used in the country field then the state field will not be used.<br />
* If "UK" or "GB" is used in the country field then the state field may optionally be used to qualify the constituent country.<br />
* Questions are often raised about how to record London addresses. At the moment the county field could be used to store "Greater London", "London", or a historic county for the London borough. The city field could be used to store "London" or the name of the London borough. The new Locality field may be useful to record the London borough.<br />
* When we upgrade the database we need to take into account the different possible values in the country field.<br />
<br />
=== Define one ideal way of working with alternative place ===<br />
Physical places can have more than one name and can move between administrative regions over time. The following list gives examples of why places need alternate names:<br />
* Places can change their name over time.<br />
* In countries where more than one language is spoken the place may have different names in different languages.<br />
* Multiple names for a place may exist where there are variant spellings for the place name.<br />
* Different names may be used for political reasons.<br />
For genealogical purposes it is important to record the place name as it appears in the source material. We could define alternative places with a date span. There may be one or more alternative places within a given date span.<br />
<br />
=== Improve the place tree view ===<br />
At present the place tree uses a three level hierarchy of Country, State and County.<br />
<br />
For some countries the State field is not relevant - for example in the UK. In this case it is more useful to display a Country and County or Country, County and City hierarchy.<br />
<br />
Countries also use different descriptions for the their administrative regions. We could change the column headings according to the country displayed. This would require a countries table in the database. We could also restrict the view to displaying only one country at a time.<br />
<br />
=== Improve data entry in the Place editor ===<br />
We could use drop-down lists in the place editor to allow the user to select values for each of the hierarchical fields. The data could come from data already in the database or we could consider building up a gazetteer for Gramps.<br />
<br />
Suggestion (BM):<br />
* Country is a GrampsType field, with known countries predefined. This gives us translated countries.<br />
* based on country, the normal divisions are set bold. All divisions can be entered however<br />
* Translation of labels is based on country, with fallback to the general. A Tier will have different translations depending on the country it is in. However, we must be carefull not to translate everything before Gramps can start up. Eg, we define, COUNTY= _('County), USA = (STATE, None, COUNTY, ...), where None is used to indicate to use the general name of the field, and this long list of countries is not kept in memory but constructed when a county is needed. <br />
<br />
The place editor could be made clearer if the hierarchical fields were placed together in the editor window.<br />
<br />
== Motivation ==<br />
Time and again users pose questions on improving the place structure of Gramps. This GEPS is about defining a new improved way of handling place, keeping backward compatibility with GEDCOM/present Gramps.<br />
<br />
Many things are also not well designed, in that Gramps allows the user to do as he likes, without guiding the user to a good way of storing place data. (this statement is disputed, see [[Talk:GEPS 006: Better Place handling|discussion]])<br />
<br />
== Some ideas ==<br />
<br />
* [[Geonames]]<br />
* [http://wiki-en.genealogy.net/wiki/Gedcom_5.5EL#High-Level-Entitiy_.22Location.22 Gedcom 5.5EL]<br />
* An internal [[place database]]<br />
<br />
== References ==<br />
<br />
Some relevant bug tracker entries:<br />
<br />
* {{bug|1862}} Place Guessing Feature Request<br />
* {{bug|2196}} Some changes to the Places viewer would be helpful<br />
* {{bug|2311}} Implement a place database ...<br />
* {{bug|4230}} Places tree view gives confusing place names<br />
* {{bug|4231}} Add Municipality to places data<br />
* {{bug|4510}} Additional Suggestion<br />
* {{bug|4712}} Eliminate case-sensitivy when searching city names in place completion tool<br />
* {{bug|4714}} Superwide resize after adding lat/lon<br />
<br />
[[Category:GEPS|B]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=37754Addon:Place completion tool2012-06-25T12:23:22Z<p>DouginIT: </p>
<hr />
<div>{{out of date|page needs to be reworked and maybe split}}<br />
<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There are versions for 3.1, 3.2, 3.3 and 3.4.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go.<br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is useful.<br />
*Construction of a uniform title/description field, from the data in the place object.<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download data files of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need! If the download is a compressed zip file, you will need to extract the data file before you can use it.<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so e.g. municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
<br />
<br />
This is for advanced users who know how to use [http://en.wikipedia.org/wiki/Regular_expression regular expressions]. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
<br />
=== Parse title details ===<br />
<br />
<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
<br />
'''NOTE: take care when pasting a Regex (for example, after testing in a regex editor) into the Parse title details field'''<br />
<br />
'''Pasting adds redundant spaces before or after the Regex that will prevent it working properly in the Place Completion Tool'''<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you still use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
If you still use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz].<br />
<br />
If you still use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
Extract the three files that are in the download. Put the .glade and .py files in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon], use the [[3.2_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.3 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps33/download/PlaceCompletion.addon.tgz this addon], use the [[3.3_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.4 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps34/download/PlaceCompletion.addon.tgz this addon], use the [[3.4_Addons|automatic installation]].<br />
<br />
<br />
<br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]<br />
[[Category:Tools]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=37753Addon:Place completion tool2012-06-25T12:08:23Z<p>DouginIT: /* Advanced usage */</p>
<hr />
<div>{{out of date|page needs to be reworked and maybe split}}<br />
<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.1.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go.<br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is useful.<br />
*Construction of a uniform title/description field, from the data in the place object.<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download data files of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need! If the download is a compressed zip file, you will need to extract the data file before you can use it.<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so e.g. municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
<br />
<br />
This is for advanced users who know how to use [http://en.wikipedia.org/wiki/Regular_expression regular expressions]. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
<br />
=== Parse title details ===<br />
<br />
<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
<br />
'''NOTE: take care when pasting a Regex (for example, after testing in a regex editor) into the Parse title details field'''<br />
<br />
'''Pasting adds redundant spaces before or after the Regex that will prevent it working properly in the Place Completion Tool'''<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you still use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
If you still use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz].<br />
<br />
If you still use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
Extract the three files that are in the download. Put the .glade and .py files in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon], use the [[3.2_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.3 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps33/download/PlaceCompletion.addon.tgz this addon], use the [[3.3_Addons|automatic installation]].<br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]<br />
[[Category:Tools]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=37700Addon:Place completion tool2012-06-16T10:45:57Z<p>DouginIT: /* Advanced usage */</p>
<hr />
<div>{{out of date|page needs to be reworked and maybe split}}<br />
<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.1.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go.<br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is useful.<br />
*Construction of a uniform title/description field, from the data in the place object.<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download data files of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need! If the download is a compressed zip file, you will need to extract the data file before you can use it.<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so e.g. municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
<br />
'''''NOTE: At present (Gramps 3.4) regular expression parsing is no longer functional, only the pre-defined option 'Change title into''''''<br />
<br />
This is for advanced users who know how to use [http://en.wikipedia.org/wiki/Regular_expression regular expressions]. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
<br />
=== Parse title details ===<br />
'''''This entire section should be ignored until the parsing option receives developer attention'''''<br />
<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
'''''End of Parse Title Details section awaiting attention'''''<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you still use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
If you still use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz].<br />
<br />
If you still use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
Extract the three files that are in the download. Put the .glade and .py files in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon], use the [[3.2_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.3 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps33/download/PlaceCompletion.addon.tgz this addon], use the [[3.3_Addons|automatic installation]].<br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]<br />
[[Category:Tools]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=37335Addon:Place completion tool2012-05-28T10:51:15Z<p>DouginIT: /* Parse title details */</p>
<hr />
<div>{{out of date|page needs to be reworked and maybe split}}<br />
<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.1.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go.<br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is useful.<br />
*Construction of a uniform title/description field, from the data in the place object.<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download data files of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need! If the download is a compressed zip file, you will need to extract the data file before you can use it.<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so e.g. municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
This is for advanced users who know how to use [http://en.wikipedia.org/wiki/Regular_expression regular expressions]. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
<br />
=== Parse title details ===<br />
'''''This option needs developer attention. Recent Gramps versions have changed the behaviour of regular expression parsing and it no longer works'''''<br />
<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
'''''End of Parse Title Details section needing attention'''''<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you still use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
If you still use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz].<br />
<br />
If you still use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
Extract the three files that are in the download. Put the .glade and .py files in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon], use the [[3.2_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.3 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps33/download/PlaceCompletion.addon.tgz this addon], use the [[3.3_Addons|automatic installation]].<br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]<br />
[[Category:Tools]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=37161Addon:Place completion tool2012-05-21T13:15:59Z<p>DouginIT: /* Parse title details */</p>
<hr />
<div>{{out of date|page needs to be reworked and maybe split}}<br />
<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.1.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go.<br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is useful.<br />
*Construction of a uniform title/description field, from the data in the place object.<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download data files of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need! If the download is a compressed zip file, you will need to extract the data file before you can use it.<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so e.g. municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
This is for advanced users who know how to use [http://en.wikipedia.org/wiki/Regular_expression regular expressions]. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
<br />
=== Parse title details ===<br />
'''''This section is awaiting revision. The regex examples below no longer work correctly in Gramps 3.3.1'''''<br />
<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
'''''End of Parse Title Details section needing revision'''''<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you still use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
If you still use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz].<br />
<br />
If you still use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
Extract the three files that are in the download. Put the .glade and .py files in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon], use the [[3.2_Addons|automatic installation]].<br />
<br />
If you use Gramps 3.3 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps33/download/PlaceCompletion.addon.tgz this addon], use the [[3.3_Addons|automatic installation]].<br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]<br />
[[Category:Tools]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.4_Wiki_Manual_-_Filters&diff=36905Gramps 3.4 Wiki Manual - Filters2012-04-29T08:42:38Z<p>DouginIT: /* Common variations of a surname */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in Gramps. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
== Filter vs. Search ==<br />
<br />
There are two ways to find data in Gramps: Search and Filter. Search uses the topbar above a listing View (such as People, Families, etc). Filter can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. The top bar Search only appears when the entire sidebar is closed. You can close/open the Sidebar/bottombar through menu -> View.<br />
<br />
Search and Filter work completely differently and it is useful to understand these differences:<br />
<br />
''Search'' - the topbar search looks through the database as it appears in the rows and columns on the screen. For example, if you have the Name Display in Preferences set to show "Surname, Given" then you can match names such as "Smith, J" and all of the correct rows will match. If you change the way that names are displayed (in Preferences) then you can match that format (for example, "John Smith"). The Search functionality is probably the one you want to use most of the time, as it is most straightforward, but has some limitations (see below).<br />
<br />
''Filter'' - Filters use a more complex system. It is not limited to what you see on the screen, but looks at the actual data, rather than just what is showing in the View. The name Filter will try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name---you can't match the given field and surname field in the same name. You can match surname, but not surname and given in the same name. For example, if you Filter on "John", you will get matches of people with firstname "John" but also those with surname "Johnson". You just can't filter on combinations of first and lastnames).<br />
<br />
Filters can be created and controlled from the menu (menu -> Edit -> Filter Editor), or from a special sidebar/bottombar Gramplet. The Filter Gramplets allow for some quick filters that are similar to the topbar Search, but all Filters follow the distinction outlined here.<br />
<br />
Some additional points:<br />
<br />
* The Filter will search alternative names too; Search only looks in the primary name (the one showing). That is why if you do a Filter on "Smith" you might see people listed that don't appear to match. But if you edit that person's details, you might see that they have an alternate name containing "smith".<br />
* The Filter allows "regular expressions". So you can find all of the names that start with "B" and end in "ship": "B.*ship". You can't do that with the top bar Search.<br />
* The Search will only match what is visible. If a name or text is too big to see in listing below topbar, then you won't find it. This is something to keep in mind when Searching through Notes. Best to use Filter for notes and other long text fields.<br />
* All Filters use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp".<br />
<br />
You can find more details about making filters in [[Example filters]].<br />
<br />
The rest of this page details the Filter functionality.<br />
<br />
== Regular Expressions ==<br />
<br />
Regular Expressions are a quick and powerful way to describe text that matches a pattern and we use these in Filters. You must have the '''[ ] Use regular expressions''' option checked.<br />
<br />
For example, if you were looking for a surname that started with a "B", and ended with "ship" then you could use regular expressions to describe that pattern. That would be '''^B.*ship''':<br />
<br />
* The '''^B''' indicates text that starts with B<br />
* The '''.''' indicates any single character (letter, number, or anything)<br />
* The '''*''' indicates zero or more of the previous (in this case, any single character)<br />
* The '''ship''' matches the exact letters s, h, i, p in that order.<br />
<br />
Regular expressions are quite powerful, and there are many options. We use the Python Regular Expression system, and we will document that here. In addition, you can use any Python Regular Expression resource.<br />
<br />
''whitespace'' - The term "whitespace" is used below to mean one or more character that you don't see. For example, whitespace includes tabs, spaces, and newlines.<br />
<br />
There are some characters that have special meaning with regular expressions. They are:<br />
<br />
. ^ $ * + ? { } [ ] \ | ( )<br />
<br />
They can be used as described:<br />
<br />
* '.' matches any character (letter, number, or other)<br />
* '^' matches beginning of text<br />
* '$' matches end of text<br />
* '*' matches zero or more of the previous item<br />
* '+' matches one or more of the previous item<br />
* '?' matches zero or one of the previous item (makes it optional)<br />
* '{' - defines a number of matches<br />
* '}' - ends number of matches<br />
* '[' - beginning of set<br />
* ']' - end of set<br />
* '\' - next character is special sequence<br />
* '|' - or<br />
* '(' - beginning of a group<br />
* ')' - ending of a group<br />
<br />
Some of the special sequences beginning with '\' represent predefined sets of characters that are often useful, such as the set of digits, the set of letters, or the set of anything that isn't whitespace. The following predefined special sequences are a subset of those available.<br />
<br />
* \d Matches any decimal digit; this is equivalent to the class [0-9].<br />
* \D Matches any non-digit character; this is equivalent to the class [^0-9].<br />
* \s Matches any whitespace character; this is equivalent to the class [ \t\n\r\f\v].<br />
* \S Matches any non-whitespace character; this is equivalent to the class [^ \t\n\r\f\v].<br />
* \w Matches any alphanumeric character; this is equivalent to the class [a-zA-Z0-9_].<br />
* \W Matches any non-alphanumeric character; this is equivalent to the class [^a-zA-Z0-9_].<br />
<br />
The most complicated repeated qualifier is {m,n}, where m and n are decimal integers. This qualifier means there must be at least m repetitions, and at most n.<br />
<br />
=== Groups and Sets ===<br />
<br />
Groups are marked by the '(', ')' metacharacters. '(' and ')' have much the same meaning as they do in mathematical expressions; they group together the expressions contained inside them, and you can repeat the contents of a group with a repeating qualifier, such as *, +, ?, or {m,n}. For example, (ab)* will match zero or more repetitions of ab.<br />
<br />
Sets are marked by the '[' and ']' metacharacters.<br />
<br />
You can think of groups as a list of alternatives separated by the '|' metacharacter, where each alternative consists of one, several or zero characters and sets as a list of alternatives where each alternative is a single character.<br />
<br />
=== Examples ===<br />
<br />
* '''^B.*ship$''' - matches all text that starts with a 'B', followed by anything, ending with 'ship'.<br />
** matches: '''Blankenship''', '''Blueship''', '''Beeship'''<br />
** does not match: '''Blankenships'''<br />
* '''^B.*ship''' - matches all text that starts with a 'B', followed by anything, followed by 'ship' (could be followed by more).<br />
** matches: '''Blankenship''', '''Blankenships''', '''Blueship''', '''Blueshipman''', '''Beeship''', '''Beeshipness'''<br />
** does not match: '''Blankenschips'''<br />
<br />
===='''Common variations of a surname'''====<br />
<br />
<br />
<br />
<br />
*'''example 1:''' <br />
<br />
Erikson<br />
Eriksson<br />
Ericson<br />
Ericsson<br />
Erickson<br />
Ericksson<br />
Erichson<br />
Erichsson<br />
<br />
are matched by the expression<br />
'''Eri(ch|ck|k|c)(ss|s)on'''<br />
<br />
<br />
*'''explanation''':<br />
<br />
'''Eri''' = Eri<br />
<br />
'''(ch|ck|k|c)''' = group matching '''ch''', '''ck''', '''k''' or '''c'''. It tries to make the longest match first<br />
<br />
'''(ss|s)''' = group matching '''ss''' or '''s'''. It tries to make the longest match first<br />
<br />
'''on''' = on<br />
<br />
<br />
<br />
<br />
*'''example 2:'''<br />
<br />
Bainbricke<br />
Bainbridge<br />
Bainbrig<br />
Bainbrigg<br />
Bambridge<br />
Banbrig<br />
Banbrige<br />
Baynbrige<br />
<br />
are matched by the expression<br />
<br />
'''Ba(in|yn|m|n)bri(dge|cke|g(g|e|))'''<br />
<br />
<br />
*'''explanation:'''<br />
<br />
'''Ba''' = Ba<br />
<br />
'''(in|yn|m|n)''' = group matching '''in''', '''yn''', '''m''' or '''n'''. It tries to make the longest match first.<br />
<br />
'''bri''' = bri<br />
<br />
'''(dge|cke|g(g|e|))''' = group matching '''dge''', '''cke''' or ('''g''' with '''g''', '''g''' with '''e''' or '''g''' with nothing)<br />
<br />
<br />
<br />
<br />
*'''example 3:'''<br />
<br />
nairaud<br />
nairault<br />
naireaud<br />
nayrault<br />
nesrau <br />
nesrault<br />
nesreau<br />
nesreaud<br />
noirau<br />
noiraud<br />
noirauld<br />
noirault<br />
noiraut<br />
noiraux<br />
noireau<br />
noireaud<br />
noireault<br />
noireaut<br />
noirraux<br />
noirreau<br />
noirreaud<br />
nouarault<br />
noyraud<br />
noyrault <br />
<br />
are matched by the expression<br />
<br />
'''n(es|oua|oai|o[iya]|a[iy])r(r|)(on|((e|)au(x|t|d|lt|)))'''<br />
<br />
<br />
*'''explanation:'''<br />
<br />
'''n''' = n<br />
<br />
'''(es|oua|oai|set1|set2)''' = group matching '''es''', '''oua''', '''oai''', '''set1''' or '''set2'''<br />
<br />
'''set1''' is '''o[iya]''' = set matching '''o''' AND '''i''', '''y''' or '''a'''. In other words '''oi''', '''oy''' or '''oa'''<br />
<br />
'''set2''' is '''a[iy]''' = set matching '''a''' AND '''i''' or '''y'''. In other words '''ai''' or '''ay'''<br />
<br />
'''r''' = r<br />
<br />
'''(r|)''' = group matching '''r''' or nothing<br />
<br />
'''(on|(subgroup1)''' = group matching '''on''' or '''subgroup1'''.<br />
<br />
'''subgroup1''' is group matching ('''subgroup2 au subgroup3''')<br />
<br />
'''subgroup2''' is '''(e|)''' = group matching '''e''' or nothing<br />
<br />
'''au''' = au<br />
<br />
'''subgroup3''' is '''(x|t|d|lt)''' = group matching '''x''', '''t''', '''d''' or '''lt'''<br />
<br />
<br />
<br />
<br />
====testing regular expressions====<br />
<br />
Regular Expression testers can be found online through Google. http://gskinner.com/RegExr/ is simple and convenient<br />
<br />
==Custom Filter Editor==<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
{{man warn|Custom rules migration|To avoid unwanted effects after a major upgrades of Gramps (eg, from version 3.2.x to 3.4.x), if required, you can manually copy your ''custom_filter.xml'' from [[GRAMPS User Directory]] to ''gramps_version_number''.}}<br />
<br />
[[Image:Cfe-df.png|right|thumb|350px|Fig.11.1 Define filter]]<br />
<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of Gramps.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the toolbar {{man button|Apply and close}} button.}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Define filter}} dialog (See Fig.11.1)<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
{{-}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Add Rule}} dialog (See Fig.11.2):<br />
<br />
[[Image:Cfe-ar.png|right|thumb|350px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br />
{{-}}<br />
<br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
<br />
=== Persons-, Relationship-, and Pedigree View===<br />
<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
[[Category:Documentation]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.4_Wiki_Manual_-_Filters&diff=36899Gramps 3.4 Wiki Manual - Filters2012-04-28T15:07:58Z<p>DouginIT: /* Common variations of a surname */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in Gramps. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
== Filter vs. Search ==<br />
<br />
There are two ways to find data in Gramps: Search and Filter. Search uses the topbar above a listing View (such as People, Families, etc). Filter can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. The top bar Search only appears when the entire sidebar is closed. You can close/open the Sidebar/bottombar through menu -> View.<br />
<br />
Search and Filter work completely differently and it is useful to understand these differences:<br />
<br />
''Search'' - the topbar search looks through the database as it appears in the rows and columns on the screen. For example, if you have the Name Display in Preferences set to show "Surname, Given" then you can match names such as "Smith, J" and all of the correct rows will match. If you change the way that names are displayed (in Preferences) then you can match that format (for example, "John Smith"). The Search functionality is probably the one you want to use most of the time, as it is most straightforward, but has some limitations (see below).<br />
<br />
''Filter'' - Filters use a more complex system. It is not limited to what you see on the screen, but looks at the actual data, rather than just what is showing in the View. The name Filter will try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name---you can't match the given field and surname field in the same name. You can match surname, but not surname and given in the same name. For example, if you Filter on "John", you will get matches of people with firstname "John" but also those with surname "Johnson". You just can't filter on combinations of first and lastnames).<br />
<br />
Filters can be created and controlled from the menu (menu -> Edit -> Filter Editor), or from a special sidebar/bottombar Gramplet. The Filter Gramplets allow for some quick filters that are similar to the topbar Search, but all Filters follow the distinction outlined here.<br />
<br />
Some additional points:<br />
<br />
* The Filter will search alternative names too; Search only looks in the primary name (the one showing). That is why if you do a Filter on "Smith" you might see people listed that don't appear to match. But if you edit that person's details, you might see that they have an alternate name containing "smith".<br />
* The Filter allows "regular expressions". So you can find all of the names that start with "B" and end in "ship": "B.*ship". You can't do that with the top bar Search.<br />
* The Search will only match what is visible. If a name or text is too big to see in listing below topbar, then you won't find it. This is something to keep in mind when Searching through Notes. Best to use Filter for notes and other long text fields.<br />
* All Filters use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp".<br />
<br />
You can find more details about making filters in [[Example filters]].<br />
<br />
The rest of this page details the Filter functionality.<br />
<br />
== Regular Expressions ==<br />
<br />
Regular Expressions are a quick and powerful way to describe text that matches a pattern and we use these in Filters. You must have the '''[ ] Use regular expressions''' option checked.<br />
<br />
For example, if you were looking for a surname that started with a "B", and ended with "ship" then you could use regular expressions to describe that pattern. That would be '''^B.*ship''':<br />
<br />
* The '''^B''' indicates text that starts with B<br />
* The '''.''' indicates any single character (letter, number, or anything)<br />
* The '''*''' indicates zero or more of the previous (in this case, any single character)<br />
* The '''ship''' matches the exact letters s, h, i, p in that order.<br />
<br />
Regular expressions are quite powerful, and there are many options. We use the Python Regular Expression system, and we will document that here. In addition, you can use any Python Regular Expression resource.<br />
<br />
''whitespace'' - The term "whitespace" is used below to mean one or more character that you don't see. For example, whitespace includes tabs, spaces, and newlines.<br />
<br />
There are some characters that have special meaning with regular expressions. They are:<br />
<br />
. ^ $ * + ? { } [ ] \ | ( )<br />
<br />
They can be used as described:<br />
<br />
* '.' matches any character (letter, number, or other)<br />
* '^' matches beginning of text<br />
* '$' matches end of text<br />
* '*' matches zero or more of the previous item<br />
* '+' matches one or more of the previous item<br />
* '?' matches zero or one of the previous item (makes it optional)<br />
* '{' - defines a number of matches<br />
* '}' - ends number of matches<br />
* '[' - beginning of set<br />
* ']' - end of set<br />
* '\' - next character is special sequence<br />
* '|' - or<br />
* '(' - beginning of a group<br />
* ')' - ending of a group<br />
<br />
Some of the special sequences beginning with '\' represent predefined sets of characters that are often useful, such as the set of digits, the set of letters, or the set of anything that isn't whitespace. The following predefined special sequences are a subset of those available.<br />
<br />
* \d Matches any decimal digit; this is equivalent to the class [0-9].<br />
* \D Matches any non-digit character; this is equivalent to the class [^0-9].<br />
* \s Matches any whitespace character; this is equivalent to the class [ \t\n\r\f\v].<br />
* \S Matches any non-whitespace character; this is equivalent to the class [^ \t\n\r\f\v].<br />
* \w Matches any alphanumeric character; this is equivalent to the class [a-zA-Z0-9_].<br />
* \W Matches any non-alphanumeric character; this is equivalent to the class [^a-zA-Z0-9_].<br />
<br />
The most complicated repeated qualifier is {m,n}, where m and n are decimal integers. This qualifier means there must be at least m repetitions, and at most n.<br />
<br />
=== Groups and Sets ===<br />
<br />
Groups are marked by the '(', ')' metacharacters. '(' and ')' have much the same meaning as they do in mathematical expressions; they group together the expressions contained inside them, and you can repeat the contents of a group with a repeating qualifier, such as *, +, ?, or {m,n}. For example, (ab)* will match zero or more repetitions of ab.<br />
<br />
Sets are marked by the '[' and ']' metacharacters.<br />
<br />
You can think of groups as a list of alternatives separated by the '|' metacharacter, where each alternative consists of one, several or zero characters and sets as a list of alternatives where each alternative is a single character.<br />
<br />
=== Examples ===<br />
<br />
* '''^B.*ship$''' - matches all text that starts with a 'B', followed by anything, ending with 'ship'.<br />
** matches: '''Blankenship''', '''Blueship''', '''Beeship'''<br />
** does not match: '''Blankenships'''<br />
* '''^B.*ship''' - matches all text that starts with a 'B', followed by anything, followed by 'ship' (could be followed by more).<br />
** matches: '''Blankenship''', '''Blankenships''', '''Blueship''', '''Blueshipman''', '''Beeship''', '''Beeshipness'''<br />
** does not match: '''Blankenschips'''<br />
<br />
===='''Common variations of a surname'''====<br />
<br />
*'''example 1:''' <br />
<br />
Erikson<br />
Eriksson<br />
Ericson<br />
Ericsson<br />
Erickson<br />
Ericksson<br />
Erichson<br />
Erichsson<br />
<br />
are matched by the expression<br />
'''Eri(ch|ck|k|c)(ss|s)on'''<br />
<br />
*'''explanation''':<br />
<br />
'''Eri''' = Eri<br />
<br />
'''(ch|ck|k|c)''' = group matching '''ch''', '''ck''', '''k''' or '''c'''. It tries to make the longest match first<br />
<br />
'''(ss|s)''' = group matching '''ss''' or '''s'''. It tries to make the longest match first<br />
<br />
'''on''' = on<br />
<br />
<br />
*'''example 2:'''<br />
<br />
Bainbricke<br />
Bainbridge<br />
Bainbrig<br />
Bainbrigg<br />
Bambridge<br />
Banbrig<br />
Banbrige<br />
Baynbrige<br />
<br />
are matched by the expression<br />
<br />
'''Ba(in|yn|m|n)bri(dge|cke|g(g|e|))'''<br />
<br />
*'''explanation:'''<br />
<br />
'''Ba''' = Ba<br />
<br />
'''(in|yn|m|n)''' = group matching '''in''', '''yn''', '''m''' or '''n'''. It tries to make the longest match first.<br />
<br />
'''bri''' = bri<br />
<br />
'''(dge|cke|g(g|e|))''' = group matching '''dge''', '''cke''' or ('''g''' with '''g''', '''g''' with '''e''' or '''g''' with nothing)<br />
<br />
<br />
*'''example 3:'''<br />
<br />
nairaud<br />
nairault<br />
naireaud<br />
nayrault<br />
nesrau <br />
nesrault<br />
nesreau<br />
nesreaud<br />
noirau<br />
noiraud<br />
noirauld<br />
noirault<br />
noiraut<br />
noiraux<br />
noireau<br />
noireaud<br />
noireault<br />
noireaut<br />
noirraux<br />
noirreau<br />
noirreaud<br />
nouarault<br />
noyraud<br />
noyrault <br />
<br />
are matched by the expression<br />
<br />
'''n(es|oua|oai|o[iya]|a[iy])r(r|)(on|((e|)au(x|t|d|lt|)))'''<br />
<br />
*'''explanation:'''<br />
<br />
'''n''' = n<br />
<br />
'''(es|oua|oai|set1|set2)''' = group matching '''es''', '''oua''', '''oai''', '''set1''' or '''set2'''<br />
<br />
'''set1''' is '''o[iya]''' = set matching '''o''' AND '''i''', '''y''' or '''a'''. In other words '''oi''', '''oy''' or '''oa'''<br />
<br />
'''set2''' is '''a[iy]''' = set matching '''a''' AND '''i''' or '''y'''. In other words '''ai''' or '''ay'''<br />
<br />
'''r''' = r<br />
<br />
'''(r|)''' = group matching '''r''' or nothing<br />
<br />
'''(on|(subgroup1)''' = group matching '''on''' or '''subgroup1'''.<br />
<br />
'''subgroup1''' is group matching ('''subgroup2 au subgroup3''')<br />
<br />
'''subgroup2''' is '''(e|)''' = group matching '''e''' or nothing<br />
<br />
'''au''' = au<br />
<br />
'''subgroup3''' is '''(x|t|d|lt)''' = group matching '''x''', '''t''', '''d''' or '''lt'''<br />
<br />
==Custom Filter Editor==<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
{{man warn|Custom rules migration|To avoid unwanted effects after a major upgrades of Gramps (eg, from version 3.2.x to 3.4.x), if required, you can manually copy your ''custom_filter.xml'' from [[GRAMPS User Directory]] to ''gramps_version_number''.}}<br />
<br />
[[Image:Cfe-df.png|right|thumb|350px|Fig.11.1 Define filter]]<br />
<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of Gramps.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the toolbar {{man button|Apply and close}} button.}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Define filter}} dialog (See Fig.11.1)<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
{{-}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Add Rule}} dialog (See Fig.11.2):<br />
<br />
[[Image:Cfe-ar.png|right|thumb|350px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br />
{{-}}<br />
<br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
<br />
=== Persons-, Relationship-, and Pedigree View===<br />
<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
[[Category:Documentation]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.4_Wiki_Manual_-_Filters&diff=36898Gramps 3.4 Wiki Manual - Filters2012-04-28T15:03:48Z<p>DouginIT: /* Examples */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in Gramps. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
== Filter vs. Search ==<br />
<br />
There are two ways to find data in Gramps: Search and Filter. Search uses the topbar above a listing View (such as People, Families, etc). Filter can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. The top bar Search only appears when the entire sidebar is closed. You can close/open the Sidebar/bottombar through menu -> View.<br />
<br />
Search and Filter work completely differently and it is useful to understand these differences:<br />
<br />
''Search'' - the topbar search looks through the database as it appears in the rows and columns on the screen. For example, if you have the Name Display in Preferences set to show "Surname, Given" then you can match names such as "Smith, J" and all of the correct rows will match. If you change the way that names are displayed (in Preferences) then you can match that format (for example, "John Smith"). The Search functionality is probably the one you want to use most of the time, as it is most straightforward, but has some limitations (see below).<br />
<br />
''Filter'' - Filters use a more complex system. It is not limited to what you see on the screen, but looks at the actual data, rather than just what is showing in the View. The name Filter will try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name---you can't match the given field and surname field in the same name. You can match surname, but not surname and given in the same name. For example, if you Filter on "John", you will get matches of people with firstname "John" but also those with surname "Johnson". You just can't filter on combinations of first and lastnames).<br />
<br />
Filters can be created and controlled from the menu (menu -> Edit -> Filter Editor), or from a special sidebar/bottombar Gramplet. The Filter Gramplets allow for some quick filters that are similar to the topbar Search, but all Filters follow the distinction outlined here.<br />
<br />
Some additional points:<br />
<br />
* The Filter will search alternative names too; Search only looks in the primary name (the one showing). That is why if you do a Filter on "Smith" you might see people listed that don't appear to match. But if you edit that person's details, you might see that they have an alternate name containing "smith".<br />
* The Filter allows "regular expressions". So you can find all of the names that start with "B" and end in "ship": "B.*ship". You can't do that with the top bar Search.<br />
* The Search will only match what is visible. If a name or text is too big to see in listing below topbar, then you won't find it. This is something to keep in mind when Searching through Notes. Best to use Filter for notes and other long text fields.<br />
* All Filters use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp".<br />
<br />
You can find more details about making filters in [[Example filters]].<br />
<br />
The rest of this page details the Filter functionality.<br />
<br />
== Regular Expressions ==<br />
<br />
Regular Expressions are a quick and powerful way to describe text that matches a pattern and we use these in Filters. You must have the '''[ ] Use regular expressions''' option checked.<br />
<br />
For example, if you were looking for a surname that started with a "B", and ended with "ship" then you could use regular expressions to describe that pattern. That would be '''^B.*ship''':<br />
<br />
* The '''^B''' indicates text that starts with B<br />
* The '''.''' indicates any single character (letter, number, or anything)<br />
* The '''*''' indicates zero or more of the previous (in this case, any single character)<br />
* The '''ship''' matches the exact letters s, h, i, p in that order.<br />
<br />
Regular expressions are quite powerful, and there are many options. We use the Python Regular Expression system, and we will document that here. In addition, you can use any Python Regular Expression resource.<br />
<br />
''whitespace'' - The term "whitespace" is used below to mean one or more character that you don't see. For example, whitespace includes tabs, spaces, and newlines.<br />
<br />
There are some characters that have special meaning with regular expressions. They are:<br />
<br />
. ^ $ * + ? { } [ ] \ | ( )<br />
<br />
They can be used as described:<br />
<br />
* '.' matches any character (letter, number, or other)<br />
* '^' matches beginning of text<br />
* '$' matches end of text<br />
* '*' matches zero or more of the previous item<br />
* '+' matches one or more of the previous item<br />
* '?' matches zero or one of the previous item (makes it optional)<br />
* '{' - defines a number of matches<br />
* '}' - ends number of matches<br />
* '[' - beginning of set<br />
* ']' - end of set<br />
* '\' - next character is special sequence<br />
* '|' - or<br />
* '(' - beginning of a group<br />
* ')' - ending of a group<br />
<br />
Some of the special sequences beginning with '\' represent predefined sets of characters that are often useful, such as the set of digits, the set of letters, or the set of anything that isn't whitespace. The following predefined special sequences are a subset of those available.<br />
<br />
* \d Matches any decimal digit; this is equivalent to the class [0-9].<br />
* \D Matches any non-digit character; this is equivalent to the class [^0-9].<br />
* \s Matches any whitespace character; this is equivalent to the class [ \t\n\r\f\v].<br />
* \S Matches any non-whitespace character; this is equivalent to the class [^ \t\n\r\f\v].<br />
* \w Matches any alphanumeric character; this is equivalent to the class [a-zA-Z0-9_].<br />
* \W Matches any non-alphanumeric character; this is equivalent to the class [^a-zA-Z0-9_].<br />
<br />
The most complicated repeated qualifier is {m,n}, where m and n are decimal integers. This qualifier means there must be at least m repetitions, and at most n.<br />
<br />
=== Groups and Sets ===<br />
<br />
Groups are marked by the '(', ')' metacharacters. '(' and ')' have much the same meaning as they do in mathematical expressions; they group together the expressions contained inside them, and you can repeat the contents of a group with a repeating qualifier, such as *, +, ?, or {m,n}. For example, (ab)* will match zero or more repetitions of ab.<br />
<br />
Sets are marked by the '[' and ']' metacharacters.<br />
<br />
You can think of groups as a list of alternatives separated by the '|' metacharacter, where each alternative consists of one, several or zero characters and sets as a list of alternatives where each alternative is a single character.<br />
<br />
=== Examples ===<br />
<br />
* '''^B.*ship$''' - matches all text that starts with a 'B', followed by anything, ending with 'ship'.<br />
** matches: '''Blankenship''', '''Blueship''', '''Beeship'''<br />
** does not match: '''Blankenships'''<br />
* '''^B.*ship''' - matches all text that starts with a 'B', followed by anything, followed by 'ship' (could be followed by more).<br />
** matches: '''Blankenship''', '''Blankenships''', '''Blueship''', '''Blueshipman''', '''Beeship''', '''Beeshipness'''<br />
** does not match: '''Blankenschips'''<br />
<br />
==='''Common variations of a surname'''===<br />
<br />
*'''example 1:''' <br />
<br />
Erikson<br />
Eriksson<br />
Ericson<br />
Ericsson<br />
Erickson<br />
Ericksson<br />
Erichson<br />
Erichsson<br />
<br />
are matched by the expression<br />
'''Eri(ch|ck|k|c)(ss|s)on'''<br />
<br />
*'''explanation''':<br />
<br />
'''Eri''' = Eri<br />
<br />
'''(ch|ck|k|c)''' = group matching '''ch''', '''ck''', '''k''' or '''c'''. It tries to make the longest match first<br />
<br />
'''(ss|s)''' = group matching '''ss''' or '''s'''. It tries to make the longest match first<br />
<br />
'''on''' = on<br />
<br />
<br />
*'''example 2:'''<br />
<br />
Bainbricke<br />
Bainbridge<br />
Bainbrig<br />
Bainbrigg<br />
Bambridge<br />
Banbrig<br />
Banbrige<br />
Baynbrige<br />
<br />
are matched by the expression<br />
<br />
'''Ba(in|yn|m|n)bri(dge|cke|g(g|e|))'''<br />
<br />
*'''explanation:'''<br />
<br />
'''Ba''' = Ba<br />
<br />
'''(in|yn|m|n)''' = group matching '''in''', '''yn''', '''m''' or '''n'''. It tries to make the longest match first.<br />
<br />
'''bri''' = bri<br />
<br />
'''(dge|cke|g(g|e|))''' = group matching '''dge''', '''cke''' or ('''g''' with '''g''', '''g''' with '''e''' or '''g''' with nothing)<br />
<br />
<br />
*'''example 3:'''<br />
<br />
nairaud<br />
nairault<br />
naireaud<br />
nayrault<br />
nesrau <br />
nesrault<br />
nesreau<br />
nesreaud<br />
noirau<br />
noiraud<br />
noirauld<br />
noirault<br />
noiraut<br />
noiraux<br />
noireau<br />
noireaud<br />
noireault<br />
noireaut<br />
noirraux<br />
noirreau<br />
noirreaud<br />
nouarault<br />
noyraud<br />
noyrault <br />
<br />
are matched by the expression<br />
<br />
'''n(es|oua|oai|o[iya]|a[iy])r(r|)(on|((e|)au(x|t|d|lt|)))'''<br />
<br />
*'''explanation:'''<br />
<br />
'''n''' = n<br />
<br />
'''(es|oua|oai|set1|set2)''' = group matching '''es''', '''oua''', '''oai''', '''set1''' or '''set2'''<br />
<br />
'''set1''' is '''o[iya]''' = set matching '''o''' AND '''i''', '''y''' or '''a'''. In other words '''oi''', '''oy''' or '''oa'''<br />
<br />
'''set2''' is '''a[iy]''' = set matching '''a''' AND '''i''' or '''y'''. In other words '''ai''' or '''ay'''<br />
<br />
'''r''' = r<br />
<br />
'''(r|)''' = group matching '''r''' or nothing<br />
<br />
'''(on|(subgroup1)''' = group matching '''on''' or '''subgroup1'''.<br />
<br />
'''subgroup1''' is group matching ('''subgroup2 au subgroup3''')<br />
<br />
'''subgroup2''' is '''(e|)''' = group matching '''e''' or nothing<br />
<br />
'''au''' = au<br />
<br />
'''subgroup3''' is '''(x|t|d|lt)''' = group matching '''x''', '''t''', '''d''' or '''lt'''<br />
<br />
==Custom Filter Editor==<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
{{man warn|Custom rules migration|To avoid unwanted effects after a major upgrades of Gramps (eg, from version 3.2.x to 3.4.x), if required, you can manually copy your ''custom_filter.xml'' from [[GRAMPS User Directory]] to ''gramps_version_number''.}}<br />
<br />
[[Image:Cfe-df.png|right|thumb|350px|Fig.11.1 Define filter]]<br />
<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of Gramps.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the toolbar {{man button|Apply and close}} button.}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Define filter}} dialog (See Fig.11.1)<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
{{-}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Add Rule}} dialog (See Fig.11.2):<br />
<br />
[[Image:Cfe-ar.png|right|thumb|350px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br />
{{-}}<br />
<br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
<br />
=== Persons-, Relationship-, and Pedigree View===<br />
<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
[[Category:Documentation]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.4_Wiki_Manual_-_Filters&diff=36897Gramps 3.4 Wiki Manual - Filters2012-04-28T13:36:35Z<p>DouginIT: /* Groups */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in Gramps. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
== Filter vs. Search ==<br />
<br />
There are two ways to find data in Gramps: Search and Filter. Search uses the topbar above a listing View (such as People, Families, etc). Filter can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. The top bar Search only appears when the entire sidebar is closed. You can close/open the Sidebar/bottombar through menu -> View.<br />
<br />
Search and Filter work completely differently and it is useful to understand these differences:<br />
<br />
''Search'' - the topbar search looks through the database as it appears in the rows and columns on the screen. For example, if you have the Name Display in Preferences set to show "Surname, Given" then you can match names such as "Smith, J" and all of the correct rows will match. If you change the way that names are displayed (in Preferences) then you can match that format (for example, "John Smith"). The Search functionality is probably the one you want to use most of the time, as it is most straightforward, but has some limitations (see below).<br />
<br />
''Filter'' - Filters use a more complex system. It is not limited to what you see on the screen, but looks at the actual data, rather than just what is showing in the View. The name Filter will try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name---you can't match the given field and surname field in the same name. You can match surname, but not surname and given in the same name. For example, if you Filter on "John", you will get matches of people with firstname "John" but also those with surname "Johnson". You just can't filter on combinations of first and lastnames).<br />
<br />
Filters can be created and controlled from the menu (menu -> Edit -> Filter Editor), or from a special sidebar/bottombar Gramplet. The Filter Gramplets allow for some quick filters that are similar to the topbar Search, but all Filters follow the distinction outlined here.<br />
<br />
Some additional points:<br />
<br />
* The Filter will search alternative names too; Search only looks in the primary name (the one showing). That is why if you do a Filter on "Smith" you might see people listed that don't appear to match. But if you edit that person's details, you might see that they have an alternate name containing "smith".<br />
* The Filter allows "regular expressions". So you can find all of the names that start with "B" and end in "ship": "B.*ship". You can't do that with the top bar Search.<br />
* The Search will only match what is visible. If a name or text is too big to see in listing below topbar, then you won't find it. This is something to keep in mind when Searching through Notes. Best to use Filter for notes and other long text fields.<br />
* All Filters use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp".<br />
<br />
You can find more details about making filters in [[Example filters]].<br />
<br />
The rest of this page details the Filter functionality.<br />
<br />
== Regular Expressions ==<br />
<br />
Regular Expressions are a quick and powerful way to describe text that matches a pattern and we use these in Filters. You must have the '''[ ] Use regular expressions''' option checked.<br />
<br />
For example, if you were looking for a surname that started with a "B", and ended with "ship" then you could use regular expressions to describe that pattern. That would be '''^B.*ship''':<br />
<br />
* The '''^B''' indicates text that starts with B<br />
* The '''.''' indicates any single character (letter, number, or anything)<br />
* The '''*''' indicates zero or more of the previous (in this case, any single character)<br />
* The '''ship''' matches the exact letters s, h, i, p in that order.<br />
<br />
Regular expressions are quite powerful, and there are many options. We use the Python Regular Expression system, and we will document that here. In addition, you can use any Python Regular Expression resource.<br />
<br />
''whitespace'' - The term "whitespace" is used below to mean one or more character that you don't see. For example, whitespace includes tabs, spaces, and newlines.<br />
<br />
There are some characters that have special meaning with regular expressions. They are:<br />
<br />
. ^ $ * + ? { } [ ] \ | ( )<br />
<br />
They can be used as described:<br />
<br />
* '.' matches any character (letter, number, or other)<br />
* '^' matches beginning of text<br />
* '$' matches end of text<br />
* '*' matches zero or more of the previous item<br />
* '+' matches one or more of the previous item<br />
* '?' matches zero or one of the previous item (makes it optional)<br />
* '{' - defines a number of matches<br />
* '}' - ends number of matches<br />
* '[' - beginning of set<br />
* ']' - end of set<br />
* '\' - next character is special sequence<br />
* '|' - or<br />
* '(' - beginning of a group<br />
* ')' - ending of a group<br />
<br />
Some of the special sequences beginning with '\' represent predefined sets of characters that are often useful, such as the set of digits, the set of letters, or the set of anything that isn't whitespace. The following predefined special sequences are a subset of those available.<br />
<br />
* \d Matches any decimal digit; this is equivalent to the class [0-9].<br />
* \D Matches any non-digit character; this is equivalent to the class [^0-9].<br />
* \s Matches any whitespace character; this is equivalent to the class [ \t\n\r\f\v].<br />
* \S Matches any non-whitespace character; this is equivalent to the class [^ \t\n\r\f\v].<br />
* \w Matches any alphanumeric character; this is equivalent to the class [a-zA-Z0-9_].<br />
* \W Matches any non-alphanumeric character; this is equivalent to the class [^a-zA-Z0-9_].<br />
<br />
The most complicated repeated qualifier is {m,n}, where m and n are decimal integers. This qualifier means there must be at least m repetitions, and at most n.<br />
<br />
=== Groups and Sets ===<br />
<br />
Groups are marked by the '(', ')' metacharacters. '(' and ')' have much the same meaning as they do in mathematical expressions; they group together the expressions contained inside them, and you can repeat the contents of a group with a repeating qualifier, such as *, +, ?, or {m,n}. For example, (ab)* will match zero or more repetitions of ab.<br />
<br />
Sets are marked by the '[' and ']' metacharacters.<br />
<br />
You can think of groups as a list of alternatives separated by the '|' metacharacter, where each alternative consists of one, several or zero characters and sets as a list of alternatives where each alternative is a single character.<br />
<br />
=== Examples ===<br />
<br />
* '''^B.*ship$''' - matches all text that starts with a 'B', followed by anything, ending with 'ship'.<br />
** matches: '''Blankenship''', '''Blueship''', '''Beeship'''<br />
** does not match: '''Blankenships'''<br />
* '''^B.*ship''' - matches all text that starts with a 'B', followed by anything, followed by 'ship' (could be followed by more).<br />
** matches: '''Blankenship''', '''Blankenships''', '''Blueship''', '''Blueshipman''', '''Beeship''', '''Beeshipness'''<br />
** does not match: '''Blankenschips'''<br />
<br />
==Custom Filter Editor==<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
{{man warn|Custom rules migration|To avoid unwanted effects after a major upgrades of Gramps (eg, from version 3.2.x to 3.4.x), if required, you can manually copy your ''custom_filter.xml'' from [[GRAMPS User Directory]] to ''gramps_version_number''.}}<br />
<br />
[[Image:Cfe-df.png|right|thumb|350px|Fig.11.1 Define filter]]<br />
<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of Gramps.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the toolbar {{man button|Apply and close}} button.}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Define filter}} dialog (See Fig.11.1)<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
{{-}}<br />
<br />
Clicking the toolbar {{man button|Add...}} button invokes the {{man label|Add Rule}} dialog (See Fig.11.2):<br />
<br />
[[Image:Cfe-ar.png|right|thumb|350px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br />
{{-}}<br />
<br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
<br />
=== Persons-, Relationship-, and Pedigree View===<br />
<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.4 Wiki Manual - Settings|Gramps 3.4 Wiki Manual - FAQ|3.4}}<br />
<br />
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}<br />
<br />
[[Category:Documentation]]<br />
[[Category:Filters]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.2_Wiki_Manual_-_Filters&diff=22960Gramps 3.2 Wiki Manual - Filters2010-05-18T09:02:42Z<p>DouginIT: /* Custom Filter Editor */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in GRAMPS. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.2 Wiki Manual - Settings|Gramps 3.2 Wiki Manual - FAQ|3.2}}<br />
<br />
{{languages|Gramps_3.2_Wiki_Manual_-_Filters}}<br />
<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
==Custom Filter Editor==<br />
[[Image:Cfe-df.png|right|thumb|250px|Fig.11.1 Define filter]]<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of GRAMPS.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the {{man button|Apply and close}} button.}}<br />
<br />
Clicking the {{man button|Add...}} button invokes the following {{man label|Define filter}} dialog:<br />
<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
<br clear="all" /><br />
Clicking the {{man button|Add...}} button invokes the following {{man label|Add Rule}} dialog:<br />
<br />
[[Image:Cfe-ar.png|right|thumb|250px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br clear="all" /><br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
=== Persons-, Relationship-, and Pedigree View===<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.2 Wiki Manual - Settings|Gramps 3.2 Wiki Manual - FAQ|3.2}}<br />
<br />
[[Category:Documentation]][[Category:Filters]]<br />
<br />
{{languages|Gramps_3.2_Wiki_Manual_-_Filters}}</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.3_Wiki_Manual_-_Filters&diff=26756Gramps 3.3 Wiki Manual - Filters2010-05-18T09:02:42Z<p>DouginIT: /* Custom Filter Editor */</p>
<hr />
<div>This appendix lists of all the filter rules currently defined in GRAMPS. Each of these rules is available for use when creating custom filters, see ''tools-util-cfe'' . The rules are listed by their categories.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
{{man index|Gramps 3.3 Wiki Manual - Settings|Gramps 3.3 Wiki Manual - FAQ|3.3}}<br />
<br />
{{languages|Gramps_3.3_Wiki_Manual_-_Filters}}<br />
<br />
<br />
You can carry out a considerable amount of selection of persons, events, places, etc., just using the Filter Sidebar in Person, Event, Place,etc. Views; but note, however, that the 'Use regular expressions' option '''only works with particular fields''' in each View.<br />
<br />
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.<br />
<br />
==Custom Filter Editor==<br />
[[Image:Cfe-df.png|right|thumb|250px|Fig.11.1 Define filter]]<br />
The Custom Filter Editor builds custom filters that can be used to select people included in reports, exports, and other tools and utilities. This is in fact a very powerful tool in genealogical analysis.<br />
<br />
When you launch it, the {{man label|User defined filters}} dialog appears that lists all the filters (if any) previously defined by you. Click the {{man button|Add...}} button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the {{man button|Edit...}} , {{man button|Test...}} , and {{man button|Delete}} buttons, respectively. All the filters displayed in the list will be automatically saved along with your database and will be available with subsequent sessions of GRAMPS.<br />
<br />
{{man note|1=Changes on filters |2=The changes made to the filters only take effect when you click the {{man button|Apply and close}} button.}}<br />
<br />
Clicking the {{man button|Add...}} button invokes the following {{man label|Define filter}} dialog:<br />
<br />
<br />
Type the name for your new filter into the {{man label|Name}} field.<br />
<br />
Enter any comment that would help you identify this filter in the future into the {{man label|Comment}} field. Add as many rules to the {{man label|Rule list}} as you would like to your filter using {{man button|Add...}} button. If the filter has more than one rule, select one of the {{man label|Rule operations}} . This allows you to choose whether all rules must apply, only one (either) rule must apply, or exactly one (either) rule must apply, in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.<br />
<br />
Check {{man label|Return values that do not match the filter rules}} to invert the filter rule. For example, inverting "has a common ancestor with I1" rule will match everyone who does not have a common ancestor with that person).<br />
<br />
<br clear="all" /><br />
Clicking the {{man button|Add...}} button invokes the following {{man label|Add Rule}} dialog:<br />
<br />
[[Image:Cfe-ar.png|right|thumb|250px|Fig.11.2 Add rule]]<br />
<br />
The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree. For detailed filter rule reference. Click on the arrows to fold/unfold the appropriate category. Select the rule from the tree by clicking on its name. The right-hand side displays the name, the description, and the values for the currently selected rule. Once you are satisfied with your rule selection and its values, click {{man button|OK}} to add this rule to the rule list of the currently edited filter. Clicking {{man button|Cancel}} will abort adding the rule to the filter.<br />
<br clear="all" /><br />
{{man tip| Tip |A filter you have already designed may be used as a rule for another filter. This gives you nearly infinite flexibility in custom-tailoring your selection criteria that can be later used in most of the exports, reports, and some of the tools (such as comparing individual events).}}<br />
<br />
== Which filters in which view? ==<br />
<br />
Depending on the used View, you will get a different set of filters. <br />
<br />
*; Gramplets: no filters available<br />
<br />
*; Persons View, Relationships View, and Pedigree View: [[#Ancestral_filters|Ancestral filters]], [[#Descendant_filters|Descendant filters]], [[#Family_filters|Family filters]], [[#General_filters|General filters]], [[#Event_filters|Event filters]], and [[#Relationship filters|Relationship Filters]].<br />
<br />
*; Events View, Sources View, Media view, Repositories View, and Notes View: only [[#General_filters|General filters]]. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.<br />
<br />
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].<br />
<br />
== General filters ==<br />
=== Persons-, Relationship-, and Pedigree View===<br />
This category includes the following general rules:<br />
<br />
*;Bookmarked People: Matches the people on the bookmark list.<br />
<br />
*;Default person: Matches the default person.<br />
<br />
*;Disconnected People: Matches people that have no family relationships to any other person in the database.<br />
<br />
*;Everyone: Matches everyone in the database.<br />
<br />
*;Females: Matches all females.<br />
<br />
*;Males: Matches all males.<br />
<br />
*;People having <count> notes: Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People having notes containing <regular expression>: Matches people whose notes contain text matching a regular expression. Values: Regular expression<br />
<br />
*;People having notes containing <substring>: Matches people whose notes contain text matching a substring. Values: Substring<br />
<br />
*;People marked private: Matches people that are indicated as private. <br />
<br />
*;People matching the <filter>: Matches people matched by the specied filter name. Values: Filter name. The specified filter name should be selected from the menu.<br />
<br />
*;People probably alive: Matches people without indications of death that are not too old. Values: On Date<br />
<br />
*;People with <id> matching regular expression: Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression<br />
<br />
<br />
*;People with <count> LDS events: Matches people with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> addresses: Matches people with a certain number of personal addresses. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> associations: Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> media: Matches people with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <count> source: Matches people with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to <br />
<br />
*;People with <marker>: Matches people with a marker of a particular value. Values: Marker type ' ', Complete, or ToDo.<br />
<br />
*;People with complete records: Matches all the people whose records are complete.<br />
<br />
*;People with incomplete names: Matches people with firstname or lastname missing.<br />
<br />
*;People with records containing <substring>: Matches people whose records contain text matching a substring. Values: Substring -- Case Sensitive or not -- Regular-Expression matching or not<br />
<br />
*;People with the <name>: Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name<br />
<br />
*;People with the source: Matches people who have a particular source. values: Source ID<br />
<br />
*;People with the family <attribute>: Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with the personal <attribute>: Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...<br />
<br />
*;People with unknown gender: Matches all people with unknown gender.<br />
<br />
*;People without a known birth date: Matches people without a known birthdate.<br />
<br />
*;People with <id>: Matches people with GRAMPS ID. The rule returns a match only if the ID is matched exactly. You can either enter the ID into a text entry field, or select an object from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;People changed after <date time>: Matches person records changed after a specified date-time (yyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.<br />
<br />
*;People with events matching the <event filter>: Matches persons who have events that match a certain event filter. Values: Event filter name.<br />
<br />
== Person filters ==<br />
<br />
*;Has Address: This rule matches people with a personal address.<br />
<br />
*;Has Association: This rule matches people with a personal association.<br />
<br />
*;Has Complete Record: This rule matches all people whose records are marked as complete. Currently, the completeness of personal information is marked manually, in the {{man label|Edit Person}} dialog.<br />
<br />
*;Has Name: This rule matches any person whose name matches the specified value in full or in part. For example, ''Marta Ericsdotter'' will be matched by the rule using the value "eric" for the family name. Separate values can be used for Given name, Family name, Suffix, and the Title. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's name. To use just one value, leave the other values empty.<br />
<br />
*;Is default person: This rule matches the default (home) person.<br />
<br />
*;Is a female: This rule matches any female person.<br />
<br />
*;Is a male: This rule matches any male person.<br />
<br />
*;People probably alive: This rule matches all people whose records do not indicate their death and who are not unreasonably old, judging by their available birth data and today's date.<br />
<br />
*;People with incomplete names: This rule matches all people with either given name or family name missing.<br />
<br />
*;People without a birth date: This rule matches people missing birth date.<br />
<br />
== Event filters ==<br />
<br />
This category includes the following rules that match people based on their recorded events:<br />
<br />
*;Has the birth: This rule matches people whose birth event matches specified values for Date, Place, and Description. The rule returns a match even if the person's birth event matches the value partially. The matching rules are case-insensitive. For example, anyone born in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's birth. To use just one value, leave the other values empty.<br />
<br />
*;Has the death: This rule matches people whose death event matches specified values for Date, Place, and Description. The rule returns a match even if the person's death event matches the value partially. The matching rules are case-insensitive. For example, anyone who died in Sweden will be matched by the rule using the value "sw" for the Place. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's death. To use just one value, leave the other values empty.<br />
<br />
*;Has the personal event: This rule matches people that have a personal event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who graduated in Sweden will be matched by the rule using the Graduation event and the value "sw" for the Place. The personal events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Has the family event: This rule matches people that have a family event matching specified values for the Event type, Date, Place, and Description. The rule returns a match even if the person's event matches the value partially. The matching rules are case-insensitive. For example, anyone who was married in Sweden will be matched by the rule using the Marriage event and the value "sw" for the Place. The family events should be selected from a pull-down menu. The rule returns a match if, and only if, all non-empty values are (partially) matched by the personal event. To use just one value, leave the other values empty.<br />
<br />
*;Witness: This rule matches people who are present as a witness in the event. If the personal or family event type is specified, only the events of this type will be searched.<br />
<br />
*;People with incomplete events: This rule matches people missing date or place in any personal event.<br />
<br />
*;Families with incomplete events: This rule matches people missing date or place in any family event of any of their families.<br />
<br />
== Family filters ==<br />
<br />
This category includes the following rules that match people based on their family relationships:<br />
<br />
*;People with children: This rule matches people with children.<br />
<br />
*;People with multiple marriage records: This rule matches people with more than one spouse.<br />
<br />
*;People with no marriage records: This rule matches people with no spouses.<br />
<br />
*;People who were adopted: This rule matches adopted people.<br />
<br />
*;Has the relationships: This rule matches people with a particular relationship. The relationship must match the type selected from the menu. Optionally, the number of relationships and the number of children can be specified. The rule returns a match if, and only if, all non-empty values are (partially) matched by a person's relationship. To use just one value, leave the other values empty.<br />
<br />
*;Is spouse of filter match: This rule matches people married to someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a child of filter match: This rule matches people for whom either parent is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a parent of filter match: This rule matches people whose child is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a sibling of filter match: This rule matches people whose sibling is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Ancestral filters ==<br />
<br />
This category includes the following rules that match people based on their ancestral relations to other people:<br />
<br />
*;Is an ancestor of: This rule matches people who are ancestors of the specified person. The Inclusive option determines whether the specified person should be considered his/her own ancestor (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button|Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is an ancestor of person at least N generations away: This rule matches people who are ancestors of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandparents, great-grandparents, etc., but not the parents of the specified person.<br />
<br />
*;Is an ancestor of person not more than N generations away: This rule matches people who are ancestors of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match parents and grandparents, but not great-grandparents, etc., of the specified person.<br />
<br />
*;Has a common ancestor with: This rule matches people who have common ancestors with the specified person.<br />
<br />
*;Has a common ancestor with filter match: This rule matches people who have common ancestors with someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is an ancestor of filter match: This rule matches people who are ancestors of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
== Descendant filters ==<br />
<br />
This category includes the following rules that match people based on their descendant relations to other people:<br />
<br />
*;Is a descendant of: This rule matches people who are descendants of the specified person. The Inclusive option determines whether the specified person should be considered his/her own descendant (useful for building reports). You can either enter the ID into a text entry field, or select a person from the list by clicking {{man button| Select...}} button. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
*;Is a descendant of person at least N generations away: This rule matches people who are descendants of the specified person and are at least N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match grandchildren, great-grandchildren, etc., but not the children of the specified person.<br />
<br />
*;Is a descendant of person not more than N generations away: This rule matches people who are descendants of the specified person and are no more than N generations away from that person in their lineage. For example, using this rule with the value of 2 for the number of generations will match children and grandchildren, but not great-grandchildren, etc., of the specified person.<br />
<br />
*;Is a descendant of filter match: This rule matches people who are descendants of someone who is matched by the specified filter. The specified filter name should be selected from the menu.<br />
<br />
*;Is a descendant family member of: This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.<br />
<br />
== Relationship filters ==<br />
<br />
This category includes the following rules that match people based on their mutual relationship:<br />
<br />
*;Relationship path between two people: This rule matches all ancestors of both people back to their common ancestors (if exist). This produces the "relationship path" between these two people, through their common ancestors. You can either enter the ID of each person into the appropriate text entry fields, or select people from the list by clicking their {{man button|Select...}} buttons. In the latter case, the ID will appear in the text field after the selection was made.<br />
<br />
== Miscellaneous filters ==<br />
<br />
This category includes the following rules which do not naturally fit into any of the above categories:<br />
<br />
*;Has the personal attribute: This rule matches people who have the personal attribute of the specified value. The specified personal attribute name should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has the family attribute: This rule matches people who have the family attribute of the specified value. The specified family attribute should be selected from the menu. The specified value should be typed into the text entry field.<br />
<br />
*;Has LDS: This rule matches people or families with a LDS event.<br />
<br />
{{man index|Gramps 3.3 Wiki Manual - Settings|Gramps 3.3 Wiki Manual - FAQ|3.3}}<br />
<br />
[[Category:Documentation]][[Category:Filters]]<br />
<br />
{{languages|Gramps_3.3_Wiki_Manual_-_Filters}}</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_People_Category_screenshots&diff=22959Gramps People Category screenshots2010-05-18T08:34:44Z<p>DouginIT: /* Main window, People with filter sidebar */</p>
<hr />
<div>{{languages}}<br />
__TOC__<br />
== Main window, People ==<br />
This screenshot shows the main window in GRAMPS, displaying the Person (People) View. <br />
<br />
This view shows all people in the database, displayed in a tree and grouped by family name. The view may be switched to other views by selecting one of the buttons on the lefthand side of the screen.<br />
<br />
[[Image:Mainwin.png|Main window (Person View)]]<br />
<br />
== Main window, People with filter sidebar ==<br />
This screenshot shows the same view, but with the sidebar filter enabled. The filter allows you to control which people in the display are visible in the display.<br />
<br />
[[Image:Side-filt.png|Main window with the sidebar filter enabled]]<br />
<br />
[[Category:screenshots]]<br />
<br />
NOTE: 'Use regular expressions' only works on '''some''' fields</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=22519Addon:Place completion tool2010-04-11T08:56:39Z<p>DouginIT: /* Parse title details */</p>
<hr />
<div>A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.1.x, as well as an old version that works with GRAMPS version 3.0.x or 2.2.5+ ! [[Place_completion_tool#Download|Download]].<br />
<br />
[[Category:Plugins]]<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go. Eg you give a <br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.<br />
*Construction of a uniform title/description field, from the data in the place object<br />
<br />
== Design specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1. Selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries ===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced usage ==<br />
This is for advanced users only knowing regular expressions. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
=== Parse title details ===<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
'''Example 1'''<br />
<br />
Some French Place Titles take the form of 5 strings (Town, a numeric Postal Code, Department, Region, Country)<br />
<br />
e.g. Avignon,84000,Vaucluse,Provence-Cote-d'Azur,FRANCE,<br />
<br />
where some fields may be missing e.g. Woerth,,,Alsace,FRANCE,<br />
<br />
the regex:<br />
\s*(?P<city>[^,]+)[,]\s*(?P<zip>\d*)[,](?P<county>[^,]*)[,](?P<state>[^,]*)[,](?P<country>[^,]*)[,]*$ <br />
<br />
treating the comma character as an end-of-string delimiter, will distribute<br />
Avignon to City, 84000 to ZIP, Vaucluse to County, Province-Cote-d'Azur to State and France to Country <br />
<br />
and in the case of missing fields, as long as the first is not empty, will distribute Woerth to City, Alsace to State and FRANCE to Country.<br />
<br />
It allows initial whitespace and an optional comma after the Country<br />
<br />
'''Example 2'''<br />
<br />
In many 16th and 17th century English IGI records the situation is more complicated. <br />
<br />
The Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
<br />
If you use Gramps 3.2 , then you will need [http://gramps-addons.svn.sourceforge.net/viewvc/gramps-addons/branches/gramps32/download/PlaceCompletion.addon.tgz this addon].<br />
<br />
If you use Gramps 3.1.x, then you will need version 1.2 of the Place Completion Tool. You can find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_2.tar.gz placecompletion_1_2.tar.gz]. <br />
<br />
If you use Gramps 3.0.x, then you will need version 1.1 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz]. <br />
<br />
If you use Gramps 2.2.5+, then you will need version 1.0 of the Place Completion Tool. You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
<br />
Extract the two files that are in the download. Put the .glade and .py file both in the plugins directory. For linux:<br />
<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patches ==<br />
<br />
<br />
<br />
<br />
=== Parsing place title ===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),<br />
<br />
Note: this patch does not work with locale set to french (e.g. LANGUAGE=fr_FR.UTF-8). Before getting this fixed, users should temporarily move to english locale to use it.<br />
<br />
<br />
[[Category:Proposed Tool Specifications]]<br />
[[Category:Plugins]]<br />
[[Category:Developers/General]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees&diff=16068Gramps 3.1 Wiki Manual - Manage Family Trees2009-06-07T14:52:27Z<p>DouginIT: /* Importing Data */</p>
<hr />
<div>Now we turn to a detailed exploration of the day-to-day use of GRAMPS. In this Chapter we give a detailed overview of how you can manage your family trees, as well as share your data with other genealogists.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
<br />
== Starting a New Family Tree ==<br />
[[Image:Dbmanager01.png|right|thumb|250px|Fig. 3.1. Starting Family Trees ]]<br />
<br />
<br />
<br />
To start a new Family Tree, choose ''' Family Trees ->Manage Family Trees ''' or select the {{man button|Family Trees}} button from the toolbar. This will open the Family Tree Manager.<br />
<br />
<br />
<br />
<br />
<br />
Select the {{man button|New}} button and GRAMPS will add a new Family Tree entry to the list of Family Trees. To change its name from the default ''Family Tree 1'', click on the name and type in a new name.<br />
<br />
Now select {{man button|Load Family Tree}} to open the new, empty Family Tree.<br />
<br />
== Opening a Family Tree ==<br />
<br />
To open a Family Tree, either choose ''' Family Trees ->Manage Family Trees ''' or click the {{man button|Family Trees}} button on the Toolbar. The {{man label|Family Tree Manager}} will appear and you'll see a list of all the Family Trees known to GRAMPS. An icon will display in the {{man label|Status}} column beside any Family Tree that is currently open. Select the tree you want to open, and open it by selecting the {{man button|Load Family Tree}} button. Alternatively you can double-click on the desired Tree.<br />
<br />
To open a recently accessed Family Tree, choose either ''' Family Trees ->Open Recent ''' or the down arrow next to the {{man button|Family Trees}} button and select the Family Tree from the list.<br />
<br />
If you do not have "write permissions" for the selected Family Tree, it will be opened in a Read Only mode. In this mode, the data may be viewed, but no changes will be made to the Tree. To indicate this mode, the title of the main window will be appended with '''(Read Only)''' text.<br />
<br />
== Opening a GEDCOM or XML database ==<br />
<br />
GRAMPS allows you to open certain databases that have not been saved in GRAMPS' own file format from the command line. '''TODO link to page explaining how.''' These include XML and GEDCOM databases. But you should be aware that if the XML or GEDCOM database is relatively large, you will encounter performance problems, and in the event of a crash your data can be corrupted. Hence, it is normally better to create a new GRAMPS family tree (database) and import your XML/GEDCOM data into it.<br />
<br />
{{man note| Opening databases |XML and GEDCOM databases require all data to be held in memory and don't contain indexes. GRAMPS' native format is a database that only reads the data needed. Thus, for a large family tree the data can be accessed quicker and more efficiently by not using XML or GEDCOM.}}<br />
<br />
{{man warn| GEDCOM Editing |Please keep in mind that some information in a GEDCOM file may be lost during import into GRAMPS as well as export back to GEDCOM. Simply opening and viewing the file will not change it. However, if any changes were made and they were not abandoned upon exit, exiting GRAMPS will save the data, with possible data loss.}}<br />
<br />
== Deleting a Family Tree ==<br />
Select the family tree you want removed, and click the {{man button|Delete}} button. <br />
<br />
This will '''completely''' remove the tree, with no possibility to retrieve the data. Consider taking a backup of your data by exporting to the GRAMPS XML format, and storing that file.<br />
<br />
== Renaming a Family Tree ==<br />
You can rename a Family Tree (or an archive of it) by selecting the tree you want to rename and clicking {{man button|Rename}}. You can also click on the name in the list of trees. <br />
<br />
In either case, you just type in the new name to have it take effect.<br />
<br />
== Backing up a Family Tree ==<br />
The safest way to backup your GRAMPS Family Tree is to export to '''GRAMPS XML''' format (or '''GRAMPS Package''' to include items from your Gallery) and copy the resultant file to a safe place, preferably in a different building.<br />
<br />
You can use the Archive feature to store snapshots of your tree. These snapshots can be used as simple backups, very useful if you want to try something that you might later want to undo. However this method should not be used for standard backups, as it will not survive a hard disk crash or most of the other disasters that can befall a computer.<br />
<br />
''For advanced users:'' each database is stored in its own subdirectory under ~/.gramps. A manual backup can be made by backing up this directory.<br />
<br />
== Archiving a Family Tree ==<br />
You can easily archive and timestamp family trees with GRAMPS built-in use of [http://www.gnu.org/software/rcs/ GNU Revision Control System] or ''RCS''. For this to be possible this utility must be installed on your computer.<br />
<br />
To make an archive :<br />
# load your family tree.<br />
# click on the {{man button|Family Trees}} button (it has the gramps logo and displays {{man label|Manage databases}} when you hover over it).<br />
# click on the family tree you've just loaded: the {{man button|Archive}} button should appear.<br />
# click on {{man button|Archive}} and you will be asked for an archive name.<br />
After archiving, the list of family trees will now show your original family tree with a right-pointing triangle on its left.<br />
* Click on the triangle to display the archive name.(Click again to collapse the archive list).<br />
Archives can be deleted, renamed and Extracted. <br />
<br />
<br />
If you click on an archive, the {{man button|Extract}} button becomes visible. Click on this to obtain the extracted archive. It will appear in the family tree list as ''<name of original tree>:<name of archive>'' and is now an independent family tree. This can be a useful way of preserving an archive, because archives disappear if the originating tree is deleted; and they are not incorporated into a Portable XML export of the tree.<br />
<br />
== Extracting a Family Tree Archive ==<br />
[[Image:Dbmanager04.png|thumb|left|200px|Fig. 3.2 Selecting a version to extract]]<br />
Simply highlight the archive you want to restore, and select the {{man button|Extract}} button.<br />
[[Image:Dbmanager05.png|thumb|right|200px|Fig. 3.3 Extracted version]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
GRAMPS will transfer the archive into a new Family Tree. The Family Tree name is based on the original name and the archive name (see also [[#Archiving a Family Tree|Archiving a Family Tree]]).<br />
<br />
== Unlocking a Family Tree ==<br />
When GRAMPS opens a tree, it locks the tree, preventing you or anyone else opening it at the same time. A second copy of GRAMPS will be able to open another family tree, but the tree already open will appear with the lock icon, indicating you cannot open it. Closing the tree in the first copy of GRAMPS will make it available to be opened in the second copy. <br />
<br />
If you could open the same Family Tree in two GRAMPS at once, it is likely your data would be damaged.<br />
<br />
In the unlikely event of a crash of GRAMPS, the family tree will be left in a locked state. To unlock the tree, select the locked family tree, and click the {{man button|Unlock}} button that will be available. Only do this if you are sure no other copy of GRAMPS is using this family tree.<br />
<br />
== Repairing a Damaged Family Tree ==<br />
[[Image:Dbmanager07.png|thumb|right|250px|Fig. 3.4 Repairing a Family Tree]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Should your Family Tree become damaged or corrupted in some way, GRAMPS' Family Tree Manager will display a red Error icon in the {{man label|Status}} column.<br />
<br />
To tell GRAMPS to attempt to repair the damage, select the Tree and then click the {{man button|Repair}} button.<br />
<br />
This will attempt to rebuild your tree from the backup files that are automatically created on exit.<br />
<br />
== Saving Changes to Your Family Tree ==<br />
<br />
GRAMPS saves your changes as soon as you apply them. This means, for example, that any time you click {{man button|OK}} when using GRAMPS, your changes are immediately recorded and saved. There is no separate "save" command.<br />
<br />
You can undo changes you've made by selecting ''' Edit ->Undo '''. If you select this command repeatedly, your most recent changes will be undone one at a time. To roll back multiple commands at a time, you can using the {{man label|Undo History}} dialog available from the {{man label|Edit}} menu.<br />
<br />
If you want to return your Family Tree to the way it was when you opened it, select ''' Family Trees ->Abandon changes and quit ''' . (This is just like quitting without saving in other programs.)<br />
<br />
If you would like to save a copy of your Family Tree under a different name, you will need to export it and then import it into a new Family Tree. The ''GRAMPS XML database'' format is recommended for this purpose.<br />
<br />
== Importing Data ==<br />
<br />
Importing allows you to bring data from other genealogy programs into a GRAMPS database. Currently, GRAMPS can import data from the following formats:<br />
* GRAMPS XML (.gramps file extension)<br />
* GRAMPS package (.gpkg file extension)<br />
* GRAMPS CSV Spreadsheet - comma separated values (.csv file extension)<br />
* GRAMPS V2.x database (.grdb file extension)<br />
* GEDCOM (.ged file extension)<br />
* GeneWeb (.gw file extension)<br />
<br />
{{man note| Importing vs. opening |Please recognize that importing a database is different from opening a database. When you import, you are actually bringing data from one database into a GRAMPS database. When you open a file, you are editing your original file.}}<br />
<br />
To import data, select ''' Family Trees ->Import ''' . The '''Import database''' dialog will open, asking you to specify the file you wish to import.<br />
Note that you can only import data into an existing database so if you are transferring all your data from another program or from an older<br />
version of GRAMPS, then first create a new empty database and then import the data into it.<br />
<br />
{{man warn| Data loss with some formats |It is important to note that the importing process is not perfect for GEDCOM and GeneWeb databases. There is a chance that some of the data in these databases will not be imported into GRAMPS.}}<br />
<br />
The GRAMPS XML, GRAMPS package and GRAMPS V2.x database are all native GRAMPS formats. There is no risk of information loss when importing from or exporting to these formats.<br />
<br />
*GRAMPS XML (.gramps): The GRAMPS XML file is the standard GRAMPS data-exchange and backups format, and was also the default working-database format for older (pre 2.x) versions of GRAMPS. Unlike the grdb format, it is architecture independent and human-readable. The database may also have references to non-local (external) media objects, therefore it is not guaranteed to be completely portable (for full portability including media objects the GRAMPS package (.gpkg) should be used). The GRAMPS XML database is created by exporting ( ''' Family Trees ->Export... ''' ) to that format.<br />
<br />
*GRAMPS package (.gpkg): The GRAMPS package is a compressed archive containing the GRAMPS XML file and all media objects (images, sound files, etc.) to which the database refers. Because it contains all the media objects, this format is completely portable. The GRAMPS package is created by exporting ( ''' Family Trees ->Export... ''' ) data in that format.<br />
<br />
*GRAMPS V2.x database (.grdb): Prior to Version 3.1, this native GRAMPS database format was a specific form of Berkeley database (BSDDB) with a special structure of data tables. This format was binary and architecture-dependent. It was very quick and efficient, but not generally portable across computers with different binary architecture (e.g. i386 vs. alpha). <br />
<br />
If you import information from another GRAMPS database or GRAMPS XML database, you will see the progress of the operation in the progress bar of GRAMPS' main window.<br />
<br />
The GRAMPS CSV Spreadsheet format allows importing and exporting of a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information.<br />
<br />
<br />
{{man warn| Caution in rebuilding a database |If you need to transfer a part of your database into an earlier version of it, for instance in rebuilding a database after some error, it is important that you *don't* export and import it as XML. As the current version 3.1.2 stands, you could corrupt that database irretrievably. Export it as Gedcom and import that. You will need to carry out editing afterwards to remove any duplicates, and some information will certainly have been lost, notably the media, but the database itself will be safe.}}<br />
<br />
== Exporting Data ==<br />
[[Image:Export-druid.png|right|thumb|200px|Fig.3.4 Export assistant: format selection]]<br />
'''Wait to update manual:''' The exporter is undergoing a major rewrite.<br />
<br />
<br />
<br />
Exporting allows you to share any portion of your GRAMPS database with other researchers as well as to enable you to transfer your data to another computer. Currently, GRAMPS can export data to the following formats: GRAMPS XML, GEDCOM, GRAMPS package, Web Family Tree, GeneWeb, and GRAMPS CSV Spreadsheet formats.<br />
<br />
{{man note| Export is saving a copy |When you export, you are saving a copy of the currently opened database. Exporting creates another file with a copy of your data. Note that the database that remains opened in your GRAMPS window is NOT the file saved by your export. Additional editing of the currently opened database will not alter the copy produced by the export.}}<br />
<br />
To export data, choose ''' Family Trees ->Export ''' . This will bring up the '''Export''' assistant. Its pages will guide you through the format selection (see [[Media:export-druid.png|Fig.3.4]] ), file selection, and format specific export options. After a final confirmation page, the export will be performed according to the choices you have made. At any time, you can click the {{man button|Back}} button and revise any selection, and then go forward to redo the export.<br />
<br />
=== Export into GRAMPS formats ===<br />
<br />
*GRAMPS XML database export (.gramps): This format is the standard format for data-exchange and backups (see the related .gpkg format below for full portability including media objects). Exporting into GRAMPS XML format will produce a portable database. As XML is a text-based human-readable format, you may also use it to take a look at your data. This format is compatible with the previous versions of GRAMPS.<br />
<br />
*GRAMPS package export (.gpkg): Exporting to the GRAMPS package format will create a compressed file that contains the GRAMPS XML database and copies of all associated media files. This is useful if you want to move your database to another computer or to share it with someone.<br />
<br />
*Export to CD: Exporting to CD will prepare your database and copies of all media object files for recording onto a CD. To actually burn the CD, you will need to go to the GNOME '''burn:///''' location, which can be accessed by navigating through Nautilus: After exporting to CD, select ''' Go ->CD Creator ''' in the Nautilus menu. Your database directory will show up. To burn it to the CD, click the CD icon on the Nautilus toolbar, or select ''' File ->Write to CD ''' in the Nautilus menu.<br />
<br />
If a media file is not found during export, you will see the same '''Missing Media''' dialog you encounter with GEDCOM export.<br />
<br />
=== Exporting into the GEDCOM format ===<br />
[[Image:Gedcom-export.png|right|thumb|200px|Fig.3.5.Export assistant: GEDCOM options]]<br />
<br />
GRAMPS allows you to export a database into the common GEDCOM format. It provides options that allow you to fine tune your export (see [[Media:Gedcom-export.png|Fig.3.5.gedcom-export-fig]] ).<br />
<br />
*Filter: The filter allows you to export a limited amount of data, based on the criteria you select.<br />
<br />
*Target: While GEDCOM is a standard, not every program implements it in the same way. This can lead to data loss. GRAMPS can reduce the data loss in some cases. You can tell GRAMPS what program is the target, and GRAMPS will customize the exported file for that program. If your program is not listed, choose the "GEDCOM 5.5 Standard".<br />
<br />
*Do not include records marked private: Check this box to prevent private records from being included in the exported file.<br />
<br />
*Restrict data on living people: Check this box to limit the information exported for living people. This means that all information concerning their birth, death, addresses, significant events, etc., will be omitted in the exported GEDCOM file. If you choose this option, you will be given additional options to limit further the data on living people. For example, you can choose to substitute the word "Living" for the first name; you can exclude notes; and you can exclude sources for living people.<br />
<br />
Sometimes, it is not always obvious from the data if someone is actually alive. GRAMPS uses an advanced algorithm to try to determine if a person could still be alive. Remember, GRAMPS is making its best guess, and it may not always be able to guess correctly all the time. Please double check your data.<br />
<br />
*Reference images from path: Check this box to tell GRAMPS to use the specific path for your images when writing image references in GEDCOM.<br />
<br />
This option allows specify where your image files are located. This is useful when you are transferring your GEDCOM file from one computer to another. It tells the program that is importing the data where your images are.<br />
<br />
=== Export into other formats ===<br />
<br />
*Web Family Tree: Exporting to Web Family Tree will create a text file that can be used by the Web Family Tree program. Export options include filter selection and the ability to limit data on living people to that of their family ties.<br />
<br />
*GeneWeb: Exporting to GeneWeb will save a copy of your data into a popular web genealogy format. To find out more about GeneWeb and its format, visit http://cristal.inria.fr/~ddr/GeneWeb/en/.<br />
<br />
*vCalendar and vCard: Exporting to vCalendar or vCard will save information in a format used in many calendaring and addressbook applications, sometimes called PIM for Personal Information Manager.<br />
<br />
*GRAMPS CSV Spreadsheet format: Allows exporting (and importing) a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information. Also, see [[Gramps_3.1_Wiki_Manual_-_Settings#Export_the_screen|Export Display]] .<br />
<br />
== Moving 2.2 databases to Gramps 3 ==<br />
<br />
There are two ways of moving your Gramps data from version 2.2 to version 3; either directly importing your version 2.2 grdb file or by exporting to XML format first. Because of complexity in the way that version 2.2 stores data, exporting to XML is usually the most convenient and problem free way of moving your data to version 3.<br />
<br />
*Import 2.2 grdb file: In a Gramps 2.2 database, your data is stored in a grdb file along with one or more log files that are kept in directories found in the .gramps/env directory. To import your 2.2 data directly into Gramps 3, create a new database and select the option to import a Gramps 2.2 database. You need to make sure that you are running Gramps 3 from the same user you used to run Gramps 2.2 so that it has access to the same .gramps/env directory containing the log files that supplement your database. If you are running Gramps 3 from a different user or on another machine you need to make provisions to make the same .gramps/env directory and log files available. If you get an error saying "/tmp/tmpDkI5pO could not be opened" or something similar when attempt to import your database then it means that Gramps 3 cannot see all of the files that constitute your database.<br />
<br />
*Gramps XML: With this approach firstly start up Gramps 2.2 and export your database to the Gramps XML format. The XML file is actually compressed and contained in a .gramps file. This file is portable, has no other dependent files and can be moved to wherever you have Gramps 3 installed. Next, start Gramps 3 and create an empty database using the Family Tree Manager and import the .gramps file.<br />
<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
<br />
[[Category:Documentation]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees&diff=15607Gramps 3.1 Wiki Manual - Manage Family Trees2009-05-27T17:32:38Z<p>DouginIT: /* Restoring a Family Tree Archive */</p>
<hr />
<div>Now we turn to a detailed exploration of the day-to-day use of GRAMPS. In this Chapter we give a detailed overview of how you can manage your family trees, as well as share your data with other genealogists.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
<br />
== Starting a New Family Tree ==<br />
[[Image:Dbmanager01.png|right|thumb|250px|Fig. 3.1. Starting Family Trees ]]<br />
<br />
<br />
<br />
To start a new Family Tree, choose ''' Family Trees ->Manage Family Trees ''' or select the {{man button|Family Trees}} button from the toolbar. This will open the Family Tree Manager.<br />
<br />
<br />
<br />
<br />
<br />
Select the {{man button|New}} button and GRAMPS will add a new Family Tree entry to the list of Family Trees. To change its name from the default ''Family Tree 1'', click on the name and type in a new name.<br />
<br />
Now select {{man button|Load Family Tree}} to open the new, empty Family Tree.<br />
<br />
== Opening a Family Tree ==<br />
<br />
To open a Family Tree, either choose ''' Family Trees ->Manage Family Trees ''' or click the {{man button|Family Trees}} button on the Toolbar. The {{man label|Family Tree Manager}} will appear and you'll see a list of all the Family Trees known to GRAMPS. An icon will display in the {{man label|Status}} column beside any Family Tree that is currently open. Select the tree you want to open, and open it by selecting the {{man button|Load Family Tree}} button. Alternatively you can double-click on the desired Tree.<br />
<br />
To open a recently accessed Family Tree, choose either ''' Family Trees ->Open Recent ''' or the down arrow next to the {{man button|Family Trees}} button and select the Family Tree from the list.<br />
<br />
If you do not have "write permissions" for the selected Family Tree, it will be opened in a Read Only mode. In this mode, the data may be viewed, but no changes will be made to the Tree. To indicate this mode, the title of the main window will be appended with '''(Read Only)''' text.<br />
<br />
== Opening a GEDCOM or XML database ==<br />
<br />
GRAMPS allows you to open certain databases that have not been saved in GRAMPS' own file format from the command line. '''TODO link to page explaining how.''' These include XML and GEDCOM databases. But you should be aware that if the XML or GEDCOM database is relatively large, you will encounter performance problems, and in the event of a crash your data can be corrupted. Hence, it is normally better to create a new GRAMPS family tree (database) and import your XML/GEDCOM data into it.<br />
<br />
{{man note| Opening databases |XML and GEDCOM databases require all data to be held in memory and don't contain indexes. GRAMPS' native format is a database that only reads the data needed. Thus, for a large family tree the data can be accessed quicker and more efficiently by not using XML or GEDCOM.}}<br />
<br />
{{man warn| GEDCOM Editing |Please keep in mind that some information in a GEDCOM file may be lost during import into GRAMPS as well as export back to GEDCOM. Simply opening and viewing the file will not change it. However, if any changes were made and they were not abandoned upon exit, exiting GRAMPS will save the data, with possible data loss.}}<br />
<br />
== Deleting a Family Tree ==<br />
Select the family tree you want removed, and click the {{man button|Delete}} button. <br />
<br />
This will '''completely''' remove the tree, with no possibility to retrieve the data. Consider taking a backup of your data by exporting to the GRAMPS XML format, and storing that file.<br />
<br />
== Renaming a Family Tree ==<br />
You can rename a Family Tree (or an archive of it) by selecting the tree you want to rename and clicking {{man button|Rename}}. You can also click on the name in the list of trees. <br />
<br />
In either case, you just type in the new name to have it take effect.<br />
<br />
== Backing up a Family Tree ==<br />
The safest way to backup your GRAMPS Family Tree is to export to '''GRAMPS XML''' format (or '''GRAMPS Package''' to include items from your Gallery) and copy the resultant file to a safe place, preferably in a different building.<br />
<br />
You can use the Archive feature to store snapshots of your tree. These snapshots can be used as simple backups, very useful if you want to try something that you might later want to undo. However this method should not be used for standard backups, as it will not survive a hard disk crash or most of the other disasters that can befall a computer.<br />
<br />
''For advanced users:'' each database is stored in its own subdirectory under ~/.gramps. A manual backup can be made by backing up this directory.<br />
<br />
== Archiving a Family Tree ==<br />
You can easily archive and timestamp family trees with GRAMPS built-in use of [http://www.gnu.org/software/rcs/ GNU Revision Control System] or ''RCS''. For this to be possible this utility must be installed on your computer.<br />
<br />
To make an archive, first load your family tree.<br /><br />
Then click on the Family Trees button (it has the gramps logo and displays "Manage databases" when you hover over it).<br /><br />
Click on the family tree you've just loaded: the Archive button should appear.<br /><br />
Click on Archive and you will be asked for an archive name.<br /><br />
After archiving, the list of family trees will now show your original family tree with a right-pointing triangle on its left.<br /><br />
Click on the triangle to display the archive name.(Click again to collapse the archive list).<br /><br />
Archives can be deleted, renamed and Extracted. <br />
<br />
<br />
If you click on an archive, the Extract button becomes visible. Click on this to obtain the extracted archive. It will appear in the family tree list as <name of original tree>:<name of archive> and is now an independent family tree.This can be a useful way of preserving an archive, because archives disappear if the originating tree is deleted; and they are not incorporated into a Portable XML export of the tree.<br />
<br />
== Extracting a Family Tree Archive ==<br />
[[Image:Dbmanager04.png|thumb|left|200px|Fig. 3.2 Selecting a version to extract]]<br />
Simply highlight the archive you want to restore, and select the {{man button|Extract}} button.<br />
[[Image:Dbmanager05.png|thumb|right|200px|Fig. 3.3 Extracted version]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
GRAMPS will transfer the archive into a new Family Tree. The Family Tree name is based on the original name and the archive name (see also Archiving a Family Tree).<br />
<br />
== Unlocking a Family Tree ==<br />
When GRAMPS opens a tree, it locks the tree, preventing you or anyone else opening it at the same time. A second copy of GRAMPS will be able to open another family tree, but the tree already open will appear with the lock icon, indicating you cannot open it. Closing the tree in the first copy of GRAMPS will make it available to be opened in the second copy. <br />
<br />
If you could open the same Family Tree in two GRAMPS at once, it is likely your data would be damaged.<br />
<br />
In the unlikely event of a crash of GRAMPS, the family tree will be left in a locked state. To unlock the tree, select the locked family tree, and click the {{man button|Unlock}} button that will be available. Only do this if you are sure no other copy of GRAMPS is using this family tree.<br />
<br />
== Repairing a Damaged Family Tree ==<br />
[[Image:Dbmanager07.png|thumb|right|250px|Fig. 3.4 Repairing a Family Tree]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Should your Family Tree become damaged or corrupted in some way, GRAMPS' Family Tree Manager will display a red Error icon in the {{man label|Status}} column.<br />
<br />
To tell GRAMPS to attempt to repair the damage, select the Tree and then click the {{man button|Repair}} button.<br />
<br />
This will attempt to rebuild your tree from the backup files that are automatically created on exit.<br />
<br />
== Saving Changes to Your Family Tree ==<br />
<br />
GRAMPS saves your changes as soon as you apply them. This means, for example, that any time you click {{man button|OK}} when using GRAMPS, your changes are immediately recorded and saved. There is no separate "save" command.<br />
<br />
You can undo changes you've made by selecting ''' Edit ->Undo '''. If you select this command repeatedly, your most recent changes will be undone one at a time. To roll back multiple commands at a time, you can using the {{man label|Undo History}} dialog available from the {{man label|Edit}} menu.<br />
<br />
If you want to return your Family Tree to the way it was when you opened it, select ''' Family Trees ->Abandon changes and quit ''' . (This is just like quitting without saving in other programs.)<br />
<br />
If you would like to save a copy of your Family Tree under a different name, you will need to export it and then import it into a new Family Tree. The ''GRAMPS XML database'' format is recommended for this purpose.<br />
<br />
== Importing Data ==<br />
<br />
Importing allows you to bring data from other genealogy programs into a GRAMPS database. Currently, GRAMPS can import data from the following formats:<br />
<br />
GRAMPS XML (.gramps file extension)<br />
<br />
GRAMPS package (.gpkg file extension)<br />
<br />
GRAMPS CSV Spreadsheet - comma separated values (.csv file extension)<br />
<br />
GRAMPS V2.x database (.grdb file extension)<br />
<br />
GEDCOM (.ged file extension)<br />
<br />
GeneWeb (.gw file extension)<br />
<br />
{{man note| Importing vs. opening |Please recognize that importing a database is different from opening a database. When you import, you are actually bringing data from one database into a GRAMPS database. When you open a file, you are editing your original file.}}<br />
<br />
To import data, select ''' Family Trees ->Import ''' . The '''Import database''' dialog will open, asking you to specify the file you wish to import.<br />
Note that you can only import data into an existing database so if you are transferring all your data from another program or from an older<br />
version of GRAMPS, then first create a new empty database and then import the data into it.<br />
<br />
{{man warn| Data loss with some formats |It is important to note that the importing process is not perfect for GEDCOM and GeneWeb databases. There is a chance that some of the data in these databases will not be imported into GRAMPS.}}<br />
<br />
The GRAMPS XML, GRAMPS package and GRAMPS V2.x database are all native GRAMPS formats. There is no risk of information loss when importing from or exporting to these formats.<br />
<br />
*GRAMPS XML (.gramps): The GRAMPS XML file is the standard GRAMPS data-exchange and backups format, and was also the default working-database format for older (pre 2.x) versions of GRAMPS. Unlike the grdb format, it is architecture independent and human-readable. The database may also have references to non-local (external) media objects, therefore it is not guaranteed to be completely portable (for full portability including media objects the GRAMPS package (.gpkg) should be used). The GRAMPS XML database is created by exporting ( ''' Family Trees ->Export... ''' ) to that format.<br />
<br />
*GRAMPS package (.gpkg): The GRAMPS package is a compressed archive containing the GRAMPS XML file and all media objects (images, sound files, etc.) to which the database refers. Because it contains all the media objects, this format is completely portable. The GRAMPS package is created by exporting ( ''' Family Trees ->Export... ''' ) data in that format.<br />
<br />
*GRAMPS V2.x database (.grdb): Prior to Version 3.1, this native GRAMPS database format was a specific form of Berkeley database (BSDDB) with a special structure of data tables. This format was binary and architecture-dependent. It was very quick and efficient, but not generally portable across computers with different binary architecture (e.g. i386 vs. alpha). <br />
<br />
If you import information from another GRAMPS database or GRAMPS XML database, you will see the progress of the operation in the progress bar of GRAMPS' main window.<br />
<br />
The GRAMPS CSV Spreadsheet format allows importing and exporting of a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information.<br />
<br />
== Exporting Data ==<br />
[[Image:Export-druid.png|right|thumb|200px|Fig.3.4 Export assistant: format selection]]<br />
'''Wait to update manual:''' The exporter is undergoing a major rewrite.<br />
<br />
<br />
<br />
Exporting allows you to share any portion of your GRAMPS database with other researchers as well as to enable you to transfer your data to another computer. Currently, GRAMPS can export data to the following formats: GRAMPS XML, GEDCOM, GRAMPS package, Web Family Tree, GeneWeb, and GRAMPS CSV Spreadsheet formats.<br />
<br />
{{man note| Export is saving a copy |When you export, you are saving a copy of the currently opened database. Exporting creates another file with a copy of your data. Note that the database that remains opened in your GRAMPS window is NOT the file saved by your export. Additional editing of the currently opened database will not alter the copy produced by the export.}}<br />
<br />
To export data, choose ''' Family Trees ->Export ''' . This will bring up the '''Export''' assistant. Its pages will guide you through the format selection (see [[Media:export-druid.png|Fig.3.4]] ), file selection, and format specific export options. After a final confirmation page, the export will be performed according to the choices you have made. At any time, you can click the {{man button|Back}} button and revise any selection, and then go forward to redo the export.<br />
<br />
=== Export into GRAMPS formats ===<br />
<br />
*GRAMPS XML database export (.gramps): This format is the standard format for data-exchange and backups (see the related .gpkg format below for full portability including media objects). Exporting into GRAMPS XML format will produce a portable database. As XML is a text-based human-readable format, you may also use it to take a look at your data. This format is compatible with the previous versions of GRAMPS.<br />
<br />
*GRAMPS package export (.gpkg): Exporting to the GRAMPS package format will create a compressed file that contains the GRAMPS XML database and copies of all associated media files. This is useful if you want to move your database to another computer or to share it with someone.<br />
<br />
*Export to CD: Exporting to CD will prepare your database and copies of all media object files for recording onto a CD. To actually burn the CD, you will need to go to the GNOME '''burn:///''' location, which can be accessed by navigating through Nautilus: After exporting to CD, select ''' Go ->CD Creator ''' in the Nautilus menu. Your database directory will show up. To burn it to the CD, click the CD icon on the Nautilus toolbar, or select ''' File ->Write to CD ''' in the Nautilus menu.<br />
<br />
If a media file is not found during export, you will see the same '''Missing Media''' dialog you encounter with GEDCOM export.<br />
<br />
=== Exporting into the GEDCOM format ===<br />
[[Image:Gedcom-export.png|right|thumb|200px|Fig.3.5.Export assistant: GEDCOM options]]<br />
<br />
GRAMPS allows you to export a database into the common GEDCOM format. It provides options that allow you to fine tune your export (see [[Media:Gedcom-export.png|Fig.3.5.gedcom-export-fig]] ).<br />
<br />
*Filter: The filter allows you to export a limited amount of data, based on the criteria you select.<br />
<br />
*Target: While GEDCOM is a standard, not every program implements it in the same way. This can lead to data loss. GRAMPS can reduce the data loss in some cases. You can tell GRAMPS what program is the target, and GRAMPS will customize the exported file for that program. If your program is not listed, choose the "GEDCOM 5.5 Standard".<br />
<br />
*Do not include records marked private: Check this box to prevent private records from being included in the exported file.<br />
<br />
*Restrict data on living people: Check this box to limit the information exported for living people. This means that all information concerning their birth, death, addresses, significant events, etc., will be omitted in the exported GEDCOM file. If you choose this option, you will be given additional options to limit further the data on living people. For example, you can choose to substitute the word "Living" for the first name; you can exclude notes; and you can exclude sources for living people.<br />
<br />
Sometimes, it is not always obvious from the data if someone is actually alive. GRAMPS uses an advanced algorithm to try to determine if a person could still be alive. Remember, GRAMPS is making its best guess, and it may not always be able to guess correctly all the time. Please double check your data.<br />
<br />
*Reference images from path: Check this box to tell GRAMPS to use the specific path for your images when writing image references in GEDCOM.<br />
<br />
This option allows specify where your image files are located. This is useful when you are transferring your GEDCOM file from one computer to another. It tells the program that is importing the data where your images are.<br />
<br />
=== Export into other formats ===<br />
<br />
*Web Family Tree: Exporting to Web Family Tree will create a text file that can be used by the Web Family Tree program. Export options include filter selection and the ability to limit data on living people to that of their family ties.<br />
<br />
*GeneWeb: Exporting to GeneWeb will save a copy of your data into a popular web genealogy format. To find out more about GeneWeb and its format, visit http://cristal.inria.fr/~ddr/GeneWeb/en/.<br />
<br />
*vCalendar and vCard: Exporting to vCalendar or vCard will save information in a format used in many calendaring and addressbook applications, sometimes called PIM for Personal Information Manager.<br />
<br />
*GRAMPS CSV Spreadsheet format: Allows exporting (and importing) a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information. Also, see [[Gramps_3.1_Wiki_Manual_-_Settings#Export_the_screen|Export Display]] .<br />
<br />
== Moving 2.2 databases to Gramps 3 ==<br />
<br />
There are two ways of moving your Gramps data from version 2.2 to version 3; either directly importing your version 2.2 grdb file or by exporting to XML format first. Because of complexity in the way that version 2.2 stores data, exporting to XML is usually the most convenient and problem free way of moving your data to version 3.<br />
<br />
*Import 2.2 grdb file: In a Gramps 2.2 database, your data is stored in a grdb file along with one or more log files that are kept in directories found in the .gramps/env directory. To import your 2.2 data directly into Gramps 3, create a new database and select the option to import a Gramps 2.2 database. You need to make sure that you are running Gramps 3 from the same user you used to run Gramps 2.2 so that it has access to the same .gramps/env directory containing the log files that supplement your database. If you are running Gramps 3 from a different user or on another machine you need to make provisions to make the same .gramps/env directory and log files available. If you get an error saying "/tmp/tmpDkI5pO could not be opened" or something similar when attempt to import your database then it means that Gramps 3 cannot see all of the files that constitute your database.<br />
<br />
*Gramps XML: With this approach firstly start up Gramps 2.2 and export your database to the Gramps XML format. The XML file is actually compressed and contained in a .gramps file. This file is portable, has no other dependent files and can be moved to wherever you have Gramps 3 installed. Next, start Gramps 3 and create an empty database using the Family Tree Manager and import the .gramps file.<br />
<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
<br />
[[Category:Documentation]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees&diff=15606Gramps 3.1 Wiki Manual - Manage Family Trees2009-05-27T17:21:31Z<p>DouginIT: /* Archiving a Family Tree */</p>
<hr />
<div>Now we turn to a detailed exploration of the day-to-day use of GRAMPS. In this Chapter we give a detailed overview of how you can manage your family trees, as well as share your data with other genealogists.<br />
<br />
{{grampsmanualcopyright}}<br />
<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
<br />
== Starting a New Family Tree ==<br />
[[Image:Dbmanager01.png|right|thumb|250px|Fig. 3.1. Starting Family Trees ]]<br />
<br />
<br />
<br />
To start a new Family Tree, choose ''' Family Trees ->Manage Family Trees ''' or select the {{man button|Family Trees}} button from the toolbar. This will open the Family Tree Manager.<br />
<br />
<br />
<br />
<br />
<br />
Select the {{man button|New}} button and GRAMPS will add a new Family Tree entry to the list of Family Trees. To change its name from the default ''Family Tree 1'', click on the name and type in a new name.<br />
<br />
Now select {{man button|Load Family Tree}} to open the new, empty Family Tree.<br />
<br />
== Opening a Family Tree ==<br />
<br />
To open a Family Tree, either choose ''' Family Trees ->Manage Family Trees ''' or click the {{man button|Family Trees}} button on the Toolbar. The {{man label|Family Tree Manager}} will appear and you'll see a list of all the Family Trees known to GRAMPS. An icon will display in the {{man label|Status}} column beside any Family Tree that is currently open. Select the tree you want to open, and open it by selecting the {{man button|Load Family Tree}} button. Alternatively you can double-click on the desired Tree.<br />
<br />
To open a recently accessed Family Tree, choose either ''' Family Trees ->Open Recent ''' or the down arrow next to the {{man button|Family Trees}} button and select the Family Tree from the list.<br />
<br />
If you do not have "write permissions" for the selected Family Tree, it will be opened in a Read Only mode. In this mode, the data may be viewed, but no changes will be made to the Tree. To indicate this mode, the title of the main window will be appended with '''(Read Only)''' text.<br />
<br />
== Opening a GEDCOM or XML database ==<br />
<br />
GRAMPS allows you to open certain databases that have not been saved in GRAMPS' own file format from the command line. '''TODO link to page explaining how.''' These include XML and GEDCOM databases. But you should be aware that if the XML or GEDCOM database is relatively large, you will encounter performance problems, and in the event of a crash your data can be corrupted. Hence, it is normally better to create a new GRAMPS family tree (database) and import your XML/GEDCOM data into it.<br />
<br />
{{man note| Opening databases |XML and GEDCOM databases require all data to be held in memory and don't contain indexes. GRAMPS' native format is a database that only reads the data needed. Thus, for a large family tree the data can be accessed quicker and more efficiently by not using XML or GEDCOM.}}<br />
<br />
{{man warn| GEDCOM Editing |Please keep in mind that some information in a GEDCOM file may be lost during import into GRAMPS as well as export back to GEDCOM. Simply opening and viewing the file will not change it. However, if any changes were made and they were not abandoned upon exit, exiting GRAMPS will save the data, with possible data loss.}}<br />
<br />
== Deleting a Family Tree ==<br />
Select the family tree you want removed, and click the {{man button|Delete}} button. <br />
<br />
This will '''completely''' remove the tree, with no possibility to retrieve the data. Consider taking a backup of your data by exporting to the GRAMPS XML format, and storing that file.<br />
<br />
== Renaming a Family Tree ==<br />
You can rename a Family Tree (or an archive of it) by selecting the tree you want to rename and clicking {{man button|Rename}}. You can also click on the name in the list of trees. <br />
<br />
In either case, you just type in the new name to have it take effect.<br />
<br />
== Backing up a Family Tree ==<br />
The safest way to backup your GRAMPS Family Tree is to export to '''GRAMPS XML''' format (or '''GRAMPS Package''' to include items from your Gallery) and copy the resultant file to a safe place, preferably in a different building.<br />
<br />
You can use the Archive feature to store snapshots of your tree. These snapshots can be used as simple backups, very useful if you want to try something that you might later want to undo. However this method should not be used for standard backups, as it will not survive a hard disk crash or most of the other disasters that can befall a computer.<br />
<br />
''For advanced users:'' each database is stored in its own subdirectory under ~/.gramps. A manual backup can be made by backing up this directory.<br />
<br />
== Archiving a Family Tree ==<br />
You can easily archive and timestamp family trees with GRAMPS built-in use of [http://www.gnu.org/software/rcs/ GNU Revision Control System] or ''RCS''. For this to be possible this utility must be installed on your computer.<br />
<br />
To make an archive, first load your family tree.<br /><br />
Then click on the Family Trees button (it has the gramps logo and displays "Manage databases" when you hover over it).<br /><br />
Click on the family tree you've just loaded: the Archive button should appear.<br /><br />
Click on Archive and you will be asked for an archive name.<br /><br />
After archiving, the list of family trees will now show your original family tree with a right-pointing triangle on its left.<br /><br />
Click on the triangle to display the archive name.(Click again to collapse the archive list).<br /><br />
Archives can be deleted, renamed and Extracted. <br />
<br />
<br />
If you click on an archive, the Extract button becomes visible. Click on this to obtain the extracted archive. It will appear in the family tree list as <name of original tree>:<name of archive> and is now an independent family tree.This can be a useful way of preserving an archive, because archives disappear if the originating tree is deleted; and they are not incorporated into a Portable XML export of the tree.<br />
<br />
== Restoring a Family Tree Archive ==<br />
[[Image:Dbmanager04.png|thumb|left|200px|Fig. 3.2 Selecting a version to restore]]<br />
Simply highlight the archive you want to restore, and select the {{man button|Restore}} button.<br />
[[Image:Dbmanager05.png|thumb|right|200px|Fig. 3.3 Restored version]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
GRAMPS will transfer the archive into a new Family Tree. The Family Tree name is based on the original name and the archive name.<br />
<br />
== Unlocking a Family Tree ==<br />
When GRAMPS opens a tree, it locks the tree, preventing you or anyone else opening it at the same time. A second copy of GRAMPS will be able to open another family tree, but the tree already open will appear with the lock icon, indicating you cannot open it. Closing the tree in the first copy of GRAMPS will make it available to be opened in the second copy. <br />
<br />
If you could open the same Family Tree in two GRAMPS at once, it is likely your data would be damaged.<br />
<br />
In the unlikely event of a crash of GRAMPS, the family tree will be left in a locked state. To unlock the tree, select the locked family tree, and click the {{man button|Unlock}} button that will be available. Only do this if you are sure no other copy of GRAMPS is using this family tree.<br />
<br />
== Repairing a Damaged Family Tree ==<br />
[[Image:Dbmanager07.png|thumb|right|250px|Fig. 3.4 Repairing a Family Tree]]<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
Should your Family Tree become damaged or corrupted in some way, GRAMPS' Family Tree Manager will display a red Error icon in the {{man label|Status}} column.<br />
<br />
To tell GRAMPS to attempt to repair the damage, select the Tree and then click the {{man button|Repair}} button.<br />
<br />
This will attempt to rebuild your tree from the backup files that are automatically created on exit.<br />
<br />
== Saving Changes to Your Family Tree ==<br />
<br />
GRAMPS saves your changes as soon as you apply them. This means, for example, that any time you click {{man button|OK}} when using GRAMPS, your changes are immediately recorded and saved. There is no separate "save" command.<br />
<br />
You can undo changes you've made by selecting ''' Edit ->Undo '''. If you select this command repeatedly, your most recent changes will be undone one at a time. To roll back multiple commands at a time, you can using the {{man label|Undo History}} dialog available from the {{man label|Edit}} menu.<br />
<br />
If you want to return your Family Tree to the way it was when you opened it, select ''' Family Trees ->Abandon changes and quit ''' . (This is just like quitting without saving in other programs.)<br />
<br />
If you would like to save a copy of your Family Tree under a different name, you will need to export it and then import it into a new Family Tree. The ''GRAMPS XML database'' format is recommended for this purpose.<br />
<br />
== Importing Data ==<br />
<br />
Importing allows you to bring data from other genealogy programs into a GRAMPS database. Currently, GRAMPS can import data from the following formats:<br />
<br />
GRAMPS XML (.gramps file extension)<br />
<br />
GRAMPS package (.gpkg file extension)<br />
<br />
GRAMPS CSV Spreadsheet - comma separated values (.csv file extension)<br />
<br />
GRAMPS V2.x database (.grdb file extension)<br />
<br />
GEDCOM (.ged file extension)<br />
<br />
GeneWeb (.gw file extension)<br />
<br />
{{man note| Importing vs. opening |Please recognize that importing a database is different from opening a database. When you import, you are actually bringing data from one database into a GRAMPS database. When you open a file, you are editing your original file.}}<br />
<br />
To import data, select ''' Family Trees ->Import ''' . The '''Import database''' dialog will open, asking you to specify the file you wish to import.<br />
Note that you can only import data into an existing database so if you are transferring all your data from another program or from an older<br />
version of GRAMPS, then first create a new empty database and then import the data into it.<br />
<br />
{{man warn| Data loss with some formats |It is important to note that the importing process is not perfect for GEDCOM and GeneWeb databases. There is a chance that some of the data in these databases will not be imported into GRAMPS.}}<br />
<br />
The GRAMPS XML, GRAMPS package and GRAMPS V2.x database are all native GRAMPS formats. There is no risk of information loss when importing from or exporting to these formats.<br />
<br />
*GRAMPS XML (.gramps): The GRAMPS XML file is the standard GRAMPS data-exchange and backups format, and was also the default working-database format for older (pre 2.x) versions of GRAMPS. Unlike the grdb format, it is architecture independent and human-readable. The database may also have references to non-local (external) media objects, therefore it is not guaranteed to be completely portable (for full portability including media objects the GRAMPS package (.gpkg) should be used). The GRAMPS XML database is created by exporting ( ''' Family Trees ->Export... ''' ) to that format.<br />
<br />
*GRAMPS package (.gpkg): The GRAMPS package is a compressed archive containing the GRAMPS XML file and all media objects (images, sound files, etc.) to which the database refers. Because it contains all the media objects, this format is completely portable. The GRAMPS package is created by exporting ( ''' Family Trees ->Export... ''' ) data in that format.<br />
<br />
*GRAMPS V2.x database (.grdb): Prior to Version 3.1, this native GRAMPS database format was a specific form of Berkeley database (BSDDB) with a special structure of data tables. This format was binary and architecture-dependent. It was very quick and efficient, but not generally portable across computers with different binary architecture (e.g. i386 vs. alpha). <br />
<br />
If you import information from another GRAMPS database or GRAMPS XML database, you will see the progress of the operation in the progress bar of GRAMPS' main window.<br />
<br />
The GRAMPS CSV Spreadsheet format allows importing and exporting of a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information.<br />
<br />
== Exporting Data ==<br />
[[Image:Export-druid.png|right|thumb|200px|Fig.3.4 Export assistant: format selection]]<br />
'''Wait to update manual:''' The exporter is undergoing a major rewrite.<br />
<br />
<br />
<br />
Exporting allows you to share any portion of your GRAMPS database with other researchers as well as to enable you to transfer your data to another computer. Currently, GRAMPS can export data to the following formats: GRAMPS XML, GEDCOM, GRAMPS package, Web Family Tree, GeneWeb, and GRAMPS CSV Spreadsheet formats.<br />
<br />
{{man note| Export is saving a copy |When you export, you are saving a copy of the currently opened database. Exporting creates another file with a copy of your data. Note that the database that remains opened in your GRAMPS window is NOT the file saved by your export. Additional editing of the currently opened database will not alter the copy produced by the export.}}<br />
<br />
To export data, choose ''' Family Trees ->Export ''' . This will bring up the '''Export''' assistant. Its pages will guide you through the format selection (see [[Media:export-druid.png|Fig.3.4]] ), file selection, and format specific export options. After a final confirmation page, the export will be performed according to the choices you have made. At any time, you can click the {{man button|Back}} button and revise any selection, and then go forward to redo the export.<br />
<br />
=== Export into GRAMPS formats ===<br />
<br />
*GRAMPS XML database export (.gramps): This format is the standard format for data-exchange and backups (see the related .gpkg format below for full portability including media objects). Exporting into GRAMPS XML format will produce a portable database. As XML is a text-based human-readable format, you may also use it to take a look at your data. This format is compatible with the previous versions of GRAMPS.<br />
<br />
*GRAMPS package export (.gpkg): Exporting to the GRAMPS package format will create a compressed file that contains the GRAMPS XML database and copies of all associated media files. This is useful if you want to move your database to another computer or to share it with someone.<br />
<br />
*Export to CD: Exporting to CD will prepare your database and copies of all media object files for recording onto a CD. To actually burn the CD, you will need to go to the GNOME '''burn:///''' location, which can be accessed by navigating through Nautilus: After exporting to CD, select ''' Go ->CD Creator ''' in the Nautilus menu. Your database directory will show up. To burn it to the CD, click the CD icon on the Nautilus toolbar, or select ''' File ->Write to CD ''' in the Nautilus menu.<br />
<br />
If a media file is not found during export, you will see the same '''Missing Media''' dialog you encounter with GEDCOM export.<br />
<br />
=== Exporting into the GEDCOM format ===<br />
[[Image:Gedcom-export.png|right|thumb|200px|Fig.3.5.Export assistant: GEDCOM options]]<br />
<br />
GRAMPS allows you to export a database into the common GEDCOM format. It provides options that allow you to fine tune your export (see [[Media:Gedcom-export.png|Fig.3.5.gedcom-export-fig]] ).<br />
<br />
*Filter: The filter allows you to export a limited amount of data, based on the criteria you select.<br />
<br />
*Target: While GEDCOM is a standard, not every program implements it in the same way. This can lead to data loss. GRAMPS can reduce the data loss in some cases. You can tell GRAMPS what program is the target, and GRAMPS will customize the exported file for that program. If your program is not listed, choose the "GEDCOM 5.5 Standard".<br />
<br />
*Do not include records marked private: Check this box to prevent private records from being included in the exported file.<br />
<br />
*Restrict data on living people: Check this box to limit the information exported for living people. This means that all information concerning their birth, death, addresses, significant events, etc., will be omitted in the exported GEDCOM file. If you choose this option, you will be given additional options to limit further the data on living people. For example, you can choose to substitute the word "Living" for the first name; you can exclude notes; and you can exclude sources for living people.<br />
<br />
Sometimes, it is not always obvious from the data if someone is actually alive. GRAMPS uses an advanced algorithm to try to determine if a person could still be alive. Remember, GRAMPS is making its best guess, and it may not always be able to guess correctly all the time. Please double check your data.<br />
<br />
*Reference images from path: Check this box to tell GRAMPS to use the specific path for your images when writing image references in GEDCOM.<br />
<br />
This option allows specify where your image files are located. This is useful when you are transferring your GEDCOM file from one computer to another. It tells the program that is importing the data where your images are.<br />
<br />
=== Export into other formats ===<br />
<br />
*Web Family Tree: Exporting to Web Family Tree will create a text file that can be used by the Web Family Tree program. Export options include filter selection and the ability to limit data on living people to that of their family ties.<br />
<br />
*GeneWeb: Exporting to GeneWeb will save a copy of your data into a popular web genealogy format. To find out more about GeneWeb and its format, visit http://cristal.inria.fr/~ddr/GeneWeb/en/.<br />
<br />
*vCalendar and vCard: Exporting to vCalendar or vCard will save information in a format used in many calendaring and addressbook applications, sometimes called PIM for Personal Information Manager.<br />
<br />
*GRAMPS CSV Spreadsheet format: Allows exporting (and importing) a subset of your GRAMPS data in a simple spreadsheet format. See [[Gramps 3.1 Wiki Manual - Manage Family Trees: CSV Import and Export|CSV Import and Export]] for more information. Also, see [[Gramps_3.1_Wiki_Manual_-_Settings#Export_the_screen|Export Display]] .<br />
<br />
== Moving 2.2 databases to Gramps 3 ==<br />
<br />
There are two ways of moving your Gramps data from version 2.2 to version 3; either directly importing your version 2.2 grdb file or by exporting to XML format first. Because of complexity in the way that version 2.2 stores data, exporting to XML is usually the most convenient and problem free way of moving your data to version 3.<br />
<br />
*Import 2.2 grdb file: In a Gramps 2.2 database, your data is stored in a grdb file along with one or more log files that are kept in directories found in the .gramps/env directory. To import your 2.2 data directly into Gramps 3, create a new database and select the option to import a Gramps 2.2 database. You need to make sure that you are running Gramps 3 from the same user you used to run Gramps 2.2 so that it has access to the same .gramps/env directory containing the log files that supplement your database. If you are running Gramps 3 from a different user or on another machine you need to make provisions to make the same .gramps/env directory and log files available. If you get an error saying "/tmp/tmpDkI5pO could not be opened" or something similar when attempt to import your database then it means that Gramps 3 cannot see all of the files that constitute your database.<br />
<br />
*Gramps XML: With this approach firstly start up Gramps 2.2 and export your database to the Gramps XML format. The XML file is actually compressed and contained in a .gramps file. This file is portable, has no other dependent files and can be moved to wherever you have Gramps 3 installed. Next, start Gramps 3 and create an empty database using the Family Tree Manager and import the .gramps file.<br />
<br />
<br />
{{languages|Gramps_3.1_Wiki_Manual_-_Manage_Family_Trees}}<br />
<br />
{{man index|Gramps 3.1 Wiki Manual - Main Window|Gramps 3.1 Wiki Manual - Entering and Editing Data: Brief|3.1}}<br />
<br />
<br />
[[Category:Documentation]]</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=13022Addon:Place completion tool2009-02-02T11:48:59Z<p>DouginIT: /* Design Specification */</p>
<hr />
<div>[[Category:Proposed_Tool_Specifications]][[Category:Plugins]]<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.0.1, as well as an old version that works with GRAMPS version 2.2.5+ ! [[Place_completion_tool#Download|Download beta]].<br />
<br />
[[Category:Plugins]]<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go. Eg you give a <br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.<br />
*Construction of a uniform title/description field, from the data in the place object<br />
<br />
== Design Specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parse Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1: selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of Places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced Usage ==<br />
This is for advanced users only knowing regular expressions. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
=== Parse title details ===<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
In many 16th and 17th century English IGI records the Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
You can download the beta version.<br />
For Gramps 3.0.x: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz]. <br />
For Gramps 2.2.5+: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
Extract the two files in this archive. Put the .glade and .py file both in the plugins directory, linux:<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patchs ==<br />
<br />
===Parsing place title===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=13021Addon:Place completion tool2009-02-02T11:47:28Z<p>DouginIT: /* Parse title details */</p>
<hr />
<div>[[Category:Proposed_Tool_Specifications]][[Category:Plugins]]<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.0.1, as well as an old version that works with GRAMPS version 2.2.5+ ! [[Place_completion_tool#Download|Download beta]].<br />
<br />
[[Category:Plugins]]<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go. Eg you give a <br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.<br />
*Construction of a uniform title/description field, from the data in the place object<br />
<br />
== Design Specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parsed Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1: selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of Places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced Usage ==<br />
This is for advanced users only knowing regular expressions. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
=== Parse title details ===<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
In many 16th and 17th century English IGI records the Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give the 3-string record a non-existent Parish called "Of" ! <br />
<br />
To avoid this, when using Regex B click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'.<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
You can download the beta version.<br />
For Gramps 3.0.x: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz]. <br />
For Gramps 2.2.5+: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
Extract the two files in this archive. Put the .glade and .py file both in the plugins directory, linux:<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patchs ==<br />
<br />
===Parsing place title===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=13020Addon:Place completion tool2009-02-02T11:43:23Z<p>DouginIT: /* Parse title details */</p>
<hr />
<div>[[Category:Proposed_Tool_Specifications]][[Category:Plugins]]<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.0.1, as well as an old version that works with GRAMPS version 2.2.5+ ! [[Place_completion_tool#Download|Download beta]].<br />
<br />
[[Category:Plugins]]<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go. Eg you give a <br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.<br />
*Construction of a uniform title/description field, from the data in the place object<br />
<br />
== Design Specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parsed Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1: selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of Places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced Usage ==<br />
This is for advanced users only knowing regular expressions. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
=== Parse title details ===<br />
In 'Parsing and Conversion of existing title or position', 'Parse title' and 'Change title into' provide some pre-defined options for extracting location values from a Place Title. Otherwise regex parsing is needed.<br />
<br />
Write your regex in 'Parse title:'.Click on 'Find', which shows the proposed changes. Then click 'Apply'.<br />
<br />
In many 16th and 17th century English IGI records the Place Title takes the form of 3 strings (Town, County, Country) or 4 strings (Parish, District, County, Country) for example:<br />
<br />
(a) Chester le Street, Durham, England - 3-string<br />
<br />
(b) Of Middleton-in-Teesdale, Durham, England - 3-string<br />
<br />
(c) Bishoply,Stanhope, Durham, England - 4-string<br />
<br />
(d) Of St. Margaret's, Stanhope, Durham, England - 4-string<br />
<br />
<br />
For the 3-string record the following regex, treating the comma character as an end-of-string delimiter, will distribute the 3 strings correctly to City, County, Country locations, leaving 4-string records untouched.<br />
<br />
Regex A:<br />
<br />
\s*(Of[,]*\s*)*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
For 4-string records the following regex will distribute the 4 strings correctly to Parish, City, County, Country locations, leaving 3-string records untouched.<br />
<br />
Regex B:<br />
<br />
\s*(Of[,]*\s*)*(?P<parish>[^,]+?)[,]\s*(?P<city>[^,]+?)[,]\s*(?P<county>[^,]+?)[,]\s*((?P<country>[^,]+?)){1,1}$<br />
<br />
<br />
"Bogus" 4-string records: a not uncommon error in these old records is for 'Of' to be followed by a comma, e.g.<br />
<br />
(e) Of, Houghton-le-Spring, Durham, England<br />
<br />
Regex A will parse 3-string records correctly and Regex B 4-string records. However Regex B will attempt to treat a 3-string record with 'Of,' as if it were a 4-string record. This would give it a Parish and set the name to "Of" ! To avoid this,click on 'Find' to display the records proposed for change and delete all the 3-string 'Of,' records before clicking 'Apply'<br />
<br />
<br />
<br />
The predefined regex expressions are as follows, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
You can download the beta version.<br />
For Gramps 3.0.x: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz]. <br />
For Gramps 2.2.5+: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
Extract the two files in this archive. Put the .glade and .py file both in the plugins directory, linux:<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patchs ==<br />
<br />
===Parsing place title===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),</div>DouginIThttps://gramps-project.org/wiki/index.php?title=Addon:Place_completion_tool&diff=13013Addon:Place completion tool2009-02-01T15:29:27Z<p>DouginIT: /* Design Specification */</p>
<hr />
<div>[[Category:Proposed_Tool_Specifications]][[Category:Plugins]]<br />
A tool to bring the places in your GRAMPS database in accordance with the GRAMPS requirements: batch add country, county; look-up latitude-longitude; set description (title); ...<br />
<br />
There is a version for 3.0.1, as well as an old version that works with GRAMPS version 2.2.5+ ! [[Place_completion_tool#Download|Download beta]].<br />
<br />
[[Category:Plugins]]<br />
<br />
== Place Completion tool ==<br />
This tool helps you fill in the place attributes like county, country, ..., by allowing you to select the places you work on, and do changes on all these places with one button click.<br />
<br />
The general aims are:<br />
*Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. This should be parsed to insert the values in the correct attribute fields.<br />
*Latitude and longitude are important to show data on a map. However, doing a look-up of this data on the internet is slow and time consuming. The tool allows to search in the free resources on the net.<br />
*Setting of an attribute of a set of places in one go. Eg you give a <br />
*Conversion of latitude and longitude to a fixed data format. On import one might obtain latitude and longitude in several different formats. A conversion tool to store them all in the same format is usefull.<br />
*Construction of a uniform title/description field, from the data in the place object<br />
<br />
== Design Specification ==<br />
See [[Place completion tool specification]]<br />
Place/Location is a newer concept in GRAMPS. Many older databases only have a Place title field which is a descriptive text containing city, state, country. To distribute these values into the correct attribute fields, see Parsed Title Details below<br />
<br />
== Manual ==<br />
The place completion tool gives a lot of functionality. This manual should help you to understand how it works.<br />
<br />
=== Download resources ===<br />
The place completion tool can look up for you latitude/longitude, add county information (USA), ... . For some of this functionality, you must download datafiles of the countries you are interested in. Right now you have three options:<br />
<br />
#Download geonames country files. You can do this [http://download.geonames.org/export/dump/ here freely]. Geonames parses fastest, so is the advised format to use<br />
#Download geonames USA state files. You can do this [http://geonames.usgs.gov/domestic/download_data.htm here freely]. This is advised for USA searches, as the data in the USA country file contains many doubles, which can be avoided by searching state per state. State info also contains county information.<br />
#download GNS Geonet country files (not available for usa). You can do this [ftp://ftp.nga.mil/pub/gns_data here freely with ftp]. <br />
<br />
Watch out, some of these downloads are '''VERY''' large, especially USA data. Only download what you need!<br />
<br />
<small>'''Note''': The geonames data of popular places is in English, so eg municipalities in Italy will be found, but Roma not, as this is Rome in English. To find data with these you need to search in the localised variants of the name (see below)</small><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP.}}<br />
<br />
=== Starting the tool ===<br />
You will find the plugin under 'Tools > Utilities > Interactive place completion'<br />
<br />
=== The dialog explained ===<br />
[[Image:place_completion_tool_empty.png|500px|The Place Completion Tool]]<br />
<br />
The Dialog consists of 4 parts:<br />
====Part 1: selection of places====<br />
First you need to choose with which places you want to work. You can use several methods to define your places:<br />
# Use a place filter. You can use two preset filters: ''All places'', which returns all places, and ''No Latitude/Longitude given'', which returns all places of which the latitude or the longitude is not set. You can also created a custom place filter in the place view, test it with the filter sidebar, and then use it in this tool. All custom filters you made will be available<br />
# To prevent the need to make a filter for every city, ... in your data, you can set country,state,county,city or parish of the places you want to search on. This works just like in the filter sideview in the places view.<br />
# Use a latitude, longitude rectangle. Eg, suppose you have the latitude and longitude of all places in the UK, and now want to add in the state attribute ''Wales'', for all places in Wales. You can look on a map, note down the centre of Wales in latitude and longitude, as well as roughly the width and height of this rectangle. This will allow you to obtain all places in Wales (and some in England), allowing to much faster set the state information.<br />
<br />
====Part 2. Completion of Places ====<br />
#The first possibility is to look up in a datafile the latitude and longitude of your places. For this you must have downloaded the necessary resources, see section above. You can select with a file dialog the file you want to search, and set how this data must be parsed. The following parsing options are available:<br />
##''GeoNames country file, city search'': use the city attribute to look for lat/lon in a GeoNames country file. This is the fastest search.<br />
##''GeoNames country file, city localized variants search'': use the city attribute to look for lat/lon in a GeoNames country file using the localised (non-English) known names in the GeoNames file. Eg, Roma will be found with this option (as Roma is the Italian local variant of the English name Rome)<br />
##''GeoNames country file, title begin, general search'': Use the start of the title field to search in a GeoNames file. With start it is meant everything before a comma:''',''' . This allows to find landmarks, squares, ... . Eg, if the title of your place is: ''Piazza Navona, Rome'', using this search will find you the latitude and longitude of this famous square in Rome. <br />
##''GeoNames USA state file, city search'': Looking for places in the USA file is almost worthless: it takes a long time and every name exists several times. Hence, it is worthwhile to use state by state. If a USA state file is selected for doing a search, you '''must''' select this option. The city attribute is used for the search.<br />
##''GNS Geonet country file, city search'': use the city attribute to search in a GNS file (slower than GeoNames search!).<br />
##''GNS Geonet country file, title begin search'': use the start of the title of a place to search in a GNS file. With start everything appearing before the first comma is meant.<br />
#A second option is to parse some existing data in your places.<br />
##You can parse the title attribute to extract information from it. Eg a title like ''Albany, NY'' can be used to set the city attribute to ''Albany'' and the state attribute to ''NY''.<br />
##You can set the title of all the selected places to a uniform way. This is interesting if due to imports you have different styles for the title field, which can be annoying in reports. At the moment there are two options:<br />
###Set title field to ''City[, State]'': This means the title of your places will contain the city, and if the state field is present, the state will be appended with a comma.<br />
###Set title field to ''Titlestart[, City][, State]'': This means the present start of your title will be kept. If this start is not the city, then the city will be appended. If state is present, also state will be appended. An example: suppose your title is ''Piazza Navona, Italy'', the city is ''Rome'' and the State is ''Lazio''. Using this option to set the title would change the title attribute into ''Piazza Navona, Rome, Lazio''.<br />
##Convert latitude and longitude to a uniform way. Again due to import, copy/paste, you might have latitude and longitude entered in different formats. This is annoying on reports. This options allows you to set for all selected places the lat/lon to one form. The options are:<br />
###All in degree notation: use the classical degree notation with degree, minutes and seconds.<br />
###All in decimal notation: use the decimal system to denote lat/lon.<br />
###Correct -50° in 50°S: a much seen error is to use - for the classical degree notation, which is wrong, and which GRAMPS will not be able to interpret. With this option this error is looked for and corrected.<br />
# A third option is to set attributes of all selected places. You can set the country, state, county, parish, zip/postal code and city attributes of all places in one sweep.<br />
<br />
====Part 3. Overview of the results ==== <br />
After having entered all data in Part 1 and 2, you click find for GRAMPS to search all changes that will occur. This part of the dialog shows all changes that will occur. <br />
<br />
[[Image:place_completion_tool_results.png]]<br />
<br />
All selected places are shown. If changes will be done all changes are listed as subentries of the place. Every change will be a subentry. <br />
<br />
If the change will '''overwrite''' an existing entry, the subentry is '''shown in orange'''. <br />
<br />
<br />
'''TO AVOID PROBLEMS, GO OVER ALL CHANGES QUICKLY, AND CHECK ALL ENTRIES IN ORANGE!'''<br />
<br />
<br />
The following actions are possible in the result screen:<br />
# press delete to delete the entry, making sure that this change will not occur. You can delete the entry to delete all changes, or select one subentry, to only delete that specific chagne<br />
# double-click on an entry to open the place dialog. If you double-click on the entry, '''all changes will be preentered'''. If you double-click on a subentry, only this specific change will be preentered in the place dialog.<br />
# press tab to open in a browser window google maps. Pressing tab on a subentry showing a '''new''' lat/lon entry will open google maps on this new lat/lon position. Pressing tab on the top place entry will give open google maps with the old lat/lon position, or if that is not known the title/city field is used for the search.<br />
<br />
====Part 4. Actions ==== <br />
After you have checked the changes in Part 3, you can now apply them all with one button click, by clicking the ''Apply'' button. <br />
<br />
<br />
Clicking ''Help'' will bring you to this page, clicking ''Close'' will close the window and clicking ''Google Maps'' when an entry is selected in the results field has the same effect as pressing tab on an entry (see above).<br />
<br />
== Example == <br />
<br />
Open the example file from the examples where latitude and longitude are empty: [http://gramps.svn.sourceforge.net/viewvc/*checkout*/gramps/trunk/gramps2/example/gramps/example.gramps?revision=7186 example.gramps]. <br />
<br />
We will now show how the places in this file can be completed. The best thing to do is open a new family tree (.grdb), give it a name, and import the example.gramps file. This file has 852 places, which would mean a lot of manual edits if you do not use this tool!<br />
<br />
Now, open the place view. You will see all places are of the form:<br />
:Aberdeen, WA<br />
This value is the <code>Place Name</code> attribute (the title or description of the place). <br />
<br />
=== Step 1: City and State data ===<br />
Our first step will be to split this field into a <code>City</code> value (here Aberdeen), and a <code>State</code> value (here WA).<br />
<br />
We open the ''Place completion tool'':<br />
[[Image:place_completion_tool_example1.png|500px|Parse the Place Name Field]]<br />
Here we have selected ''All Places'', and we parse the title as ''City [,|.] State''. Click on ''Find'', quickly scan the data if all looks ok, and then click on ''Apply''. You are notified that 851 places are updated. This is one less that the number of places. Indeed, one place does have a different type of title: ''Puerto Rico'' has no state information.<br />
<br />
=== Step 2: Look-up latitude and longitude ===<br />
We have downloaded the GeoNames datafiles for the USA states, and will now use that to complete the latitude and longitude of the data. At the same time, this will fill up the county field.<br />
<br />
[[Image:place_completion_tool_example2.png|500px|Look up lat/lon for Alaska]]<br />
<br />
In the above screenshot, you see we have selected All Places with State=AK. In the second part of the window we give that we want to search in the AK_DECI.txt file downloaded from GeoNames, using the parsing method: ''GeoNames USA state file, city search''.<br />
<br />
Note that if you want to change AK into Alaska, this would be possble. Just set state=Alaska in the set attributes section of the window.<br />
<br />
<br />
Do this now for all the states. Always check for doubles. Eg, for state ''AL'', going over the changes, we encounter:<br />
<br />
<br />
[[Image:place_completion_tool_example3.png|Double in lat/lon, city Enterprise exists in two counties]]<br />
<br />
<br />
We see that the first time 'Enterprise' if found, it is in county ''Coffee'' in lat/lon:31.31/-85.85. The second hit is for county ''Chilton'' with lat/lon:32.73/-86.62. <br />
<br />
You can now use the Google Maps button (or press TAB key) while the lat/lon subentry is selected to see where this city is in both cases. From this it will be clear for example that one is a hamlet, not really a city, while the first is a real city. So now, select the second lat/lon entry, and delete it by pressing the DEL key. Do the same for the second county entry. <br />
<br />
In case google maps did not allow you to determine which is the correct city, you can double click on the city to open the Place Dialog ('''Warning: this will preenter the data of the Place Completion tool. So hit cancel here if you want to exit without these changes done'''). In this dialog the references tab allows you to navigate to all events coupled to this place. This will give you extra information you might use to decide which of the two found places is the correct place.<br />
<br />
=== Step 3: Problem entries===<br />
While updating all places in step 2, you will have noticed some errors in the state information: Some places have a dubious state: eg OH-AL<br />
<br />
You can obtain these states by choosing ''All Places'' en setting the state search box to '''-'''. Clicking Find will give you all these problem places. You can use google maps or the place dialog to sort them out. You can also use the USA country GeoNames file to search these places in the entire USA. You will need sufficient memory for this, or you will obtain a MemoryError (see below)!<br />
<br />
=== Step 4: Lat/Lon not found ===<br />
<br />
After the above, still some 45 places have no latitude/longitude found. You can now select these places by setting the Place filter to 'No Latitude/Longitude', which will find you all places with no coordinates. <br />
<br />
It will be clear that many of those can be quickly corrected: abbreviations, eg the city field contains ''St.George'', which should be ''Saint George''; double names, eg Waterloo-Cedar Falls, IA means Waterloo near Cedar Falls, changing the city to Waterloo and redoing the search using Google Maps will allow to quickly find which coordinates for Waterloo are needed.<br />
<br />
== Advanced Usage ==<br />
This is for advanced users only knowing regular expressions. <br />
<br />
The parsing fields have entry fields allowing you to give your own parsing. Parsing uses regular expressions. You can use this to parse your title, and to parse a lat/lon file in your own way. For reference, here an overview of the parsing codes used for the predefined parses:<br />
=== Parse title details ===<br />
The following regex expressions are used, where for brevity we use some variables defined lower.<br />
<br />
Note: For those new to Python and Regex please review the HOWTO here:<br />
<br />
http://docs.python.org/dev/howto/regex.html<br />
<br />
<br />
#<nowiki>"City [,|.] State" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+state_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City [,|.] Country" is parsed by : r'\s*(?P<'+city_translated +r'>.+?)\s*[.,]\s*(?P<'+country_translated +r'>.+?)\s*$'</nowiki><br />
#<nowiki>"City (Country)" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*\(\s*(?P<'+country_translated +r'>[^\)]+)\s*\)\s*$'</nowiki><br />
#<nowiki>"City" is parsed by : r'\s*(?P<'+city_translated +r'>.*?)\s*$'</nowiki><br />
<br />
Here the variables used are: <br />
lat_translated = _('lat')<br />
lon_translated = _('lon')<br />
city_translated = _('city')<br />
county_translated = _('county')<br />
state_translated = _('state')<br />
country_translated = _('country')<br />
<br />
You can use one of these variables as a group, and the tool will recognise them, and use as values for the corresponding place attributes.<br />
<br />
=== Lat/Lon lookup parsing ===<br />
For the regex of lat/lon lookup, you need to indicate which data must be replaced with existing place attributes for the search, as well as indicate which regex groups must be extracted. <br />
<br />
#<nowiki>"GeoNames country file, city search" is parsed with: r'\t'+CITY_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, city localized variants search" is parsed with: r'[\t,]'+CITY_transl+r'[,\t][^\t\d]*\t?' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\tP'</nowiki><br />
#<nowiki>"GeoNames country file, title begin, general search" is parsed with: r'\t'+TITLEBEGIN_transl +r'\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)\t[PSTV]'</nowiki><br />
#<nowiki>"GeoNames USA state file, city search" is parsed with: r'\t'+CITY_transl+r'\tPopulated Place\t[^\t]*\t[^\t]*\t' + countygr + r'[^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t' +latgr + r'[\d+-][^\t]*)\t' + longr + r'[\d+-][^\t]*)'</nowiki><br />
#<nowiki>"GNS Geonet country file, city search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\tP\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+CITY_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#<nowiki>"GNS Geonet country file, title begin search" is parsed with: r'\t'+latgr+r'[\d+-][^\t]*)\t'+longr+r'[\d+-][^\t]*)'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[PLSTV]\t[^\t]*\t[^\t]*'+ r'\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t[^\t]*\t[^\t]*\t[^\t]*' + r'\t'+TITLEBEGIN_transl+r'\t[^\t]*\t[^\t\n]+$'</nowiki><br />
#Read of mediawiki CSV dump. This reads the files on [http://tools.wikimedia.de/~kolossos/wp-world/pub_CSV_test3.csv.gz] (for more information, see http://meta.wikimedia.org/wiki/WikiProjects_Geographical_coordinates) (''Contribution by nomeata'')<br />
<br />
For extraction of data you can use the same groupnames as in title parsing, so eg latgr in above should read: <nowiki>r'(?P<'+lat_translated +r'>'</nowiki> .<br />
<br />
The syntax for the values that need to be used for searching in the file, eg CITY_transl, is given by : _('CITY'). You can use as substitution values:<br />
_('CITY'), _('TITLE'), _('TITLEBEGIN'), _('STATE'), _('PARISH'). <br />
<br />
The tool will read in the given regex, replace the substitution strings by the values in the place object, do the search, and extract the regex groups given from the result.<br />
<br />
Resource: [http://de.wikipedia.org/wiki/Wikipedia:GEOnet_Names_Server GEOnet]<br />
<br />
== Troubleshooting ==<br />
=== Non UTF-8 latitude/longitude file ===<br />
The place completion tool expects the input files for location lookup to be in unicode (utf-8). On the occasion this is not the case, you will get the error:<br />
<br />
<code><nowiki>File "/home/benny/programms/gramps/gramps2/src/plugins/PlaceCompletion.py", line 851, in load_latlon_file<br />
self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
UnicodeDecodeError: 'utf8' codec can't decode bytes in position 1610092-1610094: invalid data</nowiki></code> <br />
<br />
Note that the Place Completion tool catches these errors and shows you an information box. After this, the tool will attempt to read the file with utf-8 (unicode), ignoring errors. This might give good results, but will of course fail to produce results on non-unicode encoded files. <br />
<br />
In the above example it is clear the problem is in two bytes, so you can correct this manually: open the file with eg <code>KHexEdit Binary Editor</code>, go to the specified position (offset 1610092), and change the two bytes with a space. <br />
<br />
In the case the file is completely non-unicode, you will have to convert it to unicode with a tool, before using it in the placecompletion tool.<br />
<br />
=== Memory Error ===<br />
The tool might fail with the error:<br />
<br />
<nowiki>self.latlonfile_datastr = infile.read()<br />
File "/usr/lib/python2.4/codecs.py", line 481, in read<br />
return self.reader.read(size)<br />
File "/usr/lib/python2.4/codecs.py", line 293, in read<br />
newchars, decodedbytes = self.decode(data, self.errors)<br />
MemoryError</nowiki><br />
<br />
The tool has to load the datafile for latitude/longitude searching into memory. For large files like USA.txt, this might be impossible if you have limited memory. You can try to close as many programs running at together with GRAMPS, and try the tool again.<br />
<br />
<br />
== Download ==<br />
You can download the beta version.<br />
For Gramps 3.0.x: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_1.tar.gz placecompletion_1_1.tar.gz]. <br />
For Gramps 2.2.5+: You find it at [http://cage.ugent.be/~bm/varia/placecompletion_1_0.tar.gz placecompletion_1_0.tar.gz]. <br />
Extract the two files in this archive. Put the .glade and .py file both in the plugins directory, linux:<br />
* local install: place in <code>~/.gramps/plugins</code><br />
* global install: <code>place_to_gramps_install/src/plugins</code><br />
<br />
{{man warn|Warning:|DO NOT BETA TEST WITH YOUR RESEARCH DATA. EXPORT DATA FIRST TO HAVE A BACKUP, THEN RUN THE TOOL}}<br />
<br />
== Patchs ==<br />
<br />
===Parsing place title===<br />
<br />
For France, some [http://www.geneawiki.com/index.php/Informatique_-_saisie_des_lieux practical rules] could be useful for seizing place. We need :<br />
* the city name + INSEE code (at option). This code is unique and can identify with certainty a common (with the county, district, township and municipality). It can identify with a common insurance even if it has changed its name. This code is used in Archives. ''Using postal code is not advisable ...''<br />
* a subdivision: identifies a parish or a place called within a municipality<br />
* the state (at option) ''or county but is already on INSEE code''<br />
* the country (at option). Ideally it should still take the country. It is understandable that this is tedious. ''Maybe do not enter the country if the genealogy is mostly of one country and seize enter the country for events outside the country's main. Everyone will appreciate.''<br />
<br />
If you have a place name like :<br />
'''City, code, state, country''', you could try this patch on current ''Place completion tool'' for parsing place title on location fields :<br />
<br />
1080a1081<br />
+ code_translated = _('zip')<br />
1091a1093<br />
+ codegr = r'(?P<'+code_translated +r'>'<br />
1100a1103,1106<br />
+ ("citycodestatecountry", "City[,|.] Code[,|.] State[,|.] Country",<br />
+ _("City[,|.] Code[,|.] State[,|.] Country")<br />
+ , r'\s*'+citygr+r'.*?)\s*[.,]\s*'+codegr+r'.*?)\s*[.,]\s*'<br />
+ +stategr+r'.*?)\s*[.,]\s*'+countrygr+r'.*?)\s*$'),</div>DouginIT