Contenido del repositorio de origen con títulos, ejemplos, código, tablas, enlaces e imágenes preservados.
BioHousekeeper Skill
Turns a messy biodiversity spreadsheet into a Darwin Core-aligned structure through analysis plus a short, targeted conversation - never a silent bulk rewrite.
Setup
cd /path/to/biohousekeeper
pip install -r requirements.txtUsage
/biohousekeeper analyze <spreadsheet>
python scripts/analyze.py my_spreadsheet.xlsx
python scripts/analyze.py my_spreadsheet.xlsx --sheet "Occurrences"
python scripts/analyze.py data.csv --out-dir ./reportReads the file (first sheet by default for .xlsx; other sheets are listed but not analyzed - pass --sheet to pick one), inspects both column names and sample cell values, and writes two files next to --out-dir (default: current directory):
<name>_biohousekeeper_report.md- human-readable report: column mapping table, proposed transformations, missing recommended fields, open questions<name>_biohousekeeper_report.json- the same findings as a plan, with anapply/auto_applyflag per suggestion, consumed byapply.py
The original spreadsheet is never modified by either script.
What you (the agent) do after running analyze.py
- Read the generated Markdown report and present the column mapping table and proposed transformations to the user.
- Walk through the
questionsarray in the JSON one at a time (not all at once) - these are the cases the heuristics could not resolve alone:
- a "coordinates split" needs no question (deterministic,
auto_apply: true) - a binomial
scientificNamesplit intogenus/specificEpithetalways asks for confirmation - regex-based epithet extraction can be wrong on cultivars, hybrids, or "sp." records - a delimited locality column asks the user to name each part left-to-right (e.g.
country,stateProvince,municipality) - order is dataset-specific and cannot be inferred - a suspected duplicate column asks which one to drop
- Record the user's answers by editing the plan JSON directly:
- set
"apply": true(orfalse) on the relevant column entry or operation - for
split_locality, fill in"targets"with the DwC term list the user gave you, in order (use"skip"for a part that maps to nothing)
- Ask whether the user wants a corrected file. If yes, run
apply.py; if no, the report alone stands as the deliverable.
apply.py - write the corrected spreadsheet
python scripts/apply.py my_spreadsheet.xlsx --plan my_spreadsheet_biohousekeeper_report.json --output my_spreadsheet_corrected.xlsxExecutes, in order: date-parts merges, coordinate splits, taxon epithet derivation, locality splits, redundant-column drops, then column header renames. Only operations/columns with apply: true (or their heuristic auto_apply: true default, if untouched) run. --output must differ from the input path - the original file is always preserved.
Detection heuristics (what analyze.py looks for)
| Finding | Signal | Confidence |
|---|---|---|
| Column already named or synonym of a DwC term | Name match against references/dwc_terms.csv + a EN/PT/ES synonym dictionary | high -> auto-applies |
| Partial name match only | Substring match against DwC term list | low -> asks for confirmation |
Packed coordinate pair ("−23.5,−46.6") | Column name hints at coordinates + delimited values both numeric and in valid lat/lon range | high -> auto-applies, original kept as verbatimCoordinates |
Binomial scientific name ("Panthera onca") | Column maps to scientificName (or name hints at species) + values match a Genus species pattern | medium -> always asks |
Delimited locality hierarchy ("Brazil / SP / Campinas") | Column name hints at locality + a consistent delimiter splits most rows into 2-5 parts | low -> always asks which DwC term each part represents |
| Separate year/month/day columns | Three columns with valid year/month/day ranges | high -> auto-applies, merges into ISO 8601 eventDate |
| Redundant duplicate columns | Two columns match in ≥95% of overlapping non-null rows | medium -> always asks which to drop |
| Missing recommended field | occurrenceID, basisOfRecord, scientificName, eventDate, decimalLatitude/decimalLongitude, recordedBy, country absent from the mapped terms | advisory note only, not a blocking error |
Only column-level renaming and single-column split/merge/drop operations are in scope. BioHousekeeper does not attempt full DwC-DP multi-table normalization (splitting a flat sheet into separate event/occurrence/taxon tables) - use the darwin-core skill's DwC-DP guide for that.
References
- `references/dwc_terms.csv` - flat list of 216 current Darwin Core terms, vendored from the TDWG `dwc` repository
Related Skills
[darwin-core](../darwin-core/) - once BioHousekeeper's report and corrected spreadsheet exist, use darwin-core to validate the result, generate a full DwC-A/DwC-DP package, or look up the precise definition of any DwC term the report suggested.
