Skip to content

Bundle Records

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.

FormatChoose it whenIt holdsNAHPU can import it
Darwin Core Archive (.dwca.zip)A museum database or biodiversity portal (such as GBIF) asks for a DwC-ASpecimens as one flat core table, with parts, measurements, and media in extension tablesNo
Darwin Core Data Package (.dwc-dp.tar.gz)The recipient supports the newer relational Darwin Core standardSpecimens, events, identifications, parts, and people in linked Darwin Core tablesNo
NAHPU Data Package (.nahpu-dp.tar.gz)You need everything for R or Python analysis, long-term archiving, or a full project copyThe complete project, every populated NAHPU table, user configs, and filesYes, 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.

  1. Open the project Dashboard menu and select Bundle records.
  2. Choose a Bundle format B.
  3. Choose an Archive format C when the format supports more than one container:
    • TAR.GZ is the default for Data Packages.
    • ZIP is available for tools and operating systems that prefer standard ZIP archives.
    • Darwin Core Archive always uses ZIP.
  4. For a Darwin Core bundle, select All taxa A or Selected taxa. Selecting Mammals also includes Bats.
  5. Enter a File name D (optionally turn on Append date) and choose a destination folder on desktop.
  6. Inspect Package contents E (under the Contents tab on phones). Expand any CSV resource F to inspect its columns.
  7. Review any warnings, such as missing media or the DwC-DP ZIP compatibility notice.
  8. Select Create bundle G. You can cancel while the bundle is being built. Once finished, share, open the folder, save a copy, or select Bundle another.
ContainerTypical extensionsNotes
TAR.GZ.dwc-dp.tar.gz, .nahpu-dp.tar.gzDefault 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.zipRequired for Darwin Core Archive; normal option for NAHPU Data Package; compatibility option for DwC-DP (triggers a warning because DwC-DP guidance prefers gzip).

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.

A Darwin Core Archive (DwC-A) is a specimen-focused exchange package following the Darwin Core Text Guidelines.

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.

  • meta.xml
  • eml.xml
  • occurrence.csv
  • material.csv
  • measurement_or_fact.csv
  • multimedia.csv
  • Directorymedia/
    • …

Only files backed by selected data are written:

  • meta.xml describes the occurrence core, extension files, column positions, and Darwin Core term URIs.
  • eml.xml holds dataset-level metadata.
  • occurrence.csv is always the core table.
  • Extension rows link back to the occurrence core: specimen parts become material.csv records, measurements become measurement_or_fact.csv records, and multimedia.csv rows reference both the occurrence and the packaged path under media/.

Output: <file-name>.dwca.zip.

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.

  • 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.

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);
  • agent and *-agent-role: people and their roles (preferring canonical ORCID URLs with NAHPU UUIDs as fallback);
  • media and occurrence-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 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.

  • 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.

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.

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, and specimenIndividual), using explicit stable codes where legacy codes 0, 1, and 2 keep 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.

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.

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.toml records the format name and version, export timestamp, application name/version/build number, database and user-config schema versions, table/enum/vocabulary counts, and compiled nahpu_api crate versions (nahpu_dp, nahpu_dwc, nahpu_db, nahpu_configs, and others).
  • configs/user_configs.json holds the versioned user-config export (general settings, record-export presets, document templates, and print-layout presets).
  • media/ and files/ carry referenced project media, referenced personnel photos (under media/ with transfer-compatible paths), and custom user fonts (under files/). 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.

Darwin Core bundleNAHPU Data PackageDatabase backup
Restores a NAHPU projectNoYes (Import project or Merge project)Yes (entire installation)
Primary purposeExchange with biodiversity systemsDocumented, reusable copy of one projectFull 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.

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.