Gramps 3.4 Wiki Manual - Filters

From Gramps
Revision as of 02:08, 15 October 2012 by Leonhaeuser (Talk | contribs)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search
Gnome-important.png Special copyright notice: All edits to this page need to be under two different copyright licenses:

These licenses allow the Gramps project to maximally use this wiki manual as free content in future Gramps versions. If you do not agree with this dual license, then do not edit this page. You may only link to other pages within the wiki which fall only under the GFDL license via external links (using the syntax: [http://www.gramps-project.org/...]), not via internal links.<br\> Also, only use the known conventions


Previous Index Next


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 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 -> 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 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 [ ]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.

Gnome-important.png
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.

Fig.11.1 Define filter

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 User defined filters dialog appears that lists all the filters (if any) previously defined by you. Click the + button to define a new filter. Once you have designed your filters, you can edit, test, and delete selected filters using the Edit... , Test... , and - 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.

Gramps-notes.png
Changes on filters

The changes made to the filters only take effect when you click the toolbar Apply and close button.

Clicking the toolbar + button invokes the Define filter dialog (See Fig.11.1)

Type the name for your new filter into the Name field.

Enter any comment that would help you identify this filter in the future into the Comment field. Add as many rules to the Rule list as you would like to your filter using + button. If the filter has more than one rule, select one of the 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 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 + button invokes the Add Rule dialog (See Fig.11.2):

Fig.11.2 Add rule

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 OK to add this rule to the rule list of the currently edited filter. Clicking Cancel will abort adding the rule to the filter.


Gnome-important.png
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).


Which filters in which view?

Depending on the used View, you will get a different set of filters.

  • Gramplets
    no filters available
  • Events View, Sources View, Citations View, Media view, Repositories View, and Notes View
    only General filters. Those General filters are specific for a View: in the Media View the filters will only sort and search on Media Objects.

General filters

Persons-, Relationship-, and Pedigree View

This category includes the following general rules:

  • Bookmarked People
    Matches the people on the bookmark list.
  • Default person
    Matches the default person.
  • Disconnected People
    Matches people that have no family relationships to any other person in the database.
  • Everyone
    Matches everyone in the database.
  • Females
    Matches all females.
  • Males
    Matches all males.
  • People having <count> notes
    Matches people having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to
  • People having notes containing <regular expression>
    Matches people whose notes contain text matching a regular expression. Values: Regular expression
  • People having notes containing <substring>
    Matches people whose notes contain text matching a substring. Values: Substring
  • People marked private
    Matches people that are indicated as private.
  • 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.
  • People probably alive
    Matches people without indications of death that are not too old. Values: On Date
  • People with <id> matching regular expression
    Matches people whose GRAMPS ID matches the regular expression. Values: Regular expression


  • 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
  • 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
  • People with <count> associations
    Matches people with a certain number of associations. Values: Number of instances -- Number must be greater than/lesser/equal to
  • 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
  • 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 <tag>
    Matches people with a tag of a particular value. Values: Tag name.
  • People with complete records
    Matches all the people whose records are complete.
  • People with incomplete names
    Matches people with firstname or lastname missing.
  • 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
  • People with the <name>
    Matches people with a specied (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name
  • People with the source
    Matches people who have a particular source. values: Source ID
  • People with the family <attribute>
    Matches people with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...
  • People with the personal <attribute>
    Matches people with the personal attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...
  • People with unknown gender
    Matches all people with unknown gender.
  • People without a known birth date
    Matches people without a known birthdate.
  • 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 Select... button. In the latter case, the ID will appear in the text field after the selection was made.
  • 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:.
  • People with events matching the <event filter>
    Matches persons who have events that match a certain event filter. Values: Event filter name.

Person filters

  • Has Address
    This rule matches people with a personal address.
  • Has Association
    This rule matches people with a personal association.
  • 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 Edit Person dialog.
  • 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.
  • Is default person
    This rule matches the default (home) person.
  • Is a female
    This rule matches any female person.
  • Is a male
    This rule matches any male person.
  • 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.
  • People with incomplete names
    This rule matches all people with either given name or family name missing.
  • People without a birth date
    This rule matches people missing birth date.

Event filters

This category includes the following rules that match people based on their recorded events:

  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • People with incomplete events
    This rule matches people missing date or place in any personal event.
  • Families with incomplete events
    This rule matches people missing date or place in any family event of any of their families.

Family filters

This category includes the following rules that match people based on their family relationships:

  • People with children
    This rule matches people with children.
  • People with multiple marriage records
    This rule matches people with more than one spouse.
  • People with no marriage records
    This rule matches people with no spouses.
  • People who were adopted
    This rule matches adopted people.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.

Ancestral filters

This category includes the following rules that match people based on their ancestral relations to other people:

  • 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 Select... button. In the latter case, the ID will appear in the text field after the selection was made.
  • 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.
  • 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.
  • Has a common ancestor with
    This rule matches people who have common ancestors with the specified person.
  • 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.
  • 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.

Descendant filters

This category includes the following rules that match people based on their descendant relations to other people:

  • 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 Select... button. In the latter case, the ID will appear in the text field after the selection was made.
  • 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.
  • 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.
  • 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.
  • Is a descendant family member of
    This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.

Relationship filters

This category includes the following rules that match people based on their mutual relationship:

  • 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 Select... buttons. In the latter case, the ID will appear in the text field after the selection was made.

Miscellaneous filters

This category includes the following rules which do not naturally fit into any of the above categories:

  • 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.
  • 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.
  • Has LDS
    This rule matches people or families with a LDS event.
Previous Index Next