Skip to content

Use Cases

Jump to bottom
cortexmancer edited this page Aug 14, 2026 · 3 revisions

Aquiring all basic data

A user can initially obtain only the basic data in order to use the database entries to get specific stations within various contexts. See an example of initial execution:

$ python hidrodb --skip-series-jobs
Enter API username: *******
Enter API password: *******
[INFO]: ====================================
[INFO]: Creating jobs for Bacia.
[INFO]: Initiating jobs for Bacia
[INFO]: No valid token present, requesting.
[INFO]: Token acquired and cached.
[INFO]: [WRITER Bacia]: Total processed Data: 9, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for Bacia Total processed Data: 9, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 2.0425357818603516, Total writer elapsed: 0.09407389094121754.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for Bacia.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for SubBacia.
[INFO]: Initiating jobs for SubBacia
[INFO]: [WRITER SubBacia]: Total processed Data: 84, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for SubBacia Total processed Data: 84, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 1.7218303680419922, Total writer elapsed: 0.0454633308108896.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for SubBacia.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Entidade.
[INFO]: Initiating jobs for Entidade
[INFO]: [WRITER Entidade]: Total processed Data: 1346, Total finished Jobs: 1. 
[INFO]: [WRITER Entidade]: Total processed Data: 1346, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for Entidade Total processed Data: 1346, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 2.172236442565918, Total writer elapsed: 0.10623302333988249.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for Entidade.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Municipio.
[INFO]: Initiating jobs for Municipio
[INFO]: [WRITER Municipio]: Total processed Data: 5714, Total finished Jobs: 1. 
[INFO]: [WRITER Municipio]: Total processed Data: 5714, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for Municipio Total processed Data: 5714, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 2.172177314758301, Total writer elapsed: 0.36168359825387597.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for Municipio.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Rio.
[INFO]: Initiating jobs for Rio
[INFO]: [WRITER Rio]: Total processed Data: 14121, Total finished Jobs: 1. 
[INFO]: [WRITER Rio]: Total processed Data: 14121, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for Rio Total processed Data: 14121, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 3.350553274154663, Total writer elapsed: 0.8507782021770254.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for Rio.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Estado.
[INFO]: Initiating jobs for Estado
[INFO]: [WRITER Estado]: Total processed Data: 39, Total finished Jobs: 1. 
[INFO]: [WRITER]: Finished jobs for Estado Total processed Data: 39, Total finished Jobs: 1.
[INFO]: [WRITER]: Total worker elapsed: 1.9099388122558594, Total writer elapsed: 0.058666198747232556.
[INFO]: Pending: 0, Failed: 0, Completed: 1

[INFO]: No pending jobs for Estado.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Estacao.
[INFO]: Initiating jobs for Estacao
[INFO]: [WRITER Estacao]: Total processed Data: 1189, Total finished Jobs: 5. 
[INFO]: [WRITER Estacao]: Total processed Data: 2276, Total finished Jobs: 7. 
[INFO]: [WRITER Estacao]: Total processed Data: 3495, Total finished Jobs: 9. 
[INFO]: [WRITER Estacao]: Total processed Data: 4753, Total finished Jobs: 11. 
[INFO]: [WRITER Estacao]: Total processed Data: 6285, Total finished Jobs: 13. 
[INFO]: [WRITER Estacao]: Total processed Data: 7992, Total finished Jobs: 15. 
[INFO]: [WRITER Estacao]: Total processed Data: 9249, Total finished Jobs: 16. 
[INFO]: [WRITER Estacao]: Total processed Data: 11812, Total finished Jobs: 18. 
[INFO]: [WRITER Estacao]: Total processed Data: 13200, Total finished Jobs: 19. 
[INFO]: [WRITER Estacao]: Total processed Data: 14593, Total finished Jobs: 20. 
[INFO]: [WRITER Estacao]: Total processed Data: 16400, Total finished Jobs: 21. 
[INFO]: [WRITER Estacao]: Total processed Data: 18306, Total finished Jobs: 22. 
[INFO]: [WRITER Estacao]: Total processed Data: 21073, Total finished Jobs: 23. 
[INFO]: [WRITER Estacao]: Total processed Data: 24074, Total finished Jobs: 24. 
[INFO]: [WRITER Estacao]: Total processed Data: 27250, Total finished Jobs: 25. 
[INFO]: [WRITER Estacao]: Total processed Data: 32572, Total finished Jobs: 26. 
[INFO]: [WRITER Estacao]: Total processed Data: 37918, Total finished Jobs: 27. 
[INFO]: [WRITER Estacao]: Total processed Data: 37918, Total finished Jobs: 27. 
[INFO]: [WRITER]: Finished jobs for Estacao Total processed Data: 37918, Total finished Jobs: 27.
[INFO]: [WRITER]: Total worker elapsed: 532.6351408958435, Total writer elapsed: 23.213562343851663.
[INFO]: Pending: 0, Failed: 0, Completed: 27

[INFO]: No pending jobs for Estacao.
[INFO]: ====================================

[INFO]: Skiping series jobs.

In a few minutes, it was possible to obtain all basic data, as well as all stations in the national territory. If the --skip-series-jobs option were not present, the application would continue execution by acquiring time series data for all acquired stations. Since most studies focus on specific regions, it is possible to obtain granularity using the basic data.

Aquiring specific data from a region

Take this use case as example:

"A researcher wants to study flood risk in the Paraopeba River basin, a region with a recent history of critical hydrological events. To do this, the researcher needs time-series data on river levels (stage) from monitoring stations within the basin, as well as the spatial locations of these stations."

Since this hypotetic user knows the name of the river, the following query can be executed:

$ sqlite3 db/hidro.db -header "SELECT * FROM Rio WHERE LOWER(Nome) LIKE '%paraopeba%';"
╭───────────────┬──────────┬────────────┬─────────────┬────────────────┬────────────┬────────────────────────────┬─────────╮
│     Nome      │  Codigo  │ Jurisdicao │ BaciaCodigo │ SubBaciaCodigo │ RegistroID │          DataIns           │ DataAlt │
╞═══════════════╪══════════╪════════════╪═════════════╪════════════════╪════════════╪════════════════════════════╪═════════╡
│ RIO PARAOPEBA │ 40300000 │          2 │           4 │             40 │       6086 │ 2026-08-13 10:39:01.699526 │ NULL    │
│ RIO PARAOPEBA │ 58642000 │          2 │           5 │             58 │       8911 │ 2026-08-13 10:39:01.700797 │ NULL    │
╰───────────────┴──────────┴────────────┴─────────────┴────────────────┴────────────┴────────────────────────────┴─────────╯

Since stations holds the codes from river, sub-basins and basins, it is possible to aquire the specific stations within those data:

$ sqlite3 db/hidro.db "SELECT COUNT(*) FROM Estacao WHERE RioCodigo IN (40300000, 58642000);"
╭──────────╮
│ COUNT(*) │
╞══════════╡
│       92 │
╰──────────╯

Now the user knows that the region of interest holds 92 stations, and now it is possible to aquire the specific data from this region:

$ python hidrodb --run-for Cotas --stations "$(sqlite3 db/hidro.db "FROM Estacao WHERE RioCodigo IN (40300000, 58642000");"

[INFO]: ====================================
[INFO]: No pending jobs for Bacia.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for SubBacia.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for Entidade.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for Municipio.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for Rio.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for Estado.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: No pending jobs for Estacao.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for Chuvas.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for ResumoDescarga.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for Sedimentos.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for Vazoes.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for Granulometria.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for CurvaDescarga.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for QualAgua.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Skiping job for PerfilTransversal.
[INFO]: ====================================

[INFO]: ====================================
[INFO]: Creating jobs for Cotas
[INFO]: Created 17618 jobs for Cotas in 1.48 seconds
[INFO]: Initiating 116 jobs for Cotas
[INFO]: [WRITER Cotas]: Total processed Data: 586, Total finished Jobs: 116. 
[INFO]: [WRITER]: Finished jobs for Cotas Total processed Data: 586, Total finished Jobs: 116.
[INFO]: [WRITER]: Total worker elapsed: 2920.0324144363403, Total writer elapsed: 12.48312541591713.
[INFO]: Pending: 17499, Failed: 5, Completed: 111

[INFO]: Initiating 5 jobs for Cotas
[INFO]: [WRITER Cotas]: Total processed Data: 24, Total finished Jobs: 5. 
[INFO]: [WRITER]: Finished jobs for Cotas Total processed Data: 24, Total finished Jobs: 5.
[INFO]: [WRITER]: Total worker elapsed: 48.97978663444519, Total writer elapsed: 8.0868257163811.
[INFO]: Pending: 17499, Failed: 0, Completed: 116

[INFO]: No pending jobs for Cotas.
[INFO]: ====================================

After some minutes, the user aquired all stage data of the stations within the area of interest, and now he can analyse and work it in whatever way is necessarie for the research. There is an example using plotfy as well:

Paraopepa Example

Clone this wiki locally