Family Statistics

Family Statistics is a small genealogy statistics project for Gramps.

The purpose is to show some of the same types of statistical information that are available in Gramps, but on a private family history website.

The project uses four HTML reports exported from Gramps. A Python script reads these reports and creates statistics.json, which is then displayed by index.html using JavaScript.

Important: Gramps must use English

Gramps must be running in English, and the date format must be YYYY-MM-DD (ISO) when the reports are created.

The Python script depends on specific English report headings and English month names when reading the exported HTML files. Reports generated in another language may therefore not be parsed correctly.

What is displayed

The statistics page is divided into four sections:

On this day

Shows events occurring on today's date:

• Birthdays
• Wedding anniversaries
• Death anniversaries

The newest events are shown first.

Counts

Shows:

• Persons
• Men
• Women
• Unknown gender
• Persons without a birth date
• Families

It also shows record lists for:

• Father with most children
• Mother with most children
• Couple with most children
• Father with most grandchildren
• Mother with most grandchildren

Age

Shows lifespan statistics:

• Minimum
• Average
• Maximum

It also shows record lists for:

• Youngest living person
• Oldest living person
• Person died at youngest age
• Person died at oldest age
• Person married at youngest age
• Person married at oldest age
• Couple with smallest age difference
• Couple with biggest age difference

Names

Shows the ten most frequent:

• First names
• Last names

Each entry shows the percentage first and the number of persons afterwards.

Filters and tags

The examples use a Gramps person tag named ProfileTag.

You may use your own filter and tag, but the tag must contain the same set of persons as the filter used for the reports.

A guide for creating a person tag from a filter is available here:

Create a tag from a filter – step 3

The selected tag name is read from the Gramps Tag Report and is shown dynamically on the statistics page, for example:

Selected filter: ProfileTag

Requirements

• Gramps 5.2 or later
• Gramps running in English when the reports are created
• Date format YYYY-MM-DD (ISO) for the reports that contain date fields
• Python 3.x
• Python package beautifulsoup4

Install BeautifulSoup if needed:

python -m pip install beautifulsoup4

Tested on

Tested with:

• Gramps 6.0.8 on Windows 11
• Gramps 6.0.8 on Zorin OS 18.1 Core

macOS has not been tested.

Files

The package contains:

index.html
LICENSE
README.md
RELEASE_NOTES.md
statistics.py
statistics.css
statistics.js

example/
    index.html

The example folder contains a standalone demonstration page that can be opened directly in a web browser before creating your own reports.

The example index.html is created specifically for preview purposes. It contains its own embedded CSS, JavaScript and fictional example data, so it does not use statistics.json and does not require localhost or a web server.

The normal index.html in the main folder still uses statistics.json and must be opened through localhost or a web server.

How it works

Four Gramps reports are first exported as HTML:

1. Complete Individual Report
2. Tag Report
3. Records report
4. Birthday and Anniversary Report

All four files must be saved in the same folder as statistics.py.

The required filenames are:

complete.html
tag.html
records.html
birthdays.html

After the reports have been created, statistics.py reads them and creates:

statistics.json

The statistics page then reads statistics.json.

Creating the Gramps reports

1. Complete Individual Report

Open Gramps and open the family tree you want to use.

Go to:

Reports / Text Reports / Complete Individual Report...

Use these settings:

• In Report Options, Select your own filter.
• In Report Options(2), select YYYY-MM-DD (ISO) for the date format (Important)
• Under Include, leave all options unselected.
• Under Include(2), select Do not include Gramps ID and leave the other options unselected.
• Under Sections, select only Family.
• Set the output format to HTML.
• Save the file as complete.html in the same folder as statistics.py.

2. Tag Report

Go to:

Reports / Text Reports / Tag Report...

Use these settings:

• Select your own person tag.
• The tag must contain the same persons as the filter used for the other reports.
• Select YYYY-MM-DD (ISO) for the date format (Important)
• Set the output format to HTML.
• Save the file as tag.html in the same folder as statistics.py.

3. Records report

Go to:

Reports / Text Reports / Records report...

Use these settings:

• Select your own filter.
• Select all options under the Person 1 tab.
• Select all options under the Person 2 tab.
• Select all options under the Family 1 tab.
• Set the output format to HTML.
• Save the file as records.html in the same folder as statistics.py.

4. Birthday and Anniversary Report

Open the Birthday and Anniversary Report.

Use these settings:

• Select your own filter.
• Under Birthday Surname, select: Wives use husband's surname (from last family listed)
• Set the year to the current year.
• Select: Include birthdays, anniversaries and deaths
• Set the output format to HTML.
• Save the file as birthdays.html in the same folder as statistics.py.

Create statistics.json

When all four reports have been created, close the family tree and Gramps.

Open the working folder in a terminal and run:

python statistics.py

The script reads:

birthdays.html
complete.html
records.html
tag.html

and creates:

statistics.json

View the statistics locally

Because index.html loads statistics.json using JavaScript, the page should be opened through a local web server rather than directly as a file.

Open the working folder in a terminal and run:

python -m http.server 8000

Then open a web browser and go to:

http://localhost:8000/index.html

Stop the local server when you are finished by returning to the terminal and pressing:

Ctrl+C

Updating the statistics

When the family tree changes, create the four Gramps reports again using the same filenames and run:

python statistics.py

This replaces statistics.json with updated data.

The generated date is displayed on the page, for example:

Data updated August 23, 2026