hydroloom 0.1.0__tar.gz

hydroloom-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+.Rproj.user
+.Rhistory
+.RData
+.Ruserdata
+.Renviron
+cran-comments.md
+CRAN-SUBMISSION
+*temp*
+!.github/PULL_REQUEST_TEMPLATE.md
+.vscode/
+revdep/
+dev/*
+!dev/plan/
+!dev/milestones/
+!dev/done_check.R
+!dev/FIXTURE_ARCHITECTURE.md
+vignettes/*.html
+docs/
+.kiro/workflow-output/
+.kiro/settings/lsp.json
+!.kiro/context/pr-body-template.md
+!.kiro/context/kickoff-template.md
+!inst/extdata/conformance/algorithms/TEMPLATE.md
+.pixi/
+__pycache__/
+*.egg-info/
+dist/
+src/hydroloom/data/

hydroloom-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+<!-- towncrier release notes start -->
+
+## 0.1.0 (2026-11-05)
+
+### Added
+
+- The package version comes from the `py-v*` release tag, and `hydroloom.__version__` reports it.
+- `add_toids` builds `toid`, each flowline's downstream flowline, from `fromnode` and `tonode`, the identifiers of the points at each end of every flowline. By default it keeps only the main path where a flowline splits, which needs a `divergence` column (1 main path, 2 minor path), and raises `HydroloomError` when `divergence` is missing or a split has no main path or more than one. A flowline that reaches no other gets the empty string that marks an outlet. `return_dendritic=False` keeps every downstream connection and issues a `FutureWarning`, since `to_flownetwork` is to replace it. A network that already has `toid`, or lacks `fromnode`/`tonode`, raises `RepresentationError`.
+- `align_names` renames the columns hydroloom knows by another name to its standard names and changes nothing else: identifiers keep their type and a missing `toid` stays missing. `hy_reverse` renames standard names back to those of one source, given as `source="nhdplus"`, `"nhdplushr"`, `"3dhp"`, or `"hydrofabric"`, in lowercase, so `id` becomes `comid`. With `source=None`, the default, `hy_reverse` gives each standard name the alias most recently registered for it with `register_names`, and leaves a name with no registered alias unchanged. `is_hy` reports whether a table is in the form `as_hy` returns: standard names, an `id` column with no missing values, and identifier columns as text. `name_definitions` returns a table of every standard name and its definition.
+- `as_hy` renames the columns hydroloom knows by another name to its standard names (`COMID` becomes `id`, `ToCOMID` becomes `toid`), turns identifiers into text, and gives a missing `toid` the empty string that marks an outlet (a flowline that flows to nothing else in the table). `representation` reports which representation a table follows (the pattern of its columns), such as an id/toid list or a fromnode/tonode list; it reads the column names and the `id` values only. `make_index_ids` returns an `IndexIds` that gives each flowline's downstream or upstream flowlines as integer positions, for walking the network, and `mode="both"` returns the two as a pair. All three raise `RepresentationError` when no column becomes `id` and `HydroloomError` when an `id` value is missing.
+- `capabilities` reports which hydroloom functions accept a network as it stands, in a table sorted by function name, with one row per hydroloom function that takes a table and with the columns `function`, `available`, and `via`. `available` is `True` where the network follows the representation the function needs (the pattern of columns `representation` reports) and holds the fixed columns the function requires; it tests the shape of the table, not its values, so a function marked available can still raise on the data. `via` gives the one conversion that makes an unavailable function available, such as `add_toids`, which builds `toid` for a node table (one that gives the nodes at the two ends of each flowline in `fromnode` and `tonode`). It is `""` where the function is available or no single conversion reaches it. A table with no `id` column, or an object that is not a table, has no representation, so only the functions that take any table are available. R's `hy_capabilities` takes `include_conversions` to mark the functions `via` reaches as available; `capabilities` has no such argument, since `via` gives the same answer.
+- `hydroloom.errors` holds the exception and warning classes hydroloom raises. `HydroloomError` subclasses `ValueError`. It is raised for a problem in the input table that the caller can fix. `RepresentationError` subclasses `HydroloomError`. It is raised when a table lacks the representation (the pattern of its columns, such as an id/toid list) or the columns a function needs. Two cases raise built-in exceptions that `except HydroloomError` does not catch. A vocabulary problem, a column name that hydroloom's list of names cannot resolve, raises `KeyError`. An identifier column that mixes text and numbers raises `TypeError`. Warnings other than deprecations are `HydroloomWarning`, and each one points at the line in the caller's code that made the call.
+- `is_dendritic` returns `False` when the table records a divergence and `True` otherwise. It reads two things the table records: a `divergence` value of 2, which marks the minor path leaving a divergence in NHDPlus coding, and, unless `validate_data=False`, an `id` that repeats beside a `toid` column, which is how a flowline with two downstream connections is listed. Column names are aligned to hydroloom names first, so an NHDPlus table with `COMID`, `ToCOMID`, and `Divergence` gives the same answer as one already renamed with `as_hy`. A table `as_hy` cannot read raises what `as_hy` raises, including `HydroloomError` on an (`id`, `toid`) pair listed twice. A node table whose divergences show only as a shared `fromnode`, with no `divergence` column, returns `True`.
+- `navigate_network_dfs` walks a network depth first from each flowline in `starts` and returns, for each unique start in the order given, the flowlines it reaches as a list of paths, each a pandas `Index` of identifiers in visit order. `direction` is `"down"` (along `toid`), `"up"` (against it), or `"downmain"` or `"upmain"`, which follow only the main connections that `downmain` or `upmain` mark. Where the walk can go on to more than one flowline it takes the smallest identifier in byte order of the identifiers as text first, so `"10"` comes before `"9"` and any row order of the input gives the same result. A path ends at an outlet going down or a headwater going up (a flowline with no flowline below it or above it), or where the walk turns back to a flowline it has already visited. With `reset=False`, the default, a flowline returned for one start is left out of the results for later starts; `reset=True` walks each start on its own. `network` may be a network table or the `IndexIds` that `make_index_ids` returns, built with `mode="to"` for the downstream directions and `mode="from"` for the upstream ones. A node table, which gives the nodes at the two ends of each flowline in `fromnode` and `tonode`, is converted with `add_toids` first for `"down"` and `"up"`; for `"downmain"` and `"upmain"` it raises `RepresentationError`.
+- `register_names` registers input column names as aliases of standard names for the rest of the session, so `align_names`, `as_hy`, and `hy_reverse` recognize them: `register_names({"FlowlineID": "id"})` makes a `FlowlineID` column `id`. Aliases are stored in lowercase, so `hy_reverse` gives back `flowlineid`. `replace=True` drops earlier registrations and keeps the aliases hydroloom ships. Used as `with register_names(mapping):`, the registration is undone when the block exits. A value that is not a standard name, or an alias that is a standard name other than its value, raises `KeyError` and registers nothing.
+- `sort_network` returns the rows of a network ordered upstream to downstream, so every flowline comes after every flowline that drains to it. Outlets, and flowlines that drain to the same flowline, are taken in byte order of their identifiers as text, so `"10"` comes before `"9"` and any row order of the input gives the same output. `split=True` adds `terminal_id`, the `id` of the outlet each flowline drains to, and `outlets` limits the result to the networks above the flowlines given in `outlets`. `add_topo_sort` sorts the same way and adds `topo_sort`, numbered from the number of flowlines down to 1 at the last outlet; it replaces an input `topo_sort` column, such as NHDPlus `Hydroseq`, under the input's name. Both raise `HydroloomError` when the network holds a cycle, a set of flowlines that drain back into themselves, or when a value in `outlets` is not an `id`. `sort_network` also raises it when `split=True` and one flowline in `outlets` lies upstream of another. A node table, where each flowline names the nodes at its upstream and downstream ends in `fromnode` and `tonode` and carries `divergence`, is converted with `add_toids` first; a table with neither `toid` nor node columns raises `RepresentationError`.

hydroloom-0.1.0/LICENSE

@@ -0,0 +1,116 @@
+CC0 1.0 Universal
+
+Statement of Purpose
+
+The laws of most jurisdictions throughout the world automatically confer
+exclusive Copyright and Related Rights (defined below) upon the creator and
+subsequent owner(s) (each and all, an "owner") of an original work of
+authorship and/or a database (each, a "Work").
+
+Certain owners wish to permanently relinquish those rights to a Work for the
+purpose of contributing to a commons of creative, cultural and scientific
+works ("Commons") that the public can reliably and without fear of later
+claims of infringement build upon, modify, incorporate in other works, reuse
+and redistribute as freely as possible in any form whatsoever and for any
+purposes, including without limitation commercial purposes. These owners may
+contribute to the Commons to promote the ideal of a free culture and the
+further production of creative, cultural and scientific works, or to gain
+reputation or greater distribution for their Work in part through the use and
+efforts of others.
+
+For these and/or other purposes and motivations, and without any expectation
+of additional consideration or compensation, the person associating CC0 with a
+Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
+and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
+and publicly distribute the Work under its terms, with knowledge of his or her
+Copyright and Related Rights in the Work and the meaning and intended legal
+effect of CC0 on those rights.
+
+1. Copyright and Related Rights. A Work made available under CC0 may be
+protected by copyright and related or neighboring rights ("Copyright and
+Related Rights"). Copyright and Related Rights include, but are not limited
+to, the following:
+
+  i. the right to reproduce, adapt, distribute, perform, display, communicate,
+  and translate a Work;
+
+  ii. moral rights retained by the original author(s) and/or performer(s);
+
+  iii. publicity and privacy rights pertaining to a person's image or likeness
+  depicted in a Work;
+
+  iv. rights protecting against unfair competition in regards to a Work,
+  subject to the limitations in paragraph 4(a), below;
+
+  v. rights protecting the extraction, dissemination, use and reuse of data in
+  a Work;
+
+  vi. database rights (such as those arising under Directive 96/9/EC of the
+  European Parliament and of the Council of 11 March 1996 on the legal
+  protection of databases, and under any national implementation thereof,
+  including any amended or successor version of such directive); and
+
+  vii. other similar, equivalent or corresponding rights throughout the world
+  based on applicable law or treaty, and any national implementations thereof.
+
+2. Waiver. To the greatest extent permitted by, but not in contravention of,
+applicable law, Affirmer hereby overtly, fully, permanently, irrevocably and
+unconditionally waives, abandons, and surrenders all of Affirmer's Copyright
+and Related Rights and associated claims and causes of action, whether now
+known or unknown (including existing as well as future claims and causes of
+action), in the Work (i) in all territories worldwide, (ii) for the maximum
+duration provided by applicable law or treaty (including future time
+extensions), (iii) in any current or future medium and for any number of
+copies, and (iv) for any purpose whatsoever, including without limitation
+commercial, advertising or promotional purposes (the "Waiver"). Affirmer makes
+the Waiver for the benefit of each member of the public at large and to the
+detriment of Affirmer's heirs and successors, fully intending that such Waiver
+shall not be subject to revocation, rescission, cancellation, termination, or
+any other legal or equitable action to disrupt the quiet enjoyment of the Work
+by the public as contemplated by Affirmer's express Statement of Purpose.
+
+3. Public License Fallback. Should any part of the Waiver for any reason be
+judged legally invalid or ineffective under applicable law, then the Waiver
+shall be preserved to the maximum extent permitted taking into account
+Affirmer's express Statement of Purpose. In addition, to the extent the Waiver
+is so judged Affirmer hereby grants to each affected person a royalty-free,
+non transferable, non sublicensable, non exclusive, irrevocable and
+unconditional license to exercise Affirmer's Copyright and Related Rights in
+the Work (i) in all territories worldwide, (ii) for the maximum duration
+provided by applicable law or treaty (including future time extensions), (iii)
+in any current or future medium and for any number of copies, and (iv) for any
+purpose whatsoever, including without limitation commercial, advertising or
+promotional purposes (the "License"). The License shall be deemed effective as
+of the date CC0 was applied by Affirmer to the Work. Should any part of the
+License for any reason be judged legally invalid or ineffective under
+applicable law, such partial invalidity or ineffectiveness shall not
+invalidate the remainder of the License, and in such case Affirmer hereby
+affirms that he or she will not (i) exercise any of his or her remaining
+Copyright and Related Rights in the Work or (ii) assert any associated claims
+and causes of action with respect to the Work, in either case contrary to
+Affirmer's express Statement of Purpose.
+
+4. Limitations and Disclaimers.
+
+  a. No trademark or patent rights held by Affirmer are waived, abandoned,
+  surrendered, licensed or otherwise affected by this document.
+
+  b. Affirmer offers the Work as-is and makes no representations or warranties
+  of any kind concerning the Work, express, implied, statutory or otherwise,
+  including without limitation warranties of title, merchantability, fitness
+  for a particular purpose, non infringement, or the absence of latent or
+  other defects, accuracy, or the present or absence of errors, whether or not
+  discoverable, all to the greatest extent permissible under applicable law.
+
+  c. Affirmer disclaims responsibility for clearing rights of other persons
+  that may apply to the Work or any use thereof, including without limitation
+  any person's Copyright and Related Rights in the Work. Further, Affirmer
+  disclaims responsibility for obtaining any necessary consents, permissions
+  or other rights required for any use of the Work.
+
+  d. Affirmer understands and acknowledges that Creative Commons is not a
+  party to this document and has no duty or obligation with respect to this
+  CC0 or use of the Work.
+
+For more information, please see
+<http://creativecommons.org/publicdomain/zero/1.0/>

hydroloom-0.1.0/PKG-INFO

@@ -0,0 +1,246 @@
+Metadata-Version: 2.5
+Name: hydroloom
+Version: 0.1.0
+Summary: Utilities to weave hydrologic fabrics.
+Project-URL: Homepage, https://github.com/DOI-USGS/hydroloom
+Project-URL: Issues, https://github.com/DOI-USGS/hydroloom/issues
+Author-email: David Blodgett <dblodgett@usgs.gov>
+License-Expression: CC0-1.0
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: geopandas>=1.0
+Requires-Dist: numpy
+Requires-Dist: pandas>=2.2.2
+Requires-Dist: pyogrio
+Requires-Dist: scipy
+Requires-Dist: shapely>=2.0
+Description-Content-Type: text/markdown
+
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# hydroloom <img src="man/figures/logo.png" align="right" alt="" width="120" />
+
+[![R-CMD-check](https://github.com/DOI-USGS/hydroloom/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/DOI-USGS/hydroloom/actions/workflows/R-CMD-check.yaml)
+[![codecov](https://codecov.io/gh/doi-usgs/hydroloom/branch/main/graph/badge.svg)](https://app.codecov.io/gh/doi-usgs/hydroloom)
+[![CRAN](https://www.r-pkg.org/badges/version/hydroloom)](https://cran.r-project.org/package=hydroloom)
+
+## hydroloom:
+
+**Install:** `install.packages("hydroloom")`
+
+Or for latest development:
+`remotes::install_github("doi-usgs/hydroloom")`
+
+`hydroloom` is a collection of functions to work with hydrologic
+geospatial fabrics. Hydroloom is designed to provide general hydrologic
+network functionality for any hydrographic or hydrologic data. The
+package is intended for developers of workflows and other packages that
+require low level network and network data manipulation utilities.
+
+**To Learn More, visit the pkgdown site**:
+<https://doi-usgs.github.io/hydroloom/articles/hydroloom.html>
+
+## Citation:
+
+    Blodgett, D., 2026, hydroloom: Utilities to Weave Hydrologic Fabrics v1.2,
+    https://doi.org/10.5066/P16RS3UZ
+
+Hydroloom has support for attributes that can be seen in:
+
+``` r
+hydroloom::hydroloom_name_definitions
+```
+
+<details>
+
+<summary>
+
+Click to See Definitions
+</summary>
+
+| Name | Definition |
+|:---|:---|
+| id | shared network identifier for catchment divide and flowpath or flowline |
+| toid | indicates to the downstream id. May or may not be dendritic |
+| fromnode | indicates the node representing the nexus upstream of a catchment |
+| tonode | indicates the node representing the nexus downstream of a catchment |
+| divergence | indicates whether a catchment is not downstream of a divergence (0), the primary path downstream of a divergence (1), or a diversion downstream of a divergence (2). |
+| divergence_fraction | Indicates the fraction of flow to be apportioned to a given diverted path. Should sum to 1 when considering all diverted flowlines downstream of a diversion. |
+| wbid | waterbody id |
+| total_da_sqkm | total drainage area at the outlet of a catchment |
+| da_sqkm | local drainage area of a catchment |
+| length_km | length of a single catchment’s flowpath |
+| pathlength_km | distance from the outlet of a catchment to the terminal outlet of a network |
+| arbolate_sum | total accumulated length of all upstream flowlines |
+| topo_sort | Similar to hydrosequence in NHDPlus. Large topo_sort values are upstream of small topo_sort values. Note that there are many valid topological sort orders of a directed graph. |
+| up_topo_sort | topo sort value of the upstream mainstem |
+| dn_topo_sort | topo sort value of the downstream mainstem |
+| dn_minor_topo_sort | topo sort value of the downstream minor network element with the smallest id |
+| terminal_topo_sort | topo sort value of the outlet network element |
+| terminal_flag | 1 for network terminous 0 for within network |
+| terminal_id | id of terminal catchment for entire drainage basin |
+| start_flag | 1 for a headwater, 0 otherwise |
+| levelpath | provides an identifier for the collection of flowlines that make up a single mainstem flowpath of a drainage basin |
+| up_levelpath | levelpath value of the upstream mainstem |
+| dn_levelpath | levelpath value of the downstream mainstem |
+| levelpath_outlet_id | id of outlet catchment of a levelpath |
+| stream_level | starting at 1 for coastal terminals and 4 for inland terminals increments by 1 for each smaller tributary level |
+| dn_stream_level | stream level of downstream mainstem network element |
+| stream_order | starting at 1 for headwaters increments by 1 for each larger tributary level, diversions adopt stream order from upstream but returning diverted network does not increment stream order |
+| stream_calculator | starting at 1 for headwaters and 0 along diverted paths increments by 1 for each larger tributary level, does no increment along diverted paths. Is equal to stream_order along the dendritic network |
+| feature_type | descriptive feature type moniker |
+| feature_type_code | compact feature type identifier |
+| vector_proc_unit | identifier for processing units based on vector encapsulation |
+| raster_proc_unit | identifier for processing units based on raster encapsulation |
+| id_measure | interpolative linear reference measure along a single identified feature |
+| aggregate_id | aggregate identifier useful for ‘reach’ or ‘flowpath’ aggregation of flowlines |
+| aggregate_id_measure | interpolative linear reference measure along an aggregate feature |
+| aggregate_id_from_measure | interpolative linear reference for downstream end of a single feature that makes up an aggregate feature |
+| aggregate_id_to_measure | interpolative linear reference for the upstream end of a single feature that makes up an aggregate feature |
+| point_id | identifier of hydrologic location point |
+| offset | offset distance from point to line in units of linear reference analysis units |
+| upmain | indicates that a given network element is the primary upstream connection at a confluence |
+| downmain | indicates that a given network element is the primary downstream connection at a confluence |
+
+</details>
+
+<br/>
+
+`hydroloom` supports your attribute names that map to the in-built
+definitions. See
+[`hydroloom_names()`](https://doi-usgs.github.io/hydroloom/reference/hydroloom_names.html)
+for more.
+
+`hydroloom` supports both dendritic and non-dendritic networks start at
+[this
+vignette](https://doi-usgs.github.io/hydroloom/articles/non-dendritic.html)
+for more.
+
+`hydroloom` was largely created from components of
+[nhdplusTools](https://doi.org/10.5066/P97AS8JD), which is now published
+as [hydrogeofetch](https://doi-usgs.github.io/hydrogeofetch/):
+
+    Blodgett, D., Johnson, J.M., 2022, nhdplusTools: Tools for
+      Accessing and Working with the NHDPlus,
+      https://doi.org/10.5066/P97AS8JD
+
+`hydrogeofetch` supports web service access and the particulars of the
+NHDPlus data model. In contrast, `hydroloom` is intended to be more
+general and focused specifically on hydro fabric data functionality.
+
+`hydroloom` implements algorithms documented in:
+
+NHDPlus Attributes:
+
+    Moore, R.B., McKay, L.D., Rea, A.H., Bondelid, T.R., Price, C.V., Dewald, T.G.,
+      and Johnston, C.M., 2019, User's guide for the national hydrography dataset
+      plus (NHDPlus) high resolution: U.S. Geological Survey Open-File Report 2019–1096,
+      66 p., https://doi.org/10.3133/ofr20191096.
+
+Graph Concepts:
+
+    Cormen, T. H., & Leiserson, C. E. (2022). Introduction to
+      Algorithms, fourth edition. MIT Press.
+
+Pfafstetter Attributes:
+
+    Verdin, K. L., & Verdin, J. P. (1999). A topological system for
+      delineation and codification of the Earth's river basins.
+      Journal of Hydrology, 218(1–2), 1–12.
+      https://doi.org/10.1016/S0022-1694(99)00011-6
+
+### Terminology:
+
+The following definitions have been used as much as possible throughout
+the package. Terms for rivers: **Flowline:** A flowline is an linear
+geometry that represents a segment of a flowing body of water. Some
+flowlines have no local drainage area and are never aggregate features.
+**Flowpath:** A flowpath is a linear geometry that represents the
+connection between a catchment’s inlet and its outlet. All flowpaths
+have a local drainage area and may be aggregates of flowlines.
+**Catchment:** A physiographic unit with zero or one inlets and one
+outlet. A catchment is represented by one or more partial realizations;
+flowpath, divide, and networks of flowpaths and divides. **Catchment
+Divide:** The polygon boundary that encompasses a catchment.
+**Divergence:** The hydrologic nexus (node) where flow diverges. A
+divergence is an abstract location in a hydrologic network.
+**Diversion:** A flowline that is below a divergence and is not the
+primary downstream path. A diversion is a specific feature downstream of
+a divergence.
+
+### Design Notes:
+
+- Hydroloom uses tibble because dplyr verbs for data.frame was dropping
+  the custom hy attributes.
+- The `data.table` package is used for some key joins to enhance
+  scalability but dplyr is preferred for clarity.
+- `hy` class tibble standardizes all attribute names in code.
+- graph representation facilitated by `make_index_ids()`
+- names are plural when referring to identifiers and singular when
+  referring to a numerical attribute.
+
+### Build and release:
+
+Development happens on GitHub (DOI-USGS/hydroloom). Official builds and
+release candidates are produced on code.usgs.gov
+(code.usgs.gov/water/hydroloom) using GitLab CI.
+
+Vignettes use the `BUILD_VIGNETTES` environment variable to control code
+evaluation. Set `BUILD_VIGNETTES=TRUE` in a local `.Renviron` to build
+them with live code; without it every chunk renders as prose and code
+with no evaluated output. Only `vignettes/hydroloom.Rmd` ships to CRAN.
+Everything under `vignettes/articles/` is website-only — excluded from
+the source tarball by `.Rbuildignore` and built by pkgdown. A vignette
+that needs a web service or a large download belongs in
+`vignettes/articles/`.
+
+Local development does not require building the source package. Use
+`devtools::test()`, `devtools::check()`, and `devtools::document()`
+directly.
+
+Release candidates are built on code.usgs.gov. Push a branch named
+`rc/<version>` (e.g. `rc/1.2.1`) to trigger the GitLab CI pipeline,
+which runs three stages:
+
+1.  **check** — lightweight structural check with no tests, examples, or
+    vignettes. Gates the rest of the pipeline.
+2.  **build** — `R CMD build .` to produce the source tarball, which is
+    uploaded to the GitLab generic package registry.
+3.  **verify** — `R CMD check --as-cran` on the built tarball.
+
+Once the pipeline passes, download the tarball from the package registry
+and submit it to CRAN. The tarball that CRAN receives is the exact
+artifact that passed `--as-cran` in CI.
+
+### Release checklist:
+
+- All checks pass and code coverage is adequate
+- NEWS.md is up to date
+- Disclaimer is in released form
+- Version updated in `code.json`
+- Push `rc/<version>` branch to code.usgs.gov and confirm the pipeline
+  passes
+- Download tarball from the GitLab package registry and submit to CRAN
+- After CRAN acceptance:
+  - Ensure pkgdown is up to date
+  - Commit, push, and PR/MR changes
+  - Create release page and tag
+  - Attach CRAN tar.gz to release page
+  - Update DOI to point to release page
+  - Switch README disclaimer back to “dev” mode
+  - Bump version in DESCRIPTION
+
+# Disclaimer
+
+This software is preliminary or provisional and is subject to revision.
+It is being provided to meet the need for timely best science. The
+software has not received final approval by the U.S. Geological Survey
+(USGS). No warranty, expressed or implied, is made by the USGS or the
+U.S. Government as to the functionality of the software and related
+material nor shall the fact of release constitute any such warranty. The
+software is provided on the condition that neither the USGS nor the U.S.
+Government shall be held liable for any damages resulting from the
+authorized or unauthorized use of the software.
+
+[![CC0](https://i.creativecommons.org/p/zero/1.0/88x31.png)](https://creativecommons.org/publicdomain/zero/1.0/)

hydroloom-0.1.0/README.md

@@ -0,0 +1,228 @@
+
+<!-- README.md is generated from README.Rmd. Please edit that file -->
+
+# hydroloom <img src="man/figures/logo.png" align="right" alt="" width="120" />
+
+[![R-CMD-check](https://github.com/DOI-USGS/hydroloom/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/DOI-USGS/hydroloom/actions/workflows/R-CMD-check.yaml)
+[![codecov](https://codecov.io/gh/doi-usgs/hydroloom/branch/main/graph/badge.svg)](https://app.codecov.io/gh/doi-usgs/hydroloom)
+[![CRAN](https://www.r-pkg.org/badges/version/hydroloom)](https://cran.r-project.org/package=hydroloom)
+
+## hydroloom:
+
+**Install:** `install.packages("hydroloom")`
+
+Or for latest development:
+`remotes::install_github("doi-usgs/hydroloom")`
+
+`hydroloom` is a collection of functions to work with hydrologic
+geospatial fabrics. Hydroloom is designed to provide general hydrologic
+network functionality for any hydrographic or hydrologic data. The
+package is intended for developers of workflows and other packages that
+require low level network and network data manipulation utilities.
+
+**To Learn More, visit the pkgdown site**:
+<https://doi-usgs.github.io/hydroloom/articles/hydroloom.html>
+
+## Citation:
+
+    Blodgett, D., 2026, hydroloom: Utilities to Weave Hydrologic Fabrics v1.2,
+    https://doi.org/10.5066/P16RS3UZ
+
+Hydroloom has support for attributes that can be seen in:
+
+``` r
+hydroloom::hydroloom_name_definitions
+```
+
+<details>
+
+<summary>
+
+Click to See Definitions
+</summary>
+
+| Name | Definition |
+|:---|:---|
+| id | shared network identifier for catchment divide and flowpath or flowline |
+| toid | indicates to the downstream id. May or may not be dendritic |
+| fromnode | indicates the node representing the nexus upstream of a catchment |
+| tonode | indicates the node representing the nexus downstream of a catchment |
+| divergence | indicates whether a catchment is not downstream of a divergence (0), the primary path downstream of a divergence (1), or a diversion downstream of a divergence (2). |
+| divergence_fraction | Indicates the fraction of flow to be apportioned to a given diverted path. Should sum to 1 when considering all diverted flowlines downstream of a diversion. |
+| wbid | waterbody id |
+| total_da_sqkm | total drainage area at the outlet of a catchment |
+| da_sqkm | local drainage area of a catchment |
+| length_km | length of a single catchment’s flowpath |
+| pathlength_km | distance from the outlet of a catchment to the terminal outlet of a network |
+| arbolate_sum | total accumulated length of all upstream flowlines |
+| topo_sort | Similar to hydrosequence in NHDPlus. Large topo_sort values are upstream of small topo_sort values. Note that there are many valid topological sort orders of a directed graph. |
+| up_topo_sort | topo sort value of the upstream mainstem |
+| dn_topo_sort | topo sort value of the downstream mainstem |
+| dn_minor_topo_sort | topo sort value of the downstream minor network element with the smallest id |
+| terminal_topo_sort | topo sort value of the outlet network element |
+| terminal_flag | 1 for network terminous 0 for within network |
+| terminal_id | id of terminal catchment for entire drainage basin |
+| start_flag | 1 for a headwater, 0 otherwise |
+| levelpath | provides an identifier for the collection of flowlines that make up a single mainstem flowpath of a drainage basin |
+| up_levelpath | levelpath value of the upstream mainstem |
+| dn_levelpath | levelpath value of the downstream mainstem |
+| levelpath_outlet_id | id of outlet catchment of a levelpath |
+| stream_level | starting at 1 for coastal terminals and 4 for inland terminals increments by 1 for each smaller tributary level |
+| dn_stream_level | stream level of downstream mainstem network element |
+| stream_order | starting at 1 for headwaters increments by 1 for each larger tributary level, diversions adopt stream order from upstream but returning diverted network does not increment stream order |
+| stream_calculator | starting at 1 for headwaters and 0 along diverted paths increments by 1 for each larger tributary level, does no increment along diverted paths. Is equal to stream_order along the dendritic network |
+| feature_type | descriptive feature type moniker |
+| feature_type_code | compact feature type identifier |
+| vector_proc_unit | identifier for processing units based on vector encapsulation |
+| raster_proc_unit | identifier for processing units based on raster encapsulation |
+| id_measure | interpolative linear reference measure along a single identified feature |
+| aggregate_id | aggregate identifier useful for ‘reach’ or ‘flowpath’ aggregation of flowlines |
+| aggregate_id_measure | interpolative linear reference measure along an aggregate feature |
+| aggregate_id_from_measure | interpolative linear reference for downstream end of a single feature that makes up an aggregate feature |
+| aggregate_id_to_measure | interpolative linear reference for the upstream end of a single feature that makes up an aggregate feature |
+| point_id | identifier of hydrologic location point |
+| offset | offset distance from point to line in units of linear reference analysis units |
+| upmain | indicates that a given network element is the primary upstream connection at a confluence |
+| downmain | indicates that a given network element is the primary downstream connection at a confluence |
+
+</details>
+
+<br/>
+
+`hydroloom` supports your attribute names that map to the in-built
+definitions. See
+[`hydroloom_names()`](https://doi-usgs.github.io/hydroloom/reference/hydroloom_names.html)
+for more.
+
+`hydroloom` supports both dendritic and non-dendritic networks start at
+[this
+vignette](https://doi-usgs.github.io/hydroloom/articles/non-dendritic.html)
+for more.
+
+`hydroloom` was largely created from components of
+[nhdplusTools](https://doi.org/10.5066/P97AS8JD), which is now published
+as [hydrogeofetch](https://doi-usgs.github.io/hydrogeofetch/):
+
+    Blodgett, D., Johnson, J.M., 2022, nhdplusTools: Tools for
+      Accessing and Working with the NHDPlus,
+      https://doi.org/10.5066/P97AS8JD
+
+`hydrogeofetch` supports web service access and the particulars of the
+NHDPlus data model. In contrast, `hydroloom` is intended to be more
+general and focused specifically on hydro fabric data functionality.
+
+`hydroloom` implements algorithms documented in:
+
+NHDPlus Attributes:
+
+    Moore, R.B., McKay, L.D., Rea, A.H., Bondelid, T.R., Price, C.V., Dewald, T.G.,
+      and Johnston, C.M., 2019, User's guide for the national hydrography dataset
+      plus (NHDPlus) high resolution: U.S. Geological Survey Open-File Report 2019–1096,
+      66 p., https://doi.org/10.3133/ofr20191096.
+
+Graph Concepts:
+
+    Cormen, T. H., & Leiserson, C. E. (2022). Introduction to
+      Algorithms, fourth edition. MIT Press.
+
+Pfafstetter Attributes:
+
+    Verdin, K. L., & Verdin, J. P. (1999). A topological system for
+      delineation and codification of the Earth's river basins.
+      Journal of Hydrology, 218(1–2), 1–12.
+      https://doi.org/10.1016/S0022-1694(99)00011-6
+
+### Terminology:
+
+The following definitions have been used as much as possible throughout
+the package. Terms for rivers: **Flowline:** A flowline is an linear
+geometry that represents a segment of a flowing body of water. Some
+flowlines have no local drainage area and are never aggregate features.
+**Flowpath:** A flowpath is a linear geometry that represents the
+connection between a catchment’s inlet and its outlet. All flowpaths
+have a local drainage area and may be aggregates of flowlines.
+**Catchment:** A physiographic unit with zero or one inlets and one
+outlet. A catchment is represented by one or more partial realizations;
+flowpath, divide, and networks of flowpaths and divides. **Catchment
+Divide:** The polygon boundary that encompasses a catchment.
+**Divergence:** The hydrologic nexus (node) where flow diverges. A
+divergence is an abstract location in a hydrologic network.
+**Diversion:** A flowline that is below a divergence and is not the
+primary downstream path. A diversion is a specific feature downstream of
+a divergence.
+
+### Design Notes:
+
+- Hydroloom uses tibble because dplyr verbs for data.frame was dropping
+  the custom hy attributes.
+- The `data.table` package is used for some key joins to enhance
+  scalability but dplyr is preferred for clarity.
+- `hy` class tibble standardizes all attribute names in code.
+- graph representation facilitated by `make_index_ids()`
+- names are plural when referring to identifiers and singular when
+  referring to a numerical attribute.
+
+### Build and release:
+
+Development happens on GitHub (DOI-USGS/hydroloom). Official builds and
+release candidates are produced on code.usgs.gov
+(code.usgs.gov/water/hydroloom) using GitLab CI.
+
+Vignettes use the `BUILD_VIGNETTES` environment variable to control code
+evaluation. Set `BUILD_VIGNETTES=TRUE` in a local `.Renviron` to build
+them with live code; without it every chunk renders as prose and code
+with no evaluated output. Only `vignettes/hydroloom.Rmd` ships to CRAN.
+Everything under `vignettes/articles/` is website-only — excluded from
+the source tarball by `.Rbuildignore` and built by pkgdown. A vignette
+that needs a web service or a large download belongs in
+`vignettes/articles/`.
+
+Local development does not require building the source package. Use
+`devtools::test()`, `devtools::check()`, and `devtools::document()`
+directly.
+
+Release candidates are built on code.usgs.gov. Push a branch named
+`rc/<version>` (e.g. `rc/1.2.1`) to trigger the GitLab CI pipeline,
+which runs three stages:
+
+1.  **check** — lightweight structural check with no tests, examples, or
+    vignettes. Gates the rest of the pipeline.
+2.  **build** — `R CMD build .` to produce the source tarball, which is
+    uploaded to the GitLab generic package registry.
+3.  **verify** — `R CMD check --as-cran` on the built tarball.
+
+Once the pipeline passes, download the tarball from the package registry
+and submit it to CRAN. The tarball that CRAN receives is the exact
+artifact that passed `--as-cran` in CI.
+
+### Release checklist:
+
+- All checks pass and code coverage is adequate
+- NEWS.md is up to date
+- Disclaimer is in released form
+- Version updated in `code.json`
+- Push `rc/<version>` branch to code.usgs.gov and confirm the pipeline
+  passes
+- Download tarball from the GitLab package registry and submit to CRAN
+- After CRAN acceptance:
+  - Ensure pkgdown is up to date
+  - Commit, push, and PR/MR changes
+  - Create release page and tag
+  - Attach CRAN tar.gz to release page
+  - Update DOI to point to release page
+  - Switch README disclaimer back to “dev” mode
+  - Bump version in DESCRIPTION
+
+# Disclaimer
+
+This software is preliminary or provisional and is subject to revision.
+It is being provided to meet the need for timely best science. The
+software has not received final approval by the U.S. Geological Survey
+(USGS). No warranty, expressed or implied, is made by the USGS or the
+U.S. Government as to the functionality of the software and related
+material nor shall the fact of release constitute any such warranty. The
+software is provided on the condition that neither the USGS nor the U.S.
+Government shall be held liable for any damages resulting from the
+authorized or unauthorized use of the software.
+
+[![CC0](https://i.creativecommons.org/p/zero/1.0/88x31.png)](https://creativecommons.org/publicdomain/zero/1.0/)