Repository navigation
Releases
basinkit 0.9.6
0.9.6 -- 2026-11-18
The same release, published properly
0.9.5 reached PyPI from a build made before the reservoir work was committed:
the uploaded archive carries no regulation.py and reports __version__ as
0.9.4. PyPI does not allow a version to be uploaded twice, so the fix is this
release rather than a corrected 0.9.5. Everything described under 0.9.5 below
is in this one. 0.9.5 on PyPI is yanked; the git tag and its notes stand.
The QGIS plugin now asks for basinkit>=0.9.6, because the 0.9.5 on PyPI is
the build without the feature the plugin's new algorithm calls.
0.9.5 -- 2026-11-18
Reservoirs, and an error bar withdrawn
A delineation is a statement about terrain: it says where water would go if
nothing had been built. envelope.NOT_CHARACTERISED has named regulation
since the validation was published, because the blind run at 2,550 gauges
recorded no degree of regulation for any of them, so no error figure here is
known to have been measured below a dam.
Basin.regulation() measures it. HydroLAKES was already being fetched for
lakes() and carries, per water body, whether it is a reservoir, how much it
holds, and the area draining to it; HydroRIVERS was already being fetched for
rivers() and carries the modelled long-term flow. The arithmetic between
them was the part that was missing. No new dataset, no account, nothing
downloaded that a run was not already downloading.
It returns the reservoirs, their storage, and the degree of regulation --
storage as a share of one year's flow -- in bands that are read rather than
ranked, from "effectively unregulated" to "over-year storage". The Colorado
above Lees Ferry comes back at 212 per cent of a year held behind 61
reservoirs, with 99.6 per cent of the basin draining through one of them. The
Trishuli, run through the same call, comes back at zero: three natural lakes
and no reservoir.
Two numbers are reported where one would mislead. The largest single
reservoir's upstream area is unambiguous. The sum of every reservoir's
upstream area is not an area at all -- reservoirs in series each count the
whole catchment above them, and on the Colorado that sum exceeds the basin --
so it is reported as an upper bound and labelled as one.
Above ten per cent, the output says that basinkit's own published error
figures were measured on gauges whose regulation was never recorded, and that
none of them is known to apply. The honest answer there is not a wider error
bar; it is none. envelope.NOT_CHARACTERISED now points at this call instead
of only naming the gap.
It reports how much water can be held, not how much there is. Operating
rules, release schedules and current storage are decisions and measurements,
and nothing here observes either.
basinkit 0.9.5
0.9.5 -- 2026-11-18
Reservoirs, and an error bar withdrawn
A delineation is a statement about terrain: it says where water would go if
nothing had been built. envelope.NOT_CHARACTERISED has named regulation
since the validation was published, because the blind run at 2,550 gauges
recorded no degree of regulation for any of them, so no error figure here is
known to have been measured below a dam.
Basin.regulation() measures it. HydroLAKES was already being fetched for
lakes() and carries, per water body, whether it is a reservoir, how much it
holds, and the area draining to it; HydroRIVERS was already being fetched for
rivers() and carries the modelled long-term flow. The arithmetic between
them was the part that was missing. No new dataset, no account, nothing
downloaded that a run was not already downloading.
It returns the reservoirs, their storage, and the degree of regulation --
storage as a share of one year's flow -- in bands that are read rather than
ranked, from "effectively unregulated" to "over-year storage". The Colorado
above Lees Ferry comes back at 212 per cent of a year held behind 61
reservoirs, with 99.6 per cent of the basin draining through one of them. The
Trishuli, run through the same call, comes back at zero: three natural lakes
and no reservoir.
Two numbers are reported where one would mislead. The largest single
reservoir's upstream area is unambiguous. The sum of every reservoir's
upstream area is not an area at all -- reservoirs in series each count the
whole catchment above them, and on the Colorado that sum exceeds the basin --
so it is reported as an upper bound and labelled as one.
Above ten per cent, the output says that basinkit's own published error
figures were measured on gauges whose regulation was never recorded, and that
none of them is known to apply. The honest answer there is not a wider error
bar; it is none. envelope.NOT_CHARACTERISED now points at this call instead
of only naming the gap.
It reports how much water can be held, not how much there is. Operating
rules, release schedules and current storage are decisions and measurements,
and nothing here observes either.
0.9.4
cPermanent snow and ice, and where it sits
For a Himalayan, Andean or Alpine catchment this is usually the first question asked and the last one answered. Both layers it needs were already being fetched: ESA WorldCover carries a snow-and-ice class, and the elevation model is in hand for the terrain products. Nothing had put the two together.
Basin.snow_ice() reports the share of the basin under permanent snow and ice, measured by area rather than by counting cells — a cell is 12.3 km2 at the equator and 2.2 km2 at 80 degrees north, and glaciers live at the second latitude — together with the elevation band the ice occupies and how much of the basin lies in it. No new dataset, no account, nothing downloaded that a run was not already downloading.
The first version read the bottom of the ice zone as the minimum elevation of the mapped ice, and the Trishuli said that was wrong. The lowest cell sits at 1,458 m, which is not a Himalayan terminus; 33 cells out of 140,415 — two hundredths of one per cent — lie below 2,000 m, and the lowest of them sits at the basin's own lowest point, at the outlet. The wrong floor also made the share of the basin above it 100 per cent, which says nothing about anything. The floor is now the first percentile: 4,414 m on the same basin, with 67.2 per cent of the catchment above it. The lowest mapped cell is still reported and named as probable misclassification rather than quietly dropped. A statistic one bad cell can destroy is not a statistic, and a caveat in the documentation is not a substitute for not reporting it.
The ice is also crossed against elevation, aspect and slope, which the elevation model already in hand pays for. The elevation split is a snowline read off the map rather than assumed: on the Trishuli it runs from 0.9 per cent of the 4,000 to 4,500 m band to 96.8 per cent above 7,000 m. The aspect split states which way it leans, and where it leans towards the sunlit slopes rather than away from them it says so and names the first suspect — the land-cover map rather than the glaciology, because shaded slopes are the ones a classifier loses. Settling that needs a glacier inventory this does not have. Writing those found a fault of their own: ice whose maximum landed exactly on a band boundary fell outside every band, and the breakdown accounted for 90 per cent of the ice while reporting shares that summed to 90.
Said on every path, because it is the misreading waiting to happen: an ice fraction is not a meltwater fraction. A basin 7 per cent covered by ice does not deliver 7 per cent of its flow from melt. That depends on mass balance and on how much of the ice is in the ablation zone in a given year, none of which is measured here. Outside the 60S to 82.75N that ESA WorldCover covers, the answer says the map has no opinion rather than reporting zero per cent — which is what no data would otherwise be mistaken for, in precisely the basins that have the ice.
Given a BasinATLAS row the answer gains glacier, snow-cover and permafrost extent over the whole upstream area. Those columns are found by prefix rather than by name, and are reported beside the land-cover measurement rather than averaged into it: permanent ice in one mapped year is not mean annual snow cover. Nothing requires the row, because BasinATLAS is a 2.7 GB download and the land-cover map was being fetched anyway.
In QGIS it is the Snow and ice algorithm, which also writes the ice mask as a raster — a number is what a report needs, a layer is what anyone looking at a glacier actually wants.
AGPL-3.0-or-later for the package
Apache-2.0 let anyone take basinkit, close it and sell it — as a product or, more realistically for a delineation engine, as a web service — without giving anything back and without anyone being able to check what that service was actually doing. For software whose whole claim is that you can open it and verify the number, that last part is the contradiction.
The Python package is now AGPL-3.0-or-later. Using it, changing it and publishing with it are unaffected. Distributing a modified version, or letting other people use one over a network, now means those people get the source of that version on the same terms.
Three things deliberately did not change. The QGIS plugin stays GPL-3.0-or-later, which is what the plugin repository requires and what it already was. The ArcGIS Pro toolbox stays Apache-2.0: it is a separate program that runs the package in an interpreter of its own and reads back the files it writes. And every release already published keeps the licence it was published under — MIT through 0.8.4, Apache-2.0 for 0.9.0 to 0.9.3. A licence cannot be withdrawn from a version that is already out, and this does not attempt to.
Verified end to end on the Trishuli at Syabrubesi, 3,198 km2, and on the full test suite: 374 passed.
0.9.3
The answer now carries the accuracy that was measured at its own size
The accuracy published with basinkit is a median per size band, and those medians span two orders of magnitude: 0.3% above 100,000 km2, 1.3% from 10,000 to 100,000, 1.7% from 2,000 to 10,000 — and 30% between 100 and 500, 181% below 100. Both halves have been in the README since the validation was run. Only the first half ever reached the output.
Someone clicking a 135 km2 headwater in QGIS got an area, a boundary and a consistency check, and nothing that said the figure behind the software was measured on basins two orders of magnitude away from theirs. The number was not wrong. It was being quoted about a case it had never been measured on, and the software was the one quoting it.
Basin.validation_envelope() answers the narrower question instead: of the basins that were measured, which ones does this one resemble, and what was the error there. It returns inside, edge or outside, with the band’s own median error and its within-5% and within-20% counts. Reading the area is all it costs, so it downloads nothing.
Given a dem_suitability() result it compares the terrain descriptors too. Those are not new measurements: the five suitability tests are the five numbers recorded beside the area error for 133 of the validation gauges, so each is compared against the range it covered there — the middle 90% separately from the full span, because a value at the 99th percentile was measured by almost nothing and should not read as covered.
Two of those comparisons carry a finding of their own. Within every size band, the fifth of basins whose depression filling was heaviest carried two to three times the median area error of the rest, on three to ten basins per band, which is a direction and not a coefficient. And every basin in the terrain study was fully covered, so a basin with a void in it is outside the set by definition rather than merely unusual.
Aridity, flow regulation and karst are named as uncharacterised rather than quietly omitted. None was recorded in the validation, so no figure here was measured on any of them, and the output says which tool measures each one.
Where it surfaces: Delineate basin prints the band and writes validated and band_err_pct into the output layer’s attribute table, so it survives the dialog closing. Elevation data suitability writes validation_envelope.csv. The report’s uncertainty section states the row instead of pointing at the documentation, and the full-run manifest carries the envelope. The ArcGIS run stays at 70 analyses.
A provenance record that does not have to be believed
The acquisition record added in 0.9.2 said which product a layer came from and when. A repeat study six months later can do nothing with that: if the answer has moved, nothing separates a change of your own from the provider reissuing a tile under the same name and URL.
Every file the cache serves or fetches is now hashed, and each layer record carries the digests of the files that call actually read. The digest is computed once and kept in a sidecar, and HASH_DOWNLOADS turns it off where reproducibility is not the point — a source then reads as unverifiable, never as unchanged. cache.recheck() compares a recorded run against the cache now and answers unchanged, changed, absent or unverifiable.
Every figure in the envelope is recomputed from verify/benchmarks by tests/test_envelope.py, which fails if one drifts from the file it came from. Verified in QGIS 3.34.4 on a real 135 km2 DEM-routed basin.
basinkit 0.9.2
What was fetched, and when it arrived
Asked for by someone planning batch runs over many outlets, reread months later: can the report carry the dataset details through from the acquisition step?
Almost. The sources already tagged every array they handed back — ESA WorldCover 2021 arrives carrying its product, licence, native and output resolution, the resampling used and how many tiles were merged — but nothing kept the tags once the array had been passed on, so the run itself had no record of what it had fetched.
A product name carries an edition. It does not carry a retrieval date, and the two answer different questions: the edition says what was asked for, the date says which bytes arrived. Without the second, a rerun that differs cannot be told apart from the provider reissuing a tile — which is the whole question a repeat study is asking.
Every layer method now returns through an internal recorder that keeps those tags with a UTC timestamp and the arguments that chose the layer. Basin.acquisitions() hands the list back. Records are appended rather than replaced, because fetching a layer twice in one run is a fact about the run.
{"call": "landcover", "retrieved_utc": "2026-10-17T15:10:14+00:00",
"product": "ESA WorldCover 2021", "license": "CC BY 4.0",
"native_res_m": 9.3, "output_res_m": 194.8,
"resampling": "nearest", "coarsen_factor": 21, "tiles_merged": 4}
The list is carried into the full-run manifest as layers_acquired, beside the existing datasets_available — the first says what could be reached, the second what actually was — and the report's provenance page prints it, or says plainly that no layer was fetched through this basin when none was.
A test reads basin.py and fails if a layer method returns without recording, because a recorder is only worth having if nothing routes around it.
Three faults found while wiring it through
HydroRIVERS and HydroLAKES did not name themselves at all. They tagged a licence and nothing else, so their records read {"license": "CC BY 4.0"} with no indication of which dataset that licence belonged to.
The elevation source tagged its route key rather than the dataset, so a provenance line read cop30 — the string a caller types — in place of Copernicus DEM GLO-30, and the report carried a second table of names to translate it back. The catalogue already holds the name and the licence, so the source takes them from there, and the report accepts either spelling because a grid fetched before this change still carries the key.
An argument passed to the recorder overwrote the attribute the source had set. The attributes say what arrived and the arguments say what was asked for; where both name the same thing the arrival now wins, and the request is kept beside it rather than in place of it.
Also
CITATION.cff carries the author's ORCID, which was a row of zeros — worse than absent, because a reader cannot tell a placeholder from a wrong identifier.
CITATION.cff points at the concept DOI again. The version DOI it carried belongs to 0.9.1 and is not true of this release; it is replaced once Zenodo mints one for 0.9.2.
Install: pip install -U "basinkit[delineate]"
QGIS: install basinkit from the Plugins dialog, or use the zip attached here.
Cite: Kaushik, P. (2026). basinkit (Version 0.9.2). Zenodo. https://doi.org/10.5281/zenodo.22181933
basinkit 0.9.1
Two faults in 0.9.0, both found by running the whole analysis set over one basin and then checking every printed figure against the run rather than against the code that produced it.
A grade that could not be measured read as a bad grade
0.9.0 changed precipitation() to return a named DataArray. The quality grader still asked for a column called ppt, did not find one, and fell back to the first column of the frame — which was spatial_ref, a constant. The correlation of a constant is not a number, and the grader turned that into LIMITED. Through the worst-of rule a single ungraded layer then set the whole basin's grade: the Juniata reported LIMITED overall where its rainfall pair actually agrees at r = 0.949, which is HIGH, and the basin is MODERATE.
A layer that could not be measured and a layer that measured badly are not the same finding. The grader now selects the series by name and never falls back to a position; a value that is not a number stays ungraded and says why, and a series shorter than three years is not scored at all rather than scored badly.
An empty CHIRPS result also named latitude coverage as the cause even for basins well inside the covered band. It now names the failures it saw.
The report ran at ten times its own budget inside QGIS
0.9.0 budgeted the report's elevation grid to four megapixels, because a larger one had been killed by the operating system and inside QGIS that takes QGIS with it. The QGIS algorithm passed max_pixels= of its own, though, and its default stood at forty — so the one caller that cannot survive running out of memory was the one caller that ignored the limit.
Measured on the Juniata (8,805 km²) inside QGIS 3.34: 245 seconds and 5.61 GB at forty megapixels, 26 seconds and 1.26 GB at four, for the same eight pages within six kilobytes of each other. The larger grid bought nothing, because every raster a page draws is decimated to 1,600 pixels first.
Fetching the data layers defaulted to a hundred megapixels, about 5.6 GB, past the ceiling the elevation guard enforces — so a large basin was refused outright rather than returned at a coarser resolution. It now asks for sixty, as the three other surface algorithms do.
Two tests pin both defaults, and read the values out of the files so they run where QGIS is not installed.
Smaller things
The notice shown when QGIS runs a Python too old for the package said to update to 3.28, which is the release those readers were already on. It now names 3.34. qgisMinimumVersion stays at 3.28, because the bundled Python belongs to the installer and not to the QGIS version: the Windows and macOS builds of 3.28 shipped Python 3.9, where pip finds no release of basinkit at all, while the Debian and Ubuntu packages of the same QGIS run on 3.11, where it installs normally.
The ArcGIS toolbox README asked readers to cite version 0.8.2.
Checked while fixing the above
Evidence rather than change: all eleven algorithms load into QGIS 3.34.4 and every one of their Processing dialogs builds; a delineation driven from a point given in the canvas CRS, EPSG:3857, reprojects correctly and returns 8,804.7 km² against the 8,686.8 km² published for USGS gauge 01567000.
Install: pip install "basinkit[delineate]"
QGIS: install from the Plugins dialog once 0.9.1 is approved, or use the zip attached here.
Cite: Kaushik, P. (2026). basinkit (Version 0.9.1). Zenodo. https://doi.org/10.5281/zenodo.22181933
basinkit 0.9.0
Delineation that says when it cannot be trusted, and a report that no longer
dies on a large basin.
New
- Forcing a known channel.
delineate_dem(streams=)and an optional line
layer in QGIS, for where the elevation model cannot see the channel: a
culverted urban stream, a canal across a divide, a valley a road embankment
dams in the model. Lowering the cells by a fixed depth does nothing — 0.00
km2 at every depth up to 150 m — so each line is walked from its lower end
and forced to descend the whole way. concentration_time()returns six empirical formulas rather than one,
each with the catchments it was fitted to and the spread between them,
because on a single basin they disagree by a factor of four.curve_number()composes the SCS curve number from the land cover and
soil this package already fetches, with the two judgements it rests on
returned beside the number rather than buried under it.
Licence
The package and the ArcGIS toolbox move from MIT to Apache-2.0; the QGIS
plugin is GPL-3.0-or-later. Releases up to and including 0.8.4 remain MIT.
Neither licence grants the use of the name basinkit.
Answers that were wrong, quietly
TDX-Hydro took the reach whose recorded point was nearest, which beside a
confluence is a stub: 122 km2 of a 228 km2 basin. It now takes the unit
catchment containing the outlet — 241 km2. Asking for a backend by name
skipped every check auto ran, so api returned 1.9 km2 of the Danube and
tdx 73 km2 of the Thames, both as plain answers. Every backend is now
weighed the same way. A click with no mapped river nearby and a large basin —
a city centre, a lake surface — is reported instead of returned in silence.
Gaps that were silent
A failed CHIRPS month was dropped without a word, so one run of 2015–2020
returned 59 months of 72 and a trend read the hole as a shorter record.
TerraClimate did the same per year, and fell through to the bounding box on a
clip failure. A half-extracted BasinATLAS geodatabase was accepted as a cache
forever after.
Processes that were killed
The eight-page report read elevation at the 100 Mpx default and reached 6.1 GB
on the Koshi — the basin in the README's own quick start — where the kernel
killed it, taking QGIS with it. It now reads 4 Mpx at the point every caller
arrives, decimates rasters to 1,600 pixels for drawing, and completes in 1.33
GB and eighteen seconds. The DEM backend estimates before it downloads and
declines with the figure named rather than growing its window until it dies.
Also
Band identifiers (B04, B08) are translated per mission. export_3d no
longer crashes on a basin built from a file, or loses the whole export to one
unreadable scene. The CLI reports errors instead of tracebacks. attributes()
works on any backend. Thirteen smaller fixes besides.
295 tests offline, 26 over the network, up from 177 in 0.8.4.
Full detail in CHANGELOG.md.
0.8.4
A basin delineated on the DEM carries no HydroBASINS id
backend="auto" refines anything below 2,000 km2 on the elevation model, which 0.8.3 made the default. Two things downstream still assumed the basin in hand had come from the HydroBASINS graph: subbasins() traverses the level-12 units inside a basin, and attributes() looks the basin up in BasinATLAS, which is keyed by HydroBASINS id. A DEM-derived polygon carries no such id, so both raised an error that named the backend rather than the request, and a small basin — the case the threshold change was meant to serve — could not reach either.
Both now ask for the HydroBASINS delineation when the basin they were handed does not have one, and record in the log why the backend changed. The ArcGIS Sub-Catchments tool does the same.
Every request now says which version made it
cache._USER_AGENT was the literal basinkit/0.1.0 and was never derived from anything, so every provider — ISRIC, Copernicus, HydroSHEDS, the STAC endpoints — had been seeing 0.1.0 for eight releases. soil.soil_profile carried a second copy of the same literal. Both now build the header from __version__ at call time. Providers rate-limit by User-Agent, so a stale one is not only a cosmetic lie.
One requester-pays scene no longer fails a whole Sentinel-2 mosaic
A few items in Earth Search's sentinel-2-l2a still point at s3://sentinel-s2-l2a, the requester-pays bucket of JP2s this package avoids for Landsat for the same reason. Over the Koshi at Chatara, one scene in six was such an item, and it failed the entire composite with an AWS credentials error naming neither the scene nor the bucket. stac_stack now leaves those out and reports how many, raising only if nothing public remains.
A step whose input never arrived says so
A step that consumes an earlier analysis's output raised a bare KeyError, which the sweep recorded against the consumer rather than the producer. It now names the analysis that did not complete.
Landscape form no longer fails on a basin with knickpoints
It asked the output sink for its field list; QgsFeatureSink has no fields(), so the call only survived where there was nothing to write. The fields now travel back from the algorithm that built them.
The report cover states the version that produced it
The ArcGIS sweep's PDF had its version typed into the cover, so a 0.8.3 run produced a report whose first page read 0.7.0. It now reads the run manifest, as the collage beside it already did.
basinkit 0.8.3
Three failures reported from the QGIS plugin by Vitor Castellar, two of which
turned out to be the same bug.
A basin's CRS is now checked rather than assumed
basinkit works in lon/lat throughout, and nothing verified that the geometry it
was handed was in lon/lat. Basin.from_file reprojected; Basin.from_geometry
did not, and the QGIS plugin uses from_geometry. A polygon in a projected CRS
therefore reached the equal-area projection as metres, and a northing of
7,793,981 was passed as a latitude — once in basin_area_km2, once in
morphometry, with two different error messages that looked like two separate
bugs.
clip.laea_crs()is now the only place that projection is built. It refuses a
centre that is not in degrees, with a message that names the real cause rather
than PROJ's internal one, and builds the CRS from a dict instead of a proj4
string, which QGIS's bundled PROJ does not reliably parse.Basin.from_geometryacceptscrs=and reprojects. The default is unchanged,
so existing callers are unaffected.- The QGIS plugin transforms the layer through
source.sourceCrs()on the way
in. All seven algorithms share that entry point, so all seven are fixed, not
only the three that were reported. mosaic.merge_tilestook its CRS straight from the first tile, where rasterio
returnsNonefor a file whose CRS it cannot read — what a PROJ installation
missing its data directory does. The array then failed much later inside
rioxarray with "CRS not found", naming the symptom. It now falls back to
EPSG:4326 and recordsbasinkit_crs_assumedin the mosaic metadata.
Basin.dem()keeps a second guard at the exit.
auto refines on the DEM below 2,000 km², not below 25
The default backend assembles a basin from whole HydroBASINS level-12 units of
about 130 km² each, so its boundary follows unit edges rather than the terrain
divide and will not match a DEM-derived basin along the margins. Three numbers
described where that stops being good enough: backend="auto" escaped to the
DEM below 25 km², the QGIS plugin warned below 500, and the blind check at
2,550 gauges in docs/verification.md puts the crossover near 2,000. A
catchment between 500 and 2,000 km² got the coarse answer and no warning at all.
The threshold is now delineate.DEM_REFINE_BELOW_KM2, set from that measurement
and carrying both the evidence and the cost in a comment. The plugin's warning
fires on the same number and explains what the coarse polygon is instead of only
recommending an alternative.
Tests
Six new tests. Four cover the CRS work and all four fail without it; one builds
a real EPSG:32645 layer in QGIS and asserts the geometry reaching basinkit is in
degrees; one checks that pyproject.toml, basinkit/__init__.py,
CITATION.cff and the plugin metadata all state the same version, after this
release's own bump missed one of them.
Upgrading
pip install -U basinkitThe QGIS plugin needs 0.8.3 or newer; update it from the QGIS plugin manager.
basinkit 0.8.2
Landscape form and the Arc Hydro export reach QGIS. The plugin goes to 0.8.0 with eleven algorithms rather than nine.
Landscape form returns its knickpoints as a point layer rather than a table, which is what a GIS wants. That needed something from the package: the trunk profile now carries the map coordinates of every point on it, in the grid's own CRS, and each knickpoint carries the point it sits on together with its distance to the outlet.
Export for Arc Hydro returns Catchment and DrainageLine as two feature layers with the Arc Hydro field names, and reports whether the routing table is a single tree draining to one outlet.
Both print, in the Processing log, what each number is worth and the rare cases where a number should not be used at all.
Full notes in CHANGELOG.md.