Tutorial 1 builds the LSUMZ Mammalogy WorkBench sheet inside NAHPU with an export preset. This tutorial produces the same sheet outside the app: you export a NAHPU Data Package and convert it with a ready-made script in Python or R.
Use this route when:
- the data needs checking or cleaning in a script before it goes to Specify;
- someone without NAHPU on their device prepares the upload;
- you want a reproducible, versioned record of how the sheet was made.
Both scripts live in the lsumz-mammal-specify-frictionless repository. They read the package with the Frictionless library for each language and write identical CSV files.
Before you start
Seção intitulada “Before you start”You need:
- a NAHPU project with mammal specimen records;
- uv, Python 3.10 or newer with pip, or R with permission to install packages;
- a copy of the repository, cloned with Git or downloaded as a ZIP from GitHub.
Set up your computer covers each of these.
The repository is organized like this:
Directorydata/
- country-continent.csv
Directoryexample/
- ambang-shrews.nahpu-dp.zip
- expected-specify.csv
Directorypython/
- nahpu_to_specify.py
Directorytests/
- …
DirectoryR/
- nahpu_to_specify.R
Directorytests/
- …
Directoryresults/
- …
Set up your computer
Seção intitulada “Set up your computer”Do this once per computer. The commands run in a terminal: Terminal on macOS, PowerShell on Windows, or your distribution's terminal on Linux.
Get the repository
Seção intitulada “Get the repository”With Git:
git clone https://github.com/nahpu/lsumz-mammal-specify-frictionless.gitcd lsumz-mammal-specify-frictionlessWithout Git, open the repository on GitHub, select Code, then Download ZIP, extract the archive, and open a terminal in the extracted folder.
Install the tools
Seção intitulada “Install the tools”Choose uv or pip for Python, or install R. uv is the simpler route: it installs a suitable Python version and the script's packages for you.
Install uv.
On macOS or Linux:
Janela do terminal curl -LsSf https://astral.sh/uv/install.sh | shOn Windows, in PowerShell:
Janela do terminal powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"With a package manager, use
brew install uvon macOS orwinget install --id=astral-sh.uv -eon Windows.Close and reopen the terminal, then check the installation:
Janela do terminal uv --versionFrom the repository folder, install the script's dependencies:
Janela do terminal cd pythonuv syncuv downloads Python 3.10 or newer if your computer does not have it and creates a virtual environment in
python/.venv. Prefix Python commands withuv runto use it; you do not need to activate it.
Install Python 3.10 or newer.
- Windows: download the installer from python.org and select
Add python.exe to PATHon its first screen. - macOS: download the installer from python.org, or run
brew install python. - Linux: install Python with your package manager, for example
sudo apt install python3 python3-venv python3-pipon Debian or Ubuntu.
- Windows: download the installer from python.org and select
Check the installation. Use
python3on macOS and Linux andpyon Windows:Janela do terminal python3 --versionFrom the repository folder, create a virtual environment so the packages stay separate from other Python projects:
Janela do terminal python3 -m venv .venvOn Windows, run
py -m venv .venv.Activate the environment.
On macOS or Linux:
Janela do terminal source .venv/bin/activateOn Windows, in PowerShell:
Janela do terminal .venv\Scripts\Activate.ps1The prompt now starts with
(.venv), andpythonpoints to the environment on every platform. Activate it again each time you open a new terminal.Install the script's dependency:
Janela do terminal python -m pip install frictionless
Check that
Rscriptruns from a terminal:Janela do terminal Rscript --versionOn Windows, if the command is not found, add R's
binfolder, such asC:\Program Files\R\R-<version>\bin, to yourPATH, or run the commands from an R session instead.Install the packages listed in step 2.
1. Export the NAHPU Data Package
Seção intitulada “1. Export the NAHPU Data Package”- Open the project menu and select
Bundle records. - Set
Bundle formattoNAHPU Data Package. - Keep
TAR.GZor chooseZIPas theArchive format. The scripts read both. - Name the file, choose a folder, and select
Create bundle. - Copy the file, such as
ambang.nahpu-dp.tar.gz, into the repository'sdata/folder.
2. Try the bundled example
Seção intitulada “2. Try the bundled example”Run a converter once without arguments. It converts data/example/ambang-shrews.nahpu-dp.zip and writes results/ambang-shrews-specify.csv, which should match data/example/expected-specify.csv, five rows of the real LSUMZ incoming sheet.
With uv, from the python/ folder:
uv run python nahpu_to_specify.pyWith pip, from the repository folder with .venv activated:
python python/nahpu_to_specify.pyInstall the packages once from an R session:
install.packages(c( "frictionless", "here", "dplyr", "tidyr", "readr", "purrr", "stringr", "lubridate", "testthat"))Then run from the repository root:
Rscript R/nahpu_to_specify.RIf the result matches the expected file, your setup works.
3. Convert your package
Seção intitulada “3. Convert your package”Pass your package as the first argument. The sheet is written to results/ under the package name.
With uv, from the python/ folder:
uv run python nahpu_to_specify.py ../data/ambang.nahpu-dp.tar.gzWith pip, from the repository folder with .venv activated:
python python/nahpu_to_specify.py data/ambang.nahpu-dp.tar.gzAdd -o PATH to choose the output file, and --all-taxa to keep specimens outside the mammal taxon groups.
Rscript R/nahpu_to_specify.R data/ambang.nahpu-dp.tar.gzA second argument sets the output file, and --all-taxa keeps specimens outside the mammal taxon groups. In an R session, source the script and call the function instead:
source(here::here("R", "nahpu_to_specify.R"))sheet <- nahpu_to_specify( here::here("data", "ambang.nahpu-dp.tar.gz"), here::here("results", "ambang-specify.csv"))sheet is a tibble, so you can check it with dplyr before uploading.
The scripts also accept an extracted package folder or its datapackage.json.
4. Check the sheet
Seção intitulada “4. Check the sheet”Open the CSV and compare a few specimens with their NAHPU records:
SexreadsMaleorFemale. The scripts decode the stored code with the package'smappings/sqlite_enums.csv.Continentis filled fromCountry. A country missing fromdata/country-continent.csvleaves it blank and prints a warning; add the country to that file and run again.Collector1LastNamereadsLast, First. The last word of the cataloger's name is moved to the front, so check two-word family names.Start Dateis the specimen's collection date asdd/mm/yyyy.- Each part fills one
PrepTypegroup, with its storage location, such as a freezer box position, inPrepTypenLocation.Remarksfollows the second group, as on the LSUMZ sheet. - A measurement in brackets, such as
[150], means its accuracy note marks it as unreliable, the same rule theLSUMZ-mammalogypreset from Tutorial 1 uses.
5. Upload to Specify
Seção intitulada “5. Upload to Specify”Import the CSV as a new WorkBench data set, apply the LSUMZ Mammalogy upload plan, validate, and upload, as in Tutorial 1. The columns are the same, so the same upload plan works for sheets from either route.
How the conversion works
Seção intitulada “How the conversion works”Each script follows the package's relational tables:
- It keeps specimens whose
taxonGroupis Mammals, General Mammals, or Bats. - It joins
taxonomythroughspeciesID,mammalAttributethrough the specimen UUID, and the cataloger inpersonnel. - It finds the locality through the collecting event's site and its
geographyrow. - It uses the specimen's own coordinate, or the site's coordinate when the site has exactly one, as NAHPU does.
- It spreads
specimenPartrows into numberedPrepTypecolumns in part order.
Empty NAHPU tables are left out of a Data Package, so the scripts treat a missing table as empty rather than failing. To adapt the scripts to another collection's sheet, change the column lists at the top of either file. For a different layout altogether, write your own script as in Tutorial 3.