Place format editor: help regarding levels


I’ve been made aware of the Place format editor thanks to another recent Gramps thread I don’t want to hijack here.

Actually, I don’t understand the “level” part of it, despite empirical tests from my side (on Charts view) and the following wiki description:

Levels: The place names to be displayed.

Each level in the hierarchy is represented by a positive integer, starting with 0 for the selected place and increasing by 1 for each level up the hierarchy. The levels can also be represented by negative integers, starting with -1 for the top level (usually a country) and decreasing by 1 for each level lower in the hierarchy. In addition, the populated place (city, town, village or hamlet) is represented by the letter p; this can be used with an offset (e.g. p+1 or p-2).

The names to be displayed are defined as a comma-separated list of ranges. A range can either be a single level, or a start level and an end level separated by a colon. The start level must be less than the end level in a range. The start and end levels default to 0 and -1 if missing.

My place hierarchy is the following (the large majority of my database is France-centric):
Country > Region > French Department > City or Village > Hamlet (if need be)

Could some people take multiple examples regarding “levels” and explain them to me based on my hierarchy please?
Then I will do more tests and verify the results match the explanations on my Gramps/database.

Thanks in advance :slight_smile:


  • GRAMPS : 5.1.2
  • Python : 3.7.3 (default, Jan 22 2021, 20:04:44)
  • BSDDB : 6.2.6 (5, 3, 28)
  • sqlite : 3.27.2 (2.6.0)
  • LANG : fr_FR.UTF-8
  • System : Linux
  • Distribution : 5.10.0-0.bpo.4-amd64

The first thing to note is that your example hierarchy is in “Reverse Display Order” (as the Place Format Editor describes it) with the breadcrumbs¹ for each Level separated by greater-than symbols rather than commas.

¹Breadcrumb trail navigation

The way I’m wrapping my brain about the ± sign is: the positive index means counting breadcrumbs from Left-to-Right (normal reading order) while a negative index means counting breadcrumbs from Right-to-Left (like Arabic or Hebrew reading order).

I need to investigate what “double negative” situation applies when Reverse Display Order is selected. They might cancel or be independent.

Thanks for your answer.

I’ve used greater-than signs but this is only for this Discourse thread. This doesn’t appear on Gramps of course. Do I need to change something?

Just to be clear, below is an example of my hierarchy (tell me if you have difficulties to understand because it’s in french):

Well, this Place format applies to the Place Title. That is a text string (styled as a CSV breadcrumb trail) interpretation of the hierarchy.

So I assumed you were describing your place tree hierarchically with the ‘>’ breadcrumbs.

I think that we need to separate the Title in our discussion to avoid getting tangled & tripped up.

Since the Grouping (or categorization) of Levels is in the future, I’m also choosing to think of these as ‘Relative’ paths… where there’s no base path defined.

So the Levels only have internal positional consistency. To anything outside the Program, there is no guaranteed frame of reference, no starting point.

In fact, there isn’t even a base path from the root of the Place Tree.

You can create a snarled mess of a Tree.

You can have one branch of the Place Tree that follows the Postal hierarchy of places. But then simultaneously have another branch with a socially defined tree… where the country might be divided in timezones & ‘greater metro areas’. A top level branch might start at a continent while another branch starts with the name of the region where you grew up. You would have to figure out the base path by context.

And, like Windows, you cut drop in shortcuts that transparently transport you to another part of the Tree. Relativity by M. C. Escher crossbred with Lewis Carroll’s rabbit holes!

Okay, I did some more testing;

The numbering starts at either 0, the smallest place record, or -1, the largest. So having a single number in the Level field displays that place record within the hierarchy. Negative and positive numbers are needed because within any given place record’s hierarchy there can be a varying number of levels.

Separating place levels by a comma (,) tells Gramps to display those place records within the normal hierarchy.

Using a colon (:) tells Gramps to display all places in the hierarchy before or after the number entered (excluding the numbered level).

p stands for Populated place. City, Town, Village or Hamlet.

Some examples of possible use using a normal hierarchy as an example: Country, State, County, City, Locality (within a City)

  • p, -2 = City, State

  • p-1: = City, County, State, Country (excludes any locality entries)

  • :p+1 = Locality, City

  • :p+1, -2 = Locality, City, State

The key to remember is what the number represents within any hierarchy; and each hierarchy will be different. p-1 is the next smallest place record (from the Populated Place); p+1 is the next largest.

And as I pointed out, Gramps 5.2 will offer a major reworking of how a user can manipulate the Place Name display.

It seems that those four types are hard-coded in the logic (see _find_populated_place in I have some places for which I entered custom place types based on the types used in GOV (for example, “Ortschaft”). Those get missed when I try to use the place formatting levels. I will wait for 5.2 before I think about changing anything.

1 Like

I translated (google) “Ortschaft”. It came back as “Locality” which is a standard Gramps type. I understand place Type translations are an issue resulting in multiple types having the same translation. This may be causing your hack not being recognized.

And I just looked at the code. The _find_populated_place in gen\display\ uses Gramps’ defined types from gen\lib\ If your place type is not “defined” can it be used for this definition?

1 Like

Thanks Dave. I suspect that my places with this custom type are ignored in this case not because the descriptions translates to “Locality” (Gramps would not know that anyway, since I’m running it as English and not German), but merely because it is a custom type.

I don’t think there’s a way I can map additional values to one of the standard types. To clarify my point, remove the coincidental language difference, and suppose I wanted to have a type “Suburb” that I could map to one of the place type values for City, Town, Village, or Hamlet (i.e. 4, 15, 16, 17) so that it would be considered a “populated place”; I don’t think that’s possible.

And that’s fine, I’ll wait for 5.2 and see what I can do with it.

Thank you everyone for your answers.

I think I get it but why this behavior of exclusion please:

? I mean, this is not very intuitive…

I don’t know if my Gramps version (5.1.2) or my implementation of places is buggy but I have confusing results that I can’t explain from the theory above…

Here is my hierarchy:
France (country),Occitanie (region),Lozère (french department),Saint-Chély d'Apcher (city)

I have a Death event in the complete place:
Saint-Chély d'Apcher, Lozère, Occitanie, France

My understanding is the following:

  • Saint-Chély d’Apcher = 0 = p = -4
  • Lozère = 1 = -3
  • Occitanie = 2 = -2
  • France = 3 = -1

Now I’m playing with the place format editor and here are the strange results:

  • p-1,4 => France
  • p-1: => France
  • p-2 => Occitanie

Can you explain me those results please?
As I don’t have anything below p, it looks like a loop now (p-1 = -1, p-2 = -2…)

Thanks in advance :slight_smile:

I did some more testing by creating a new tree with just your example. I am on 5.1.3 and I got all the same results.

As I said earlier, this is a crude operation and this entire function will hopefully be replaced in version 5.2 where the Place Type or a Grouping will be more important than a position in any hierarchy given that not all hierarchies will have the same depths.

So in this example the various place components can be resented as in the Level field::

  • Country -1 or 3
  • Regions -2 or 2
  • Department -3 or 1
  • City -4 or 0 or p

For most truncation of the place display, limiting the options to City, State (p, -2) or City, Country (p, -1) should probably be the desired result. In these cases p for the populated place with the negative number counting down from the top as best making all intervening levels (regardless of how many levels) hidden.

One of the confusing usage is the Populated Place p. As a stand alone entry (with no number) it will display the City, Town, Village or Hamlet. wherever that place occurs in the hierarchy. These entries may not always be 0 or -4.

When p is used with a number (p-1), for most place records, the record based upon the number will display. The exception, will be when the normal full displayed name includes locality entries for places within the populated place.

With my level settings as p-1: this is what displays for one person’s event list.

Because not every place record includes a locality entry, very different results occur.

So until more user customization is allowed in 5.2, I will limit my use of this functionality to graphical type of reports/views where the people are limited and they all share a common place structure.

So no bug, it is just a matter of understanding the function’s existing limitations.