magicsunday/webtrees-statistics

This module provides SVG-based statistics for the [webtrees](https://www.webtrees.net) genealogy application.

Maintainers

Package info

github.com/magicsunday/webtrees-statistics

Type:webtrees-module

pkg:composer/magicsunday/webtrees-statistics

Fund package maintenance!

paypal.me/magicsunday

Statistics

Installs: 4

Dependents: 0

Suggesters: 0

Stars: 7

Open Issues: 7

Security

Advisories: 0

Aikido package health analysis

1.5.0 2026-06-06 13:08 UTC

Requires

Requires (Dev)

GPL-3.0-or-later 418a9c93d3ca6d192e4abe37c5d293424e423920

modulechartstatisticwebtrees

This package is auto-updated.

Last update: 2026-06-07 15:39:15 UTC

README

Latest version License CI

Statistics

This module provides a six-tab statistics dashboard for the webtrees genealogy application. Above the tabs a dark hero strip carries the tree title and six headline metrics; the tabs themselves group cards thematically per topic (Overview, Names, Life span, Family, Places, Tree health) and render their data through donut / line / bar / stacked / population-pyramid / chord / sankey / stream / world-map / name-bubbles / month-radial / mirror-histogram / gauge / box-plot / heatmap / treemap / event-timeline widgets from the shared @magicsunday/webtrees-chart-lib.

Installation

Requires webtrees 2.2 and PHP 8.3 or later.

Manual installation

Important

Download the right .zip file. Each GitHub release page lists two kinds of archive:

  • ✅ webtrees-statistics.zip — listed under Assets at the bottom of the release. This is the install-ready archive: it bundles the required vendor/ dependencies (such as webtrees-module-base).
  • ❌ "Source code (zip)" / webtrees-statistics-<version>.zip — auto-generated by GitHub from the tag. This is the raw source without bundled dependencies. Uploading it to modules_v4/ will fail with Trait/Interface "MagicSunday\Webtrees\ModuleBase\…" not found.

Always pick the asset zip, never "Source code (zip)".

Important

If a previous version of this module is already installed: delete the entire modules_v4/webtrees-statistics folder before extracting the new ZIP. Extracting on top of an existing folder leaves stale files behind that can clash with the new release — a common cause of Interface … not found errors right after an update.

  1. Open the latest release page.
  2. Under Assets, download webtrees-statistics.zip.
  3. Upload the .zip file to your web server.
  4. Unzip the package into your modules_v4 directory.
  5. Rename the folder to webtrees-statistics.

You should now see a modules_v4/webtrees-statistics directory containing the module files.

Using Composer

Run the following command from the root of your webtrees installation:

composer require magicsunday/webtrees-statistics --update-no-dev

The module will automatically install into the modules_v4 directory.

To remove the module:

composer remove magicsunday/webtrees-statistics --update-no-dev

If you are using the development version of webtrees (main branch):

composer require magicsunday/webtrees-statistics:dev-main --update-no-dev

Using Git

Clone the repository into your modules_v4 directory (a Code → Download ZIP of the source works the same way):

git clone https://github.com/magicsunday/webtrees-statistics.git modules_v4/webtrees-statistics

A source checkout contains the module code only — it does not include the shared webtrees-module-base library, so on its own it fails with Trait "MagicSunday\Webtrees\ModuleBase\…" not found. Supply that library in one of two ways:

Way A — drop-in (no code change). Download webtrees-module-base and copy its src/ to the location this module's module.php already expects:

modules_v4/webtrees-statistics/vendor/magicsunday/webtrees-module-base/src/…

Way B — shared copy (one edit). Place webtrees-module-base next to this module in modules_v4/ (rename the extracted folder to webtrees-module-base), then point this module's module.php at it. A single shared copy then serves every magicsunday module installed this way:

// modules_v4/webtrees-statistics/module.php
$loader->addPsr4(
    'MagicSunday\\Webtrees\\ModuleBase\\',
    __DIR__ . '/../webtrees-module-base/src'
);

Important

Both ways are overwritten by every module update, so you must redo them after each upgrade. For a maintenance-free install without Composer, use the asset zip (it bundles all dependencies). Inside a Composer-managed webtrees, prefer composer require magicsunday/webtrees-statistics:dev-main — see Using Composer.

Update

To update to the latest version:

  • Manual installation: From the latest release Assets section, download webtrees-statistics.zip (not "Source code (zip)"), delete the old modules_v4/webtrees-statistics folder first, and extract the new one. Extracting on top of an existing folder leaves stale files behind that can clash with the new release (a common cause of Interface … not found errors after an update).
  • Composer: Run composer update magicsunday/webtrees-statistics --update-no-dev.
  • Git: Run git pull inside the modules_v4/webtrees-statistics directory, then re-apply your source step (see Using Git).

Configuration

  1. Go to the Control Panel (admin section) of your webtrees installation.
  2. Scroll down to the Modules section and click on Charts (under Genealogy).
  3. Enable the Statistics module. Optionally disable the built-in statistics chart to avoid the menu carrying both.
  4. Click Save.

Usage

Open the Charts menu on any tree page and select Statistics.

The module renders six tabs that aggregate tree-wide data into widget cards:

Tab What it shows
Overview Demographics (sex / living / marital donuts), cumulative tree growth over time, top occupations and religions, father → son occupation-inheritance sankey, tree-records hall-of-fame
Names Surname / male / female name bubbles, given-name popularity stream graph, same-sex name passdown, surname × surname marriage chord matrix
Life span Births by century / month / zodiac, age-at-death bands + boxplot per century, living life-stages, lifespan by sex × century, survival curve, top-10 oldest deceased and living, deaths by century / month, winter-peak score, death causes, child mortality (under 5) + peak century, mortality-outlier years, same-year sibling deaths, births / deaths by 25-year period × month heatmaps
Family Age at marriage M+F, marriage duration, couple age gap, weddings by century / month, age at first child + mean by decade, first children by month, children per family, sibling age gap, family-size composition by decade, average family size, multiple-birth rate, childless donut, top-10 largest families, top-10 by grandchildren, sex-ratio anomalies, divorce cohort rate, divorces by month / century / age band, widowhood interval, mourning period, shortest & longest marriages
Places Birth / residence / death countries with top-10 list and choropleth world map, birth → death migration sankey, geographic dispersion, distinct-places-per-individual and migration-distance metrics
Tree health Core-vs-enrichment data-set inventory + media files by type, source-citation coverage (tree-wide + per birth century), pedigree completeness, average generation length, missing-event gaps, max generation depth + distribution, known-ancestors distribution, endogamy rate, most-influential ancestors, largest unconnected sub-trees, tree type

The marital-status donut counts each living individual exactly once — precedence follows the same per-family decision order webtrees core uses in \Fisharebest\Webtrees\Census\AbstractCensusColumnCondition: an active divorce tag classes the survivor as divorced, a deceased partner as widowed, an active marriage with a living partner as current. Anything else falls into single.

The dashboard ships with light- and dark-mode visuals; the module reads data-bs-theme on the <html> element, so themes that toggle dark mode automatically style the charts too.

Troubleshooting

Fatal error after a manual installation or update: Trait/Interface "MagicSunday\Webtrees\ModuleBase\…" not found (or ModuleAssetUrlInterface not found)

  • You probably downloaded the GitHub-generated "Source code (zip)" (or used Code → Download ZIP) instead of the install-ready asset webtrees-statistics.zip. The asset bundles the required vendor/ dependencies; the source zip does not. Open the latest release, scroll to Assets, download webtrees-statistics.zip, and re-extract.
  • If you used the asset zip, make sure you deleted the previous modules_v4/webtrees-statistics folder before extracting. Stale files from an older version can shadow the new bundled vendor code and produce the same error.

The Statistics menu entry is missing

  • Make sure the module is enabled in the Control Panel under Modules > Charts.
  • Check that your PHP version is 8.3 or later.

Charts do not render / tabs are empty

  • Clear your browser cache and reload the page.
  • Open the browser developer console — a missing widget bundle usually surfaces as a MIME type or 404 error on /index.php?route=…&asset=js/statistics-<version>.min.js.

The world map shows every country in the empty colour

  • Make sure the tree's place data uses recognisable country names — the world-map widget matches free-text country labels to ISO-3166-1 alpha-2 codes across nine pre-seeded locales plus the active webtrees language; unmatched labels fall back to the empty fill.

Development

This section is for developers who want to contribute to the module.

Building JavaScript

Using Docker (no local Node.js required):

make install
make build

Using local Node.js:

npm install
npm run prepare

Running tests

# JavaScript tests
npm test

# Full PHP + JS quality check
composer update
composer ci:test