Gramps 5.1 Wiki Manual - Filters

From Gramps
Jump to: navigation, search
Previous Index Next


Fig. 16.1 Define filter - dialog - default

Filters allow Gramps to limit operations to a smaller part of a family Tree. The filtered part of the Trees shares a certain characteristic in common. (e.g., females born in France between the years 1550 and 1575.) The filter specifies which characteristics are important and allows choosing values for which to look. (In the example, the Filter looks for People of a particular sex who have an Event in specific Place during a small timespan.)

Database queries can be a challenge to compose without errors in syntax. So Filters provide structured and pre-tested database queries that hide most of the syntax complexity while providing some safety nets to avoid routine mistakes. Common characteristics used for filtering are normally presented as "parameter" fields in a form. Then the form composes a properly written query around the parameter. Forms with multiple parameter fields will compound complex queries.

Lists of all the filtering query rules currently defined in Gramps. Each of these rules is available for use when creating custom filters.

The rules are listed by their categories.

Contents

Filter vs. Search

There are two primary ways to find data in Gramps: Search and Filter.

  • Search uses the Search Bar above a listing View (such as People, Families, etc).
    The Search Bar only appears when the entire sidebar is closed. You can show or hide the Gramplet bars through changing the selection of the View ➡ ☑Sidebar or View ➡ ☑Bottombar menus.
  • Custom Filters are selected from pop-up menus in the Filter Gramplet, export option and in some reports. They can be used in combination with Search, or stand-alone in the sidebar/bottombar Gramplets. Custom Filters are created or edited from the filter Gramplet or Edit ➡ Filter Editor menu.

(There is also a basic seek-as-you-type Find box for navigating the active record focus within list view and object selector lists.)


Gramps-notes.png
Name filtering behavior has changed for Gramps 5.1

In prior versions of Gramps, the name portion of the Filter Gramplet would try to match on any single name field (given, surname, prefix, etc) of all names (primary and alternate) but only field per name — you couldn't match the given field and surname field in the same name. You could match surname, but simultaneously matching surname and given in the same query wasn't possible. For example, if you Filter on "John", you would get matches of people with firstname "John" but also those with surname "Johnson". More complex search required use of the regular expressions pattern matching options or custom filters.

This constraint has been removed and simultaneous search of multiple terms is now the default behavior.

Search and Filter work completely differently and it is useful to understand these differences:

  • Search - the Search Bar looks through the database as it appears in the rows and columns on the screen. The Search functionality is probably the one you want to use most of the time, as it is fast and most straightforward. But speed and simplicity imposes some limitations (see below).
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").
Fig. 16.2 Gramps Main Window showing Search Bar
  • Filter - Filters use a more elaborate system. It is not limited to what you see on the screen, but looks at the actual data in all name fields, rather than just what is showing in the View. Entering multiple words does phrase matching for most text fields. However, the Name filter line is far more powerful. Each word in the Name search is handled separately as though it was a sub-search on the records found with the previous search word. And it simultaneously searches all the Name fields.
e.g. a name search of "geo r." in the example tree database finds 5 people: with a variety 'Jr.' & 'Sr.' as the suffix and 'George's as first & middle names. Or searching "garn ski ph" finds Phoebe Emily who has a birth surname of Zieliński and alternate married surname of Garner.
Fig. 16.3 Gramps Filter SideBar for People view - Tag pop-up menu example

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 Search Bar, but all Filters follow the distinction outlined here.

Some additional points:

  • The Filter will search alternative & multiple names too; the Search Bar only looks in the primary name... the one showing in the People view. That is why doing a Filter on "Smith" might list people that superficially don't appear to match. But if you drill down into that person's details with the Name Editor, 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 Search Bar.
  • The Search will only match what is visible. If a name or text is too big to see in listing below Search Bar, 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 default to use case-insensitive matching; "Ship" will match "ship", "SHIP", or "ShIp". As explained below under Regular Expressions, using Regular Expressions does not currently give a means of changing from the default.

See also


Regular Expressions

Regular Expressions(aka regex, regexp, or sometimes rational expression) are a condensed, precise and powerful way to describe text that matches a pattern.

Designing a effective search pattern can be formulaic. Like math formulas, a search pattern can be quickly composed which finds a subset of records but does so very crudely and slowly. Elegant and efficient RegEx phrases are collected by optimization experts in data manipulations. There are many resources (books, websites, professional training) for RegEx design and strategy.

Gramps uses RegEx as a matching option that may be enabled for Custom Filters and in the Filter Gramplets of each Category view.

RegEx pattern matching is an advanced feature and so its checkbox is not selected by default. For Custom Filters, each individual Rule has a

Use regular expressions option check box in its Edit Rule dialog. The Filter Gramplets also have

Use regular expressions option check boxes to allow regexp expression to be used directly for matching strings in their text boxes.

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.

Gramps is currently implemented to make all string matching case-insensitive (which is the opposite of the usual default in Python). There is no easy way at present to override this behaviour for the relatively uncommon purpose of matching strings that have been entered into the database in a particular case format. Regular expressions in Gramps currently give identical results regardless of whether the target string is entered in upper case, title case, lower case or some mixture.

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:

  • . ^ $ * + ? { } [ ] \ | ( )
    decimal point (full stop), caret, dollar sign, asterisk, plus sign, question mark, left and right curly braces, left and right square brackets, backslash, vertical bar (pipe), left and right parentheses


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.

Find all defined values or blanks

To find all values, (.|\s)* will match: any character or any whitespace character; and zero or more repetitions of those.

To find empty (blank or null) strings, ^.{0}$ looks from the start of the match ^ for any character (except newline) . occurring precisely zero times {0} before the end of the match $

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
Using the expression Eri(ch|ck|k|c)(ss|s)on the following are matched:
Erikson
Eriksson
Ericson
Ericsson
Erickson
Ericksson
Erichson
Erichsson

Explanation: Because of the following

  • 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
Using the expression Ba(in|yn|m|n)bri(dge|cke|g(g|e|)) the following are matched:
Bainbricke
Bainbridge
Bainbrig
Bainbrigg
Bambridge
Banbrig
Banbrige
Baynbrige

Explanation: Because of the following

  • 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
Using the expression n(es|oua|oai|o[iya]|a[iy])r(r|)(on|((e|)au(x|t|d|lt|))) the following are matched:
nairaud
nairault
naireaud
nayrault
nesrau                
nesrault
nesreau
nesreaud
noirau
noiraud
noirauld
noirault
noiraut
noiraux
noireau
noireaud
noireault
noireaut
noirraux
noirreau
noirreaud
nouarault
noyraud
noyrault 

Explanation: Because of the following

  • 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. https://www.regexr.com/ is simple and convenient

Gnome-important.png
Regular Expression 'dialect' noted and Repaired

In Gramps 5.1, the sidebar filter inappropriately evaluated parameters containing spaces... attempting to re-interpret a single Regular Expression as a sequence of separate expressions. The Gramps 5.1.1 resolution for Bug 0011321 handles Regular Expressions more literally.

See Also

Regular expressions have been in wide use across the computer industry since the 1950s. But they are "expert tools" designed for power and efficiency rather than intuitiveness. As a result, many resources have been developed on the web.

Some of these resources have excellent tutorials. Some have cheat sheets. Some have “sand boxes” where regular expressions can be explored in real-time.

A sampling of RegEx reference websites:

Custom Filters

Tango-Dialog-information.png
Custom Filter migration

Keep your collection of custom filters through a minor updates of Gramps (e.g., from version 5.0.x to 5.1.x) by manually copying your custom_filter.xml from Gramps User Directory to the corresponding directory in new gramps_version_number.

Even minor upgrades (e.g., from a 5.0.x to a 5.1.x version) may include format changes since the recent innovation of addon rules are causing rapid evolution in Filters. So porting filters in this manner requires verification that the XML definitions haven't changed. Also, Addon rules may have to be installed in the new upgrade before copied custom filters will work safely.


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.

Tango-Dialog-information.png
Building a quick Custom Filter for an object

The clipboard has a Custom Filter generation shortcut. Copy any View object to the Clipboard (by drag'n'drop or by selecting and pressing the Ctrl+C keybinding), then select the object on the Clipboard and right-click to reveal the Clipboard's contextual pop-up menu. The bottom menu item will offer to create a Filter for the selected object.

CategoryName Filters dialog

Gramps-notes.png
Note:Changes on filters

The changes made to the filters only take effect after you use the Close button from this window.

Fig. 16.4 Person Filters - dialog - example

To create new or show previously created custom filters use the CategoryName Filters dialog list where the CategoryName changes based on the category you are in eg:

  • People Person Filters
  • Family Family Filters
  • Events Event Filters
  • Places Place Filters
  • Sources (v3.4.x) Source Filters
  • Citations Citation Filters
  • Repositories Repository Filters
  • Media Media Filters
  • Notes Note Filters

When in the CategoryName Filters dialog you have the following options from the right hand side icons:

  • STOCK_ADD Add a new filter
shows the Define filter dialog and adds a new (as yet unnamed) custom filter framework.
  • STOCK_EDIT Edit the selected filter
opens the Define filter dialog and loads your existing custom filter for editing.
  • Clone Clone the selected filter
makes an exact copy of the selected filter
  • Test Test the selected filter
brings up the 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.
  • STOCK_REMOVE Delete the selected filter:
removes the selected filter from the Gramps collection of custom filters.


Filter Test dialog

Fig. 16.5 Filter Test - results list example from Person Filters

The results list of a successful Filter Test dialog might be empty, a valid custom filter might not match any records.

Define Filter dialog

Tango-Dialog-information.png
Addon Rules for custom filters are available

Filter Rules can be expanded through the addons interface starting with the Gramps 5.1.0 version.
See: Example filters and Addon Rules


Fig. 16.6 Define filter - dialog - default

The Define filter dialog allow you to build 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.

To list all the filters (if any) previously defined by you, access the Define filter dialog from:

  • The Sidebar/Bottombar Filters
  • In most categories via the menu Edit > CategoryName Filter Editor which will bring up the CategoryName Filters dialog where you can select the + (Add another rule to filter) button or Edit the selected filter button.

In the Definition section type the Name: for your new filter and add a Comment: that would help you identify this filter in the future. 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 Options from the drop down list which allows you to choose whether

  • All rules must apply(default)
  • At least one rule must apply
  • Exactly one rule must apply

in order for the filter to generate a match. If your filter has only one rule, this selection has no effect.

  • Select
    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). (Check box unchecked by default)


Add Rule dialog

Tango-Dialog-information.png
A filter you have already designed may be used as a rule parameter 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).
See: Example filters and Addon Rules


Fig. 16.7 Add Rule - selector dialog - available for Person filters - example

To define a new filter click the + (Add another rule to filter) button from the Define filter dialog as this invokes the Add Rule dialog

The pane on the left-hand side displays available filter rules arranged by their categories in an expandable tree.

For detailed filter rule reference you can either, use the search box to find the rule, or:

  • 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.
Tango-Dialog-information.png
Finding a rule

It can be hard to remember which filter grouping contains a rule. And, since the "addon rule" is a recent innovation, there can be too many rules to peruse easily. So you can narrow down the rule list -- based on keywords from the rule titles.

Type a keyword by using the search box (box with the magnifying glass) and only the groupings with matches will be expanded.

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.

See also Which filters in which Category?

Which filter rules in which Category?

Depending on the used Category, you will get a different set of filter rules. Also see Summary of Gramplets.

  • Dashboard Category
    no filter rules available
  • Sources, Repositories, and Notes Category
    rules for only General filters available

Ancestral filters

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

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.

Ancestor of <person>

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.

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.

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.

Ancestor of bookmarked people not more than <N> generations away

Ancestor of the default person not more than <N> generations away

The ”default person” is the individual that has been defined as the ”Home Person”. (The ”default” is a legacy term in Gramps that caused minor confusion she nice the word is used in so many different parts of the wiki to describe different things.)


Duplicate ancestors of <person>

Matches people that are ancestors twice or more of a specified person

People with 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.

People with a common ancestor with <person>

This rule matches people who have common ancestors with the specified person.

Child filters

This rule category finds families having children that match the rule:

Families having child with id containing <text>

Matches families where child has a specified Gramps ID

Families with child with the <name>

Matches families where child has a specified (partial) name

Families with twins

Matches families with two (or more) children having a 'Birth' role for the Relationship to the Mother and the same birthdate.

Citation/source filters

These filter rules are view dependent

People-, and Relationships Category

This category includes the following citation and source rules:

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 the <citation>

Matches people with a citation of a particular value

People with the <source>

Matches people who have a particular source. values: Source ID

Person with at least one direct source >= <confidence level>

Families Category

This category includes the following citation and source rules:

Families with <count> sources

Matches families with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to

Families with at least one direct source >= <confidence level>

Matches families with at least one direct source with confidence level(s)

Families with the <citation>

Matches families with a citation of a particular value

Families with the <source>

Matches families who have a particular source. values: Source ID

Events Category

This category includes the following citation and source rules:

Events with <count> source

Matches events with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to

Events with at least one direct source >= <confidence level>

Matches events with at least one direct source with confidence level(s)

Events with source matching the <source filter>

Events with the <citation>

Matches events with a citation of a particular value

Places Category

This category includes the following citation and source rules:

Place with <count> sources

Matches places with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to

Place with a direct source >= <confidence level>

Matches places with at least one direct source with confidence level(s)

Place with the <citation>

Matches places with a citation of a particular value

Places with the <source>

Matches places who have a particular source. values: Source ID

Media Category

This category includes the following citation and source rules:

Media with <count> sources

Matches media with a certain number of items in the source. Values: Number of instances -- Number must be greater than/lesser/equal to

Media with a direct source >= <confidence level>

Matches media with at least one direct source with confidence level(s)

Media with the <citation>

Matches media with a citation of a particular value

Media with the <source>

Matches media who have a particular source. values: Source ID

Descendant filters

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

Descendant family member of <filter> match

Matches people that are descendants or the spouse of anybody matched by a filter

Descendant family member of <person>

This rule not only matches people who are descendants of the specified person, but also those descendants' spouses.

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.

Descendant of <person>

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.

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.

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.

Event filters

These filter rules are view dependent

People-, and Relationships Category

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

Families with incomplete events

This rule matches people missing date or place in any family event of any of their families.

People with incomplete events

This rule matches people missing date or place in any personal event.

People with the <birth data>

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.

People with the <death data>

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.

People with 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.

People with 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.

Persons with events matching the <event filter>

Matches persons who have events that match a certain event filter. Values: Event filter name.

Witnesses

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.

Families Category

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

Families with the <event>

This rule matches families that have a 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.

Family filters

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

Adopted people

This rule matches adopted people.

Children 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.

Parents 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.

People missing parents

Matches people that are children in a family with less than two parents or are not children in any family.

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 with 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.

Siblings 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.

Spouses 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.

Father filters

This rule category finds families having fathers that match the rule:

Families having father with Id containing <text>

Matches families whose father has a specified Gramps ID

Families with father with the <name>

Matches families whose father has a specified (partial) name

General filters

These filter rules are view dependent

People-, and Relationships Category

This category includes the following general rules:

Bookmarked people

Matches the people on the bookmark list.

Home person

Matches the Home Person.

Disconnected People

Matches people that have no family relationships to any other person in the database.

Everyone

Matches everyone in the family tree 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 <text>

Matches people whose notes contain text matching a regular expression

People marked private

Matches people that are indicated as private.

People matching the <filter>

Matches people matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

People not marked private

Matches people that are not indicated as private

People probably alive

Matches people without indications of death that are not too old. Values: On Date

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 id containing <text>

Matches people whose Gramps ID matches the regular expression

People with a nickname

Matches people with a nickname

People with an alternate name

Matches people with an alternate name

People with incomplete names

Matches people with first-name or last-name 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 type>

Matches people with a type of name

People with the <Surname origin type>

Matches people with a surname origin

People with the <name>

Matches people with a specified (partial) name. Values: Given Name -- Family Name -- Suffix -- Title -- Prefix -- Patronymic -- Call Name

People with <tag>

Matches people with a tag of a particular value. Values: Tag name.

People with the family <attribute>

Matches people with the family attribute of a particular value. Use RegEx pattern matching to search for all values or attributes that have been left blank. Values: Family Attribute: Identification Number -- Age ...

People with the personal <attribute>

Matches people with the personal attribute of a particular value. Use RegEx pattern matching to search for all values or attributes that have been left blank. Values: Personal Attribute: Identification Number -- Age ...

People with unknown gender

Matches all people with unknown gender.

People without a known birth date

This General filter in the People category will matches people without a known birth date.

This rule includes both Persons without any birth-type event and Persons with undated Birth-type events.

People without a known death date

Matches people without a known death date.

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 during a particular time period. Used to identify records that were imported or modified during particular work-sessions.

Filtering based on specified date and timestamp being after a particular timestamp in the format yyyy-mm-dd hh:mm:ss. This filter rules will look for records modified within a date range, if a second date-time is given.

Values:

 Changed after: 
 but before: 

Values must be after January 1st, 1970 at UTC. Future dates until 3001-01-01 01:59:59 are valid.

The People changed after <date time> filter rules are available in the General filters section for custom rules in the People, Relationships, Charts, and Geography views.

Equivalent rules exist for records of the corresponding category type in People, Families, Events, Places, Sources, Citations, Repositories, Media, and Notes category views.

Soundex match of People with the <name>

Soundex Match of people with a specified name. First name, Surname, Call name, and Nickname are searched in primary and alternate names.

This rule compares names of People against a phonetic pattern. It uses the Soundex phonetic algorithm for indexing names by sound, as pronounced in English.

Match criteria can be a Soundex code (which can be found with the Soundex Gramplet) consisting of of a letter followed by three numerical digits: the letter is the first letter of the name, and the digits encode the remaining consonants. But if the match criteria is not a valid Soundex code, the filter will simply generate Soundex code for the word entered.

All name fields (and the separate words within those fields) are searched individually against the Soundex code.

Families Category

This category includes the following general rules:

Ancestor families of <family>

Bookmarked families

Matches the families on the bookmark list.

Descendant families of <family>

Every family

Matches every family in the database.

Families changed after <date time>

Matches families 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:.

Families having <count> notes

Matches families having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to

Families having notes containing <text>

Matches families whose notes contain text matching a regular expression

Families marked private

Matches families that are indicated as private.

Families matching the <filter>

Matches families matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Families with <count> LDS events

Matches families with a certain number of LDS events. Values: Number of instances -- Number must be greater than/lesser/equal to

Families with <count> media

Matches families with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to

Families with id containing <text>

Matches families whose Gramps ID matches the regular expression

Families with a reference count of <count>

Matches families with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Families with the <tag>

Matches families with a tag of a particular value. Values: Tag name.

Families with the family <attribute>

Matches families with the family attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...

Families with the relationship type

Matches families with the relationship type of a particular value

Families with <id>

Matches families 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.

Events Category

This category includes the following general rules:

Event with <id>

Matches events 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.

Events changed after <date time>

Matches events 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:.

Events having <count> notes

Matches events having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to

Events having notes containing <text>

Matches events whose notes contain text matching a regular expression

Events marked private

Matches events that are indicated as private.

Events matching the <filter>

Matches events matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Events occurring on a particular day of the week

Matches events occurring on a particular day of the week

Events of persons matching the <person filter>

Matches events of person matched by the specified person filter name

Events of places matching the <place filter>

Matches events that occurred at places that match the specified place filter name

Events with <count> media

Matches events with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to

Events with

Matches events with data of a particular value

Events with Id containing <text>

Matches events whose Gramps ID matches the regular expression

Events with a reference count of <count>

Matches events with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Events with the <tag>

Matches events with a tag of a particular value. Values: Tag name.

Events with the attribute <attribute>

Matches events with the attribute of a particular value. Values: Family Attribute: Identification Number -- Age ...

Events with the particular type

Matches events with the particular type

Every event

Matches every event in the database.

Places Category

This category includes the following general rules:

Every place

Matches every place in the database.

Place with <Id>

Matches places 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.

Places changed after <date time>

Matches places records changed after a specified date-time (yyyy-mm-dd hh:mm:ss) or in the range, if a second date-time is given: Values: Changed after: -- but before:.

Places enclosed by another place

Places having <count> notes

Matches places having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to

Places having notes containing <text>

Matches places whose notes contain text matching a regular expression

Places marked private

Matches places that are indicated as private.

Places matching a title

Matches places with a particular title

Places matching parameters

Matches places with particular parameters

Places matching the <filter>

Matches places matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Places of events matching the <event filter>

Matches places where events happened that match the specified event filter name

Places with <count> media

Matches places with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to

Places with Id containing <text>

Matches places whose Gramps ID matches the regular expression

Places with a reference count of <count>

Matches places with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Places with the <tag>

Matches places with a tag of a particular value. Values: Tag name.

Sources Category

This category includes the following general rules:

Every source

Matches every source in the database.

Source with <Id>

Matches sources 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.

Sources changed after <date time>

Matches sources 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:.

Sources having <count> notes

Matches sources having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to

Sources having notes containing <text>

Matches sources whose notes contain text matching a regular expression

Sources marked private

Matches sources that are indicated as private.

Sources matching the <filter>

Matches sources matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Sources with <count> Repository references

Matches sources with a certain number of repository references

Sources with <count> media

Matches sources with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to

Sources with Id containing <text>

Matches sources whose Gramps ID matches the regular expression

Sources with a reference count of <count>

Matches sources with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Sources with repository reference containing <text> in "Call Number"

Matches sources with a repository reference containing a substring in 'Call Number'

Sources with repository reference matching the <repository filter>

Matches sources with a repository reference that match a certain repository filter

Sources with the <tag>

Matches sources with a tag of a particular value. Values: Tag name.

Sources with title containing <text>

Matches sources whose title contains a certain substring

Citations Category

This category includes the following general rules:

Citation with <Id>

Matches citations 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.

Citations changed after <date time>

Matches citations 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:.

Citations having <count> notes

Matches citations having a certain number of notes: Values: Number of instances -- Number must be greater than/lesser/equal to

Citations having notes containing <text>

Matches citations whose notes contain text matching a regular expression

Citations marked private

Matches citations that are indicated as private.

Citations matching parameters

Matches citations with particular parameters

Citations matching the <filter>

Matches citations matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Citations with <count> media

Matches citations with a certain number of items in the gallery. Values: Number of instances -- Number must be greater than/lesser/equal to

Citations with Id containing <text>

Matches citations whose Gramps ID matches the regular expression

Citations with Volume/Page containing <text>

Matches citations whose Volume/Page contains a certain substring

Citations with a reference count of <count>

Matches citations with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Citations with a source with a repository reference matching the <repository filter>

Matches citations with a source with a repository reference that match a certain repository filter

Citations with source matching the <source filter>

Matches citations with sources that match the specified source filter name

Citations with the <tag>

Matches citations with a tag of a particular value. Values: Tag name.

Every citation

Matches every citation in the database.

Repositories Category

This category includes the following general rules:

Every repository

Matches every repository in the database.

Repositories changed after <date time>

Matches repository 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:.

Repositories having notes containing <text>

Matches repositories whose notes contain text matching a regular expression

Repositories marked private

Matches repositories that are indicated as private.

Repositories matching the <filter>

Matches repositories matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Repositories with Id containing <text>

Matches repositories whose Gramps ID matches the regular expression

Repositories with a reference count of <count>

Matches repositories with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Repositories with name containing <text>

Matches repositories whose name contains substring

Repositories with the <tag>

Matches repositories with a tag of a particular value. Values: Tag name.

Repository with <Id>

Matches repositories 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.

Media Category

This category includes the following general rules:

Every media object

Matches every media object in the database.

Media object with <Id>

Matches media objects 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.

Media objects changed after <date time>

Matches media object 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:.

Media objects having notes containing <text>

Matches media objects whose notes contain text matching a regular expression

Media objects marked private

Matches media objects that are indicated as private.

Media objects matching parameters

Media objects matching the <filter>

Matches media objects matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Media objects with Id containing <text>

Matches media objects whose Gramps ID matches the regular expression

Media objects with a reference count of <count>

Matches media objects with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Media objects with the <tag>

Matches media objects with a tag of a particular value. Values: Tag name.

Media objects with the attribute <attribute>

Matches media objects with the attribute of a particular value

Notes Category

This category includes the following general rules:

Every note

Matches every note in the database.

Note with <Id>

Matches notes 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.

Notes changed after <date time>

Matches notes 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:.

Notes containing <text>

Matches notes contain text matching a regular expression

Notes marked private

Matches notes that are indicated as private.

Notes matching parameters

Matches notes with particular parameters

Notes matching the <filter>

Matches notes matched by the specified filter name. Values: Filter name. The specified filter name should be selected from the menu.

Notes with Id containing <text>

Matches notes whose Gramps ID matches the regular expression

Notes with a reference count of <count>

Matches notes with a certain number of references. Values: Number of references -- Number must be greater than/lesser/equal to

Notes with the <tag>

Matches notes with a tag of a particular value. Values: Tag name.

Notes with the particular type

Matches notes with the particular type

Mother filters

This rule category finds families having mothers that match the rule:

Families having mother with Id containing <text>

Matches families whose mother has a specified Gramps ID

Families with mother with the <name>

Matches families whose mother has a specified (partial) name

Position filters

This rule category finds Places by their Global Positioning System coordinates proximity:

Places in neighborhood of given position

Matches places with latitude or longitude position in a rectangle of given height and width (in degrees), and with middle point the given latitude and longitude.

Places with no latitude or longitude given

Matches places with empty latitude or longitude

Places within an area

Source filters

This rule category finds Citations that match the rule:

Citation with Source <Id>

Matches a citation with a source with a specified Gramps ID

Citations having source notes containing <text>

Matches citations whose source notes contain a substring or match a regular expression

Citations with Source Id containing <text>

Matches citations whose source has a Gramps ID that matches the regular expression

Sources matching parameters

Matches citations with a source of a particular value

Relationship filters

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

People related to <Person>

Matches people related to a specified person

Relationship path between <person> and people matching <filter>

Searches over the database starting from a specified person and returns everyone between that person and a set of target people specified with a filter. This produces a set of relationship paths (including by marriage) between the specified person and the target people. Each path is not necessarily the shortest path.

Relationship path between <persons>

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.

Relationship path between bookmarked persons

Matches the ancestors of bookmarked individuals back to common ancestors, producing the relationship path(s) between bookmarked persons.

Tagging

The concept of tagging for most people using gmail or thunderbird, the Tag feature will seem quite familiar. Instead of classifying emails into folders like in Outlook (Windows) or Evolution (Linux), emails are classified by assigning tags to them. So instead of having a disjoint N:1 classification (a email can be in one and only one folder, and a folder can contain many emails), in gmail or thunderbird there is a N:M classification (where a email can have several tags, and a tag can be applied to several emails)

Likewise, when you have a big tree, you might want to make subsets of the tree, and these subsets might be overlapping. For example, the subsets of your fathers family and your mothers family, some subset of your family that emigrated to Australia.

Gramps-tag.png

The idea is to assign a different tag to each subset: Paternal, Maternal, Australia and ToDo for example.

The differences with Gramps previous Markers are like the folders for emails. A person can be given at most one marker. Tags are thus are like multiple-valued markers.

Go to the Menu Edit ->Tag.

Fig. 16.8 Tag actions from Edit menu


Or click the Toolbar 16x16-gramps-tag.pngTag button.

Fig. 16.9 Available Tag actions from "Tag selected rows" Toolbar icon - drop down menu overview - example


See also Tag Report

New Tag dialog

Fig. 16.10 Attaching a "New Tag" to multiple list entry selections - example with "New Tag" dialog

You are able to add a new tag either a single or multiple list entries from any of the list views, by making the selection and then using the New Tag dialog.



Tagging a selection of objects

Due to the static nature of tags, it might be useful to add a tag to a selection of objects. For example one should be able to select a number of person in the Person View, and add them a new tag or an existing one.

Organize Tags Window

Fig. 16.11 Organize Tags - dialog - example

The order in the Organize Tags dialog defines the priority for coloring rows in the category views.



Tag selection dialog

Fig. 16.12 Tag selection in the Person Editor

When you use 16x16-gramps-tag.pngEdit the tag list button from any of the Editor dialogs like Person Edit the Tag selection dialog list is shown that lets you remove or assign existing custom tags. The tags are shown in alphabetical order.

Usage of tags

Here are a some ideas of operations that can be done with tags

Filtering

Fig. 16.13 Gramps Filter SideBar - Tag list example

The most obvious use is that of filtering.

  • Tags and filters both create subsets of the tree. However they have practical differences in usage.

Specifying your fathers family using filters is an easy thing; there are already filters based on some logic's that do it. On the other hand, specifying the people that emigrated to the USA is harder, while for the famous people in your family it is simply impossible as there is no logical rule. Tags are much more practical here.

However filters have the advantage of being dynamical. If you add an ancestor of your father in the database, it will be automatically added to the filter.

On the other hand, tags are static. When adding a famous person in the tree, you have to explicitly tag them as FAMOUS.

  • The most immediate object that comes to mind are the individuals, and that is also the most useful. However, other objects could be tagged:
    • Places: For example "places to visit",
    • Source: For example "sources in german",
    • Notes: For example "notes in progess", or "notes in german",
    • Media: For example "Picture belonging to Uncle Alfred".

Tags are available to use with all primary objects.

Tags Column

Fig. 16.14 People (List) View - Showing "Tag" column and colored tag rows - example

To easily see your tags, you can use the Column Editor to add the Tags column to the list views of objects. The content is then displayed as a comma-separated list of the tags of the objects.

Tags Usage Report

The Tag Usage Report lists primary objects (person, family, notes) having the selected Tag.

See also



Previous Index Next
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: [https://www.gramps-project.org/...]), not via internal links.
Also, only use the known Typographical conventions