NeoIPC Surveillance Toolkit

Everything a neonatal department needs in order to take part in NeoIPC surveillance, and everything the project needs in order to analyse what they collect: the surveillance protocol and its case definitions, the DHIS2 configuration that gathers the data, the reference lists of infectious agents and antimicrobial substances, and the reports that give each participating department its results.

NeoIPC works to reduce the transmission of resistant bacteria in neonatal intensive care across Europe and globally. Its surveillance system collects healthcare-associated infection and antimicrobial-use data from neonatal departments so that a department can compare itself against the network. This repository is the normative source for that surveillance: when a case definition changes here, the change propagates to the data-collection forms, the analysis code and the reports. Where code and the definitions in this repository disagree, the definitions win.

What's in here

Path	Contents
doc/protocol/	The NeoIPC Core Surveillance Protocol in AsciiDoc, including the eight normative case definitions under definitions/ — clinical sepsis, the two laboratory-confirmed bloodstream-infection variants, the three surgical-site-infection depths, necrotizing enterocolitis and pneumonia.
metadata/	The canonical DHIS2 configuration for the NEOIPC_CORE tracker program — data elements, option sets, program rules, tracked-entity attributes and the organisation-unit scaffold — authored as reviewable per-type CSVs plus externalized expression files rather than one opaque JSON blob. See metadata/common/README.md.
metadata/common/infectious-agents/	The NeoIPC Infectious Agent List — a pragmatic ontology of organisms with their synonyms and phenotypic resistance categories, named from LPSN, MycoBank and ICTV. Licensed separately; see below.
metadata/common/antibiotics/	The NeoIPC Antibiotics List — substances, groups and WHO AWaRe categories. Licensed separately; see below.
reports/	Five Quarto reports, drawing their data from the neoipcr R package: the Partner Report a department receives, the network-wide Reference Report, a Validation Report that flags data-quality problems, a Partner Certificate, and a Patient Data Report answering data-subject access requests.
po/	The gettext catalogues behind every localized artifact, managed with po4a and translated on Weblate.
glossary.yaml	The controlled vocabulary the reports and translators share, so one concept reads the same way everywhere.
scripts/	PowerShell entry points — Build-*.ps1 render an artifact, Test-*.ps1 check an invariant, Invoke-Localization.ps1 drives the translation pipeline. Shared logic lives in the NeoIPC-Tools module.
docs/	Design references for the pieces whose reasoning does not fit in a source comment — the metadata pipeline and its deployment to DHIS2, the infectious-agent ontology, the Weblate component contract.

Products and releases

The repository publishes five independently versioned products from one shared history, each with its own version file, tag stream and releases:

Product	Tag prefix
NeoIPC Core Surveillance Protocol	protocol-v*
NeoIPC DHIS2 Metadata Package	metadata-v*
NeoIPC Surveillance Reports	reports-v*
NeoIPC Infectious Agent List	infectious-agents-v*
NeoIPC Antibiotics List	antibiotics-v*

The infectious-agent and antibiotics lists are shared inputs: the protocol compiles them and the metadata package embeds them as option sets, so both declare the exact list release they incorporate and CI refuses a release that would ship unreleased list content. RELEASING.md has the full mechanics.

To install NeoIPC into a DHIS2 instance you want the metadata package — a JSON release asset, with a synthetic play variant for test instances. It is a generated artifact and is deliberately not committed; metadata/dist/README.md explains where to get it and how to deploy it.

That package is alpha — expect to adapt it rather than deploy it unchanged. Its version is the one in metadata/VERSION, which is what the release tag carries. It does not yet follow the WHO dhis2-package-exporter sharing and manifest conventions: DHIS2 takes it because it ignores the manifest key it does not recognize, not because the package conforms. It also attaches the program to no organisation units, so the hierarchy is yours to build and connect.

Deploy it with NeoIPC-Tools' Deploy-NeoIPCMetadata, which is verified on DHIS2 2.40.12, 2.41.10, 2.42.6 and 2.43.1; earlier 2.40 patches are not supported, 2.40.3.2 in particular carrying a confirmed defect that was fixed in 2.40.4. On an earlier patch of those lines, or on another line, the deployment stops before writing anything unless -AllowHazard UnverifiedVersion accepts the release. A plain metadata import is no substitute: in one request DHIS2 can leave an option group set without its groups while reporting success, and repeated over an existing instance it fails from 2.42 on. docs/metadata-deployment.md explains why and describes a production deployment.

Working with the toolkit

The tooling is PowerShell 7.6 or newer plus, depending on what you are building, R and Quarto (reports), Asciidoctor PDF and Pandoc (protocol), or po4a (translations). Every script carries comment-based help, so Get-Help ./scripts/Build-PartnerReport.ps1 -Full is the reference for its arguments.

git clone --recurse-submodules https://github.com/NeoIPC/Surveillance-Toolkit.git
cd Surveillance-Toolkit

The --recurse-submodules matters only for translation work: tools/po4a is a submodule, and the localization pipeline needs it.

doc/README.md lists the prerequisites for building the protocol documents and how to install them on Windows and Ubuntu. On Windows, po4a runs under the Windows Subsystem for Linux — it does not run natively.

Part of the NeoIPC surveillance system

Repository	Role
Surveillance-Toolkit	(this repository) The protocol, the case definitions, the DHIS2 metadata and the report sources
neoipcr	R package that reads NeoIPC data out of DHIS2 and computes the surveillance indicators
NeoIPC-Reporting	Service that renders this repository's reports on demand and serves them over HTTP
neoipc-app	DHIS2 application through which people request reports and administer reference data

Surveillance data itself is collected in a DHIS2 instance configured from the metadata package above. The deployment configuration for the NeoIPC network's own instances is maintained privately and contains no part of the definitions — those are all here.

Contributing

Contributions are welcome. Much of this repository is incomplete or thin on documentation, because the tools and the partner network are being built at the same time; issues and pull requests that sharpen either are useful.

CONTRIBUTING.md is the way in. It says which changes go through a pull request and which go through Weblate, and why a pull request touching a translation catalogue is closed before a human sees it. If you are translating, read docs/translating.md first: what each catalogue is and who reads it, the markup that must survive your translation unchanged, what each catalogue is published under, and how review works here.

Two things are worth knowing whichever route you take. Case definitions are normative — a pull request that changes one is a scientific change, not an editorial one, so raise an issue first. And translated text lives in gettext catalogues, not in the source files: change the English string and regenerate, never hand-edit a generated localized file.

Translations are hosted on Weblate, who support this project's translation effort with their software, expertise and free hosting. Contributions in any language are welcome and no git knowledge is needed — the web interface is enough.

Licensing

Except where noted below, this repository is licensed under the MIT License.

Two kinds of exception follow: data directories whose upstream terms are stricter than MIT, and the logos and marks, which are nobody's to license here at all.

Two data directories compile content from upstream sources whose terms are stricter than MIT. The effective license of each is dictated by what its sources permit — not a restriction NeoIPC chose to impose — and each carries its own LICENSE.md with the reasoning and full attribution:

Directory	Effective license	Upstream sources
metadata/common/infectious-agents/	CC BY-NC-ND 4.0 (plus CDC agency-material terms)	NHSN, LPSN, MycoBank, ICTV
metadata/common/antibiotics/	CC BY-NC-SA 3.0 IGO	WHO AWaRe classification / ATC/DDD index

The two directories land on different Creative Commons terms because their upstream licences differ. The infectious-agent list is no-derivatives — its MycoBank source is CC BY-NC-ND, incorporated with permission. The antibiotic list is a derivative of the WHO AWaRe classification (CC BY-NC-SA 3.0 IGO); ShareAlike requires a derivative to keep the same licence, so it is CC BY-NC-SA 3.0 IGO (the ATC codes, substance names and group descriptions it also carries are reproduced unchanged from the WHOCC ATC/DDD index, not adapted). We apply the licence the upstream terms require, no stricter.

Logos and marks

The NeoIPC logo is owned by Fondazione Penta ETS and is not covered by the MIT licence. It is included here because this repository's own documents and reports display it; that is not a grant to anyone else. Confirm any reuse beyond this repository with the NeoIPC/Penta team before publishing.

Path	Rights holder
common/img/NeoIPC-Logo.svg, common/img/NeoIPC-Logo-Horizontal.svg	Fondazione Penta ETS
common/logos/LOGO_NEOIPC.png, LOGO_NEOIPC_2.png	Fondazione Penta ETS
doc/protocol/img/ LOGO_NEOIPC.png, LOGO_NEOIPC_2.png	Fondazione Penta ETS
reports/logos/ LOGO_NEOIPC.png, LOGO_NEOIPC_2.png	Fondazione Penta ETS
reports/logos/ eu-flag.png, eu-flag-hr.jpg	European Union — the emblem is governed by the EU's own conditions of use, not by this licence
common/logos/ by.xlarge.png, cc.xlarge.png	Creative Commons — its trademarks, used to mark licence terms, and not licensed by this repository

A mark is not content. Every entry here is present so that a NeoIPC document can identify itself or credit a funder, and none of them is offered for reuse — which is why they are listed as rights holders rather than as licences.

Fondazione Penta ETS is the organisation's current legal name and the form to use. Not Fondazione Penta ONLUS, which is the pre-2023 designation and still appears in older material.

The notice travels with each file, not only with this table — and each names its own rights holder, not a blanket one. The SVGs carry it as a comment and a <metadata> element; the PNGs as a Copyright text chunk; the one JPEG as a comment segment. All are readable with any image tool. That matters because a logo leaves this repository constantly — pasted into a slide, attached to an e-mail, lifted from a rendered PDF — and at that moment the README is not travelling with it. If a logo file is ever replaced, re-apply the notice: the chunk is spliced in after IHDR without re-encoding the image, so it can be added to a new file without touching a pixel of it.

The gettext translation catalogues under po/ declare their licence in their own headers, and all of them declare CC BY 4.0, matching their templates. Two once did not — the translated reports catalogues carried MIT and the infectious_agents ones CC BY-NC-ND 4.0 — and the templates were the side that had it right: a catalogue of extracted strings is not automatically bound by the licence of the directory it was extracted from, and a no-derivatives term cannot govern a translation, which is a derivative work. Because the translated files are written by the translation platform rather than by this repository, that correction was applied there rather than here, and the same route applies should they ever diverge again.

Funding

The NeoIPC project has received funding from the European Union's Horizon 2020 research and innovation programme under grant agreement No 965328.