Large screen
Small screen
Use Bundle records to package project data alongside its metadata and media for publishing, archiving, or reproducible analysis. Before writing anything, Package contents shows every file, record count, column, and warning.
Choose a bundle format
Section titled “Choose a bundle format ”| Format | Choose it when | It holds | NAHPU can import it |
|---|---|---|---|
Darwin Core Archive (.dwca.zip) | A museum database or biodiversity portal (such as GBIF) asks for a DwC-A | Specimens as one flat core table, with parts, measurements, and media in extension tables | No |
Darwin Core Data Package (.dwc-dp.tar.gz) | The recipient supports the newer relational Darwin Core standard | Specimens, events, identifications, parts, and people in linked Darwin Core tables | No |
NAHPU Data Package (.nahpu-dp.tar.gz) | You need everything for R or Python analysis, long-term archiving, or a full project copy | The complete project, every populated NAHPU table, user configs, and files | Yes, via Import project or Merge project |
Darwin Core bundles include only values with an exact, registered Darwin Core, Dublin Core, or Audubon Core term. Choose a NAHPU Data Package when nothing may be left out, including custom fields. Any Frictionless tool can read it; see Tutorial 3.
Create a bundle
Section titled “Create a bundle”- Open the project
Dashboardmenu and selectBundle records. - Choose a
Bundle formatB. - Choose an
Archive formatC when the format supports more than one container:TAR.GZis the default for Data Packages.ZIPis available for tools and operating systems that prefer standard ZIP archives.- Darwin Core Archive always uses
ZIP.
- For a Darwin Core bundle, select
All taxaA orSelected taxa. Selecting Mammals also includes Bats. - Enter a
File nameD (optionally turn onAppend date) and choose a destination folder on desktop. - Inspect
Package contentsE (under theContentstab on phones). Expand any CSV resource F to inspect its columns. - Review any warnings, such as missing media or the DwC-DP ZIP compatibility notice.
- Select
Create bundleG. You can cancel while the bundle is being built. Once finished, share, open the folder, save a copy, or selectBundle another.
Choose an archive container
Section titled “Choose an archive container”| Container | Typical extensions | Notes |
|---|---|---|
TAR.GZ | .dwc-dp.tar.gz, .nahpu-dp.tar.gz | Default for Data Packages and the standards-oriented choice for DwC-DP. Extracts datapackage.json and root metadata at the archive root. |
ZIP | .dwca.zip, .dwc-dp.zip, .nahpu-dp.zip | Required for Darwin Core Archive; normal option for NAHPU Data Package; compatibility option for DwC-DP (triggers a warning because DwC-DP guidance prefers gzip). |
Deep dive
Section titled “Deep dive”The sections below describe what each bundle writes and how NAHPU maps records into it. Use them when a recipient asks about package structure or when you process a package in scripts.
Darwin Core Archive
Section titled “Darwin Core Archive ”A Darwin Core Archive (DwC-A) is a specimen-focused exchange package following the Darwin Core Text Guidelines.
Scope and field coverage
Section titled “Scope and field coverage”The selected taxon groups determine which specimen occurrences are exported. NAHPU follows links from those specimens to include related collecting events, specimen parts and material entities, measurements, media, and people (collectors, catalogers, preparators, and media creators). Empty optional fields and empty extension tables are omitted.
A column is written only when it has an exact, registered Darwin Core, Dublin Core, or Audubon Core term; fields without one are omitted. Package contents lists any withheld fields before export. Use a NAHPU Data Package when every recorded value must be preserved.
Root files and relationships
Section titled “Root files and relationships”- meta.xml
- eml.xml
- occurrence.csv
- material.csv
- measurement_or_fact.csv
- multimedia.csv
Directorymedia/
- …
Only files backed by selected data are written:
meta.xmldescribes the occurrence core, extension files, column positions, and Darwin Core term URIs.eml.xmlholds dataset-level metadata.occurrence.csvis always the core table.- Extension rows link back to the occurrence core: specimen parts become
material.csvrecords, measurements becomemeasurement_or_fact.csvrecords, andmultimedia.csvrows reference both the occurrence and the packaged path undermedia/.
Output: <file-name>.dwca.zip.
Darwin Core Data Package
Section titled “Darwin Core Data Package”A Darwin Core Data Package (DwC-DP) represents Darwin Core data as normalized, relational tables under the Darwin Core Data Package specification and the Frictionless Data Package model.
Root files
Section titled “Root files”- datapackage.json
- eml.xml
- occurrence.csv
- identification.csv
- event.csv
- material.csv
- occurrence-assertion.csv
- media.csv
- agent.csv
- occurrence-agent-role.csv
- event-agent-role.csv
- material-agent-role.csv
- media-agent-role.csv
- occurrence-media.csv
Directorymedia/
- …
Optional tables appear only when data exist. datapackage.json identifies the versioned DwC-DP profile and declares every CSV resource, media type, field order, primary key, foreign key, and relationship predicate. Structural _pk and _fk columns preserve relational links alongside human-readable IDs.
Data mapping
Section titled “Data mapping”NAHPU maps specimen data into normalized classes rather than repeating fields on occurrence.csv:
occurrence: the specimen occurrence;identification: determination and taxonomic ranks;event: collecting activity and locality context;material: specimen parts, catalog, and preparation details;occurrence-assertion: measurements and non-class assertions (such as host association);agentand*-agent-role: people and their roles (preferring canonical ORCID URLs with NAHPU UUIDs as fallback);mediaandoccurrence-media: media metadata and links.
The same strict term-coverage rule applies as for DwC-A. Original DDM, DMS, or UTM strings stay in verbatim-coordinate terms, positive capture extent adds to coordinate uncertainty, and selected weight units are preserved.
For invertebrates, sex, life stage, caste, host association, and specimen remarks are occurrence terms; host part and optional morphometrics (head width, body length, upper and lower wingspan) export as MeasurementOrFact assertions in millimetres. Canopy cover and environmental parameters attach to the collecting event with defined units (°C, %, mg/L, m/s, mm, okta).
Output: <file-name>.dwc-dp.tar.gz (default) or <file-name>.dwc-dp.zip (compatibility option, with a warning).
NAHPU Data Package
Section titled “NAHPU Data Package ”NAHPU Data Package is NAHPU's complete-data and reproducibility format—a Frictionless Data Package enriched with NAHPU metadata. Unlike Darwin Core bundles, it is not filtered by taxon group: it bundles the full active-project transfer JSON, matching typed CSV tables, enum mappings, controlled-vocabulary snapshots, user configs, and associated files.
It is the only bundle that preserves custom fields without a Darwin Core term. Only tables populated by the project are exported (a mammals-only project carries no bird, herpetofauna, invertebrate, or fish tables), and mappings/sqlite_enums.csv lists only the enum columns of those populated tables.
Root layout
Section titled “Root layout”- datapackage.json
- nahpu.toml
- nahpu-project.json
Directorytables/
- project.csv
- ...
Directoryconfigs/
- user_configs.json
Directorymappings/
- sqlite_enums.csv
Directoryvocabularies/
- site.csv
- events.csv
- specimens.csv
- symbionts.csv
Directoryfiles/
- ...
Directorymedia/
- ...
Empty project tables are omitted from tables/ and datapackage.json, while metadata resources (mappings/sqlite_enums.csv and vocabularies/*.csv) are always present—with header rows only if empty.
Project JSON and CSV tables
Section titled “Project JSON and CSV tables”nahpu-project.json is the same versioned payload created by Export project (active project, related records, media manifest, metadata, and warnings), preserving distinctions like null versus an empty string without requiring SQLite. The CSV files under tables/ are generated from the same payload so JSON and tables stay aligned; empty collections stay in nahpu-project.json for project transfer even when omitted as CSVs.
SQLite enum mappings
Section titled “SQLite enum mappings”mappings/sqlite_enums.csv decodes integer enum indexes stored in the exported tables. Each row records the SQLite table, column, Dart enum or logical type, zero-based integer index, stable code name, and human-readable NAHPU label.
Included mappings (filtered to the populated tables in the package) cover:
- specimen sex (
mammalAttribute,birdAttribute,herpAttribute,invertebrateAttribute,fishAttribute, andspecimenIndividual), using explicit stable codes where legacy codes0,1, and2keep their original meanings; - identification confidence (
specimen.iDConfidence); - fish specimen type (
Individual/Lot) and invertebrate caste; - mammal reproductive fields and echolocation categories;
- avian reproductive and molt fields.
Boolean integers and numeric measurements are not enum indexes and are not listed.
Controlled vocabularies
Section titled “Controlled vocabularies”Four CSV resources snapshot the active controlled vocabularies from NAHPU Settings (or NAHPU defaults if unchanged):
vocabularies/site.csv: site types and habitat types;vocabularies/events.csv: collecting methods and collecting personnel roles;vocabularies/specimens.csv: specimen types, treatments, conditions, enabled specimen-sex options, identification methods, and life stages;vocabularies/symbionts.csv: symbiont interaction types, categories, detection methods, preparation methods, anatomical locations, storage, and treatments.
Each row records the config key, vocabulary name, zero-based position, and value, so analysis tools can read vocabularies directly without parsing configs/user_configs.json.
Frictionless descriptor and analysis
Section titled “Frictionless descriptor and analysis”datapackage.json uses the standard data-package profile, declaring each populated table as a UTF-8 tabular-data-resource with column order, types, required constraints, primary keys, and foreign keys, along with schemas for the enum-mapping and vocabulary CSVs and entries for non-tabular resources.
Extract the archive before loading datapackage.json, because paths are relative to the package root. Check whether an optional table exists before reading it:
from collections import Counter
from frictionless import Package
package = Package("/path/to/extracted-package/datapackage.json")print(package.resource_names)
if package.has_resource("specimen"): specimens = package.get_resource("specimen").read_rows() counts = Counter(row["taxonGroup"] or "Unspecified" for row in specimens) print(counts)library(frictionless)
package <- read_package("/path/to/extracted-package/datapackage.json")resource_names(package)
if ("specimen" %in% resource_names(package)) { specimens <- read_resource(package, "specimen") print(table(specimens$taxonGroup, useNA = "ifany"))}Reproducibility manifest, configs, and files
Section titled “Reproducibility manifest, configs, and files”nahpu.tomlrecords the format name and version, export timestamp, application name/version/build number, database and user-config schema versions, table/enum/vocabulary counts, and compilednahpu_apicrate versions (nahpu_dp,nahpu_dwc,nahpu_db,nahpu_configs, and others).configs/user_configs.jsonholds the versioned user-config export (general settings, record-export presets, document templates, and print-layout presets).media/andfiles/carry referenced project media, referenced personnel photos (undermedia/with transfer-compatible paths), and custom user fonts (underfiles/). Missing files trigger warnings rather than failing silently.
Output: <file-name>.nahpu-dp.tar.gz (default) or <file-name>.nahpu-dp.zip, with identical internal contents.
Bundle versus backup
Section titled “Bundle versus backup”| Darwin Core bundle | NAHPU Data Package | Database backup | |
|---|---|---|---|
| Restores a NAHPU project | No | Yes (Import project or Merge project) | Yes (entire installation) |
| Primary purpose | Exchange with biodiversity systems | Documented, reusable copy of one project | Full device recovery |
A NAHPU Data Package covers one project only, so continue making regular database backups for full-device recovery.
Contributors extending bundle fields or taxon groups can consult Export workflows and Adding a taxon group.
Package validation and warnings
Section titled “Package validation and warnings”Before writing, NAHPU validates required fields and relationships; afterward, it reopens the archive to confirm root metadata exist. Warnings—such as missing linked media or DwC-DP ZIP compatibility mode—do not always block export, so review them before sharing or depositing the bundle.


