8,878
edits
Changes
Integrated the customizing section
{{grampsmanualcopyright}}
{{man index|Gramps 3.4 Wiki Manual - SettingsCustomizing|Gramps 3.4 Wiki Manual - FAQ|3.4}}
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}
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 [[Media:Cfe-df.png|Custom filter]] . The rules are listed by their categories. == Filter vs. Search == 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 {{man menu | -> View}}.
Search and Filter work completely differently and it is useful to understand these differences:
*''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).
*''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).
Filters can be created and controlled from the menu ({{man 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.
Some additional points:
* 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".
* 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.
* 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.
* All Filters use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp".
You can find more details about making filters in [[Example filters]].
The rest of this page details the Filter functionality.
== Regular Expressions ==
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 {{man button|[ ]}}{{man label|Use regular expressions}} option checked.
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''':
* The '''^B''' indicates text that starts with B
* The '''.''' indicates any single character (letter, number, or anything)
* The '''*''' indicates zero or more of the previous (in this case, any single character)
* The '''ship''' matches the exact letters s, h, i, p in that order.
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.
''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.
There are some characters that have special meaning with regular expressions. They are:
. ^ $ * + ? { } [ ] \ | ( )
They can be used as described:
* '.' matches any character (letter, number, or other)
* '^' matches beginning of text
* '$' matches end of text
* '*' matches zero or more of the previous item
* '+' matches one or more of the previous item
* '?' matches zero or one of the previous item (makes it optional)
* '{' - defines a number of matches
* '}' - ends number of matches
* '[' - beginning of set
* ']' - end of set
* '\' - next character is special sequence
* '|' - or
* '(' - beginning of a group
* ')' - ending of a group
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.
* \d Matches any decimal digit; this is equivalent to the class [0-9].
* \D Matches any non-digit character; this is equivalent to the class [^0-9].
* \s Matches any whitespace character; this is equivalent to the class [ \t\n\r\f\v].
* \S Matches any non-whitespace character; this is equivalent to the class [^ \t\n\r\f\v].
* \w Matches any alphanumeric character; this is equivalent to the class [a-zA-Z0-9_].
* \W Matches any non-alphanumeric character; this is equivalent to the class [^a-zA-Z0-9_].
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.
=== Groups and Sets ===
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.
Sets are marked by the '[' and ']' metacharacters.
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.
=== Examples ===
* '''^B.*ship$''' - matches all text that starts with a 'B', followed by anything, ending with 'ship'.
** matches: '''Blankenship''', '''Blueship''', '''Beeship'''
** does not match: '''Blankenships'''
* '''^B.*ship''' - matches all text that starts with a 'B', followed by anything, followed by 'ship' (could be followed by more).
** matches: '''Blankenship''', '''Blankenships''', '''Blueship''', '''Blueshipman''', '''Beeship''', '''Beeshipness'''
** does not match: '''Blankenschips'''
====Common variations of a surname====
*'''example 1:'''
Erikson
Eriksson
Ericson
Ericsson
Erickson
Ericksson
Erichson
Erichsson
are matched by the expression
'''Eri(ch|ck|k|c)(ss|s)on'''
*'''explanation''':
'''Eri''' = Eri
'''(ch|ck|k|c)''' = group matching '''ch''', '''ck''', '''k''' or '''c'''. It tries to make the longest match first
'''(ss|s)''' = group matching '''ss''' or '''s'''. It tries to make the longest match first
'''on''' = on
*'''example 2:'''
Bainbricke
Bainbridge
Bainbrig
Bainbrigg
Bambridge
Banbrig
Banbrige
Baynbrige
are matched by the expression
'''Ba(in|yn|m|n)bri(dge|cke|g(g|e|))'''
*'''explanation:'''
'''Ba''' = Ba
'''(in|yn|m|n)''' = group matching '''in''', '''yn''', '''m''' or '''n'''. It tries to make the longest match first.
'''bri''' = bri
'''(dge|cke|g(g|e|))''' = group matching '''dge''', '''cke''' or ('''g''' with '''g''', '''g''' with '''e''' or '''g''' with nothing)
*'''example 3:'''
nairaud
nairault
naireaud
nayrault
nesrau
nesrault
nesreau
nesreaud
noirau
noiraud
noirauld
noirault
noiraut
noiraux
noireau
noireaud
noireault
noireaut
noirraux
noirreau
noirreaud
nouarault
noyraud
noyrault
are matched by the expression
'''n(es|oua|oai|o[iya]|a[iy])r(r|)(on|((e|)au(x|t|d|lt|)))'''
*'''explanation:'''
'''n''' = n
'''(es|oua|oai|set1|set2)''' = group matching '''es''', '''oua''', '''oai''', '''set1''' or '''set2'''
'''set1''' is '''o[iya]''' = set matching '''o''' AND '''i''', '''y''' or '''a'''. In other words '''oi''', '''oy''' or '''oa'''
'''set2''' is '''a[iy]''' = set matching '''a''' AND '''i''' or '''y'''. In other words '''ai''' or '''ay'''
'''r''' = r
'''(r|)''' = group matching '''r''' or nothing
'''(on|(subgroup1)''' = group matching '''on''' or '''subgroup1'''.
'''subgroup1''' is group matching ('''subgroup2 au subgroup3''')
'''subgroup2''' is '''(e|)''' = group matching '''e''' or nothing
'''au''' = au
'''subgroup3''' is '''(x|t|d|lt)''' = group matching '''x''', '''t''', '''d''' or '''lt'''
====testing regular expressions====
Regular Expression testers can be found online through Google. http://gskinner.com/RegExr/ is simple and convenient
==Custom Filter Editor==
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.
If the Filter Sidebar is inadequate for your purpose, you will need to build custom filters.
{{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''.}}
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.
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.
{{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.}}
Clicking the toolbar {{man button|Add...+}} button invokes the {{man label|Define filter}} dialog (See Fig.11.1)
Type the name for your new filter into the {{man label|Name}} field.
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.
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).
{{-}}
Clicking the toolbar {{man button|Add...+}} button invokes the {{man label|Add Rule}} dialog (See Fig.11.2):
[[Image:Cfe-ar.png|right|thumb|350px|Fig.11.2 Add rule]]
*; 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]].
*; Events View, Sources View, Citations 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.
*; Places View: [[#General_filters|General filters]], and [[#Position filters|Position filters]].
*;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
*;People with <markertag>: Matches people with a marker tag of a particular value. Values: Marker type ' ', Complete, or ToDoTag name.
*;People with complete records: Matches all the people whose records are complete.
*;Has LDS: This rule matches people or families with a LDS event.
{{man index|Gramps 3.4 Wiki Manual - SettingsCustomizing|Gramps 3.4 Wiki Manual - FAQ|3.4}}
{{languages|Gramps_3.4_Wiki_Manual_-_Filters}}
