{"id":40669079,"url":"https://github.com/csiro-hydroinformatics/uchronia-time-series","last_synced_at":"2026-01-21T09:17:58.152Z","repository":{"id":88767083,"uuid":"323520682","full_name":"csiro-hydroinformatics/uchronia-time-series","owner":"csiro-hydroinformatics","description":"Library for ensemble forecast time series","archived":false,"fork":false,"pushed_at":"2025-03-03T07:56:11.000Z","size":877,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-10T06:42:52.243Z","etag":null,"topics":["ensemble-forecasts","multidimensional-arrays","time-series"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/csiro-hydroinformatics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2020-12-22T04:31:12.000Z","updated_at":"2023-01-31T18:39:23.000Z","dependencies_parsed_at":"2023-11-15T06:33:01.970Z","dependency_job_id":"0e520d55-979b-44da-a666-566c1a27912c","html_url":"https://github.com/csiro-hydroinformatics/uchronia-time-series","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/csiro-hydroinformatics/uchronia-time-series","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csiro-hydroinformatics%2Fuchronia-time-series","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csiro-hydroinformatics%2Fuchronia-time-series/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csiro-hydroinformatics%2Fuchronia-time-series/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csiro-hydroinformatics%2Fuchronia-time-series/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/csiro-hydroinformatics","download_url":"https://codeload.github.com/csiro-hydroinformatics/uchronia-time-series/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/csiro-hydroinformatics%2Fuchronia-time-series/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28630946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T04:47:28.174Z","status":"ssl_error","status_checked_at":"2026-01-21T04:47:22.943Z","response_time":86,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ensemble-forecasts","multidimensional-arrays","time-series"],"created_at":"2026-01-21T09:17:58.077Z","updated_at":"2026-01-21T09:17:58.136Z","avatar_url":"https://github.com/csiro-hydroinformatics.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Uchronia - time series handling for ensembles simulations and forecasts in C++\n\n## Overview\n\nUchronia is a C++ library designed to handle multidimensional time series and ensemble thereof. [Uchronia](https://en.wikipedia.org/wiki/Uchronia) is a literary neologism for a hypothetical or fictional time-period of our world. This seems a suitable name for a library primarily designed notably to handle retrospective ensemble forecast time series.\n\nSome key capabilities are:\n\n* Off the shelf support for point time series and time series of ensemble forecast\n* Extensibility to various data types (numeric or not) through C++ templates, e.g. to a \"time series of spatial grids\"\n* High level language bindings for R, Python, Matlab, and others via a consistent \"C\" API.\n\n## Design goals\n\n* Consistent handling of multidimensional time series across programming languages, from prototyping to operations\n* Prevent wasting resource in I/O code duplication and idiosyncratic data structure across (matlab/R/Python/etc.) implementations\n* Scalable from interactive exploratory data analysis to high-performance cluster computing\n* Promote high level data identification for provenance and data integrity\n\n## Documentation\n\nThe combined [C++ and Python API documentation](https://csiro-hydroinformatics.github.io/uchronia-ts-doc/) is available as of August 2022.\n\n## License\n\nMIT-derived CSIRO license (see [License.txt](./LICENSE.txt))\n\nPlease contact David Robertson (david.robertson@csiro.au) if you want to reuse this library, to facilitate the maintenance of IP registers.\n\n## Getting started\n\n\"Getting started\" with Uchronia may mean:\n\n* Using existing capabilities\n* Using Uchronia C++ templates in your C++ code to create new types of time series suited to your context\n\n### Using off-the-shelf\n\n**uchronia** is largely a header-only library but can be installed as a shared library, for off the shelf use. There are ongoing efforts to package it for Windows and Linux, but for now one needs to install from source.\n\nOn Linux:\n\n```sh\nROOT_DIR=~/src/uchronia-time-series\n\nINSTALL_PREFIX=/usr/local\n\nCXX_COMP=-DCMAKE_CXX_COMPILER=g++\nC_COMP=-DCMAKE_C_COMPILER=gcc\nCM_PREF=-DCMAKE_INSTALL_PREFIX=${INSTALL_PREFIX}\nCM=\"cmake ${CXX_COMP} ${C_COMP} ${CM_PREF} -DBUILD_SHARED_LIBS=ON ..\"\n\n# placeholder: depending on Linux machine getting yaml-cpp, moirai, netCDF, cinterop, and Boost packages pre-installed\ncd ${ROOT_DIR}/datatypes\nmkdir -p build ; cd build\n$CM\nmake \nsudo make install\n```\n\n### R bindings\n\nBuilding the package from source can be done with:\n\n```sh\ncd ${ROOT_DIR}/bindings/R/pkgs\nR CMD build uchronia\nR CMD INSTALL uchronia_x.y.tar.gz\n```\n\nThe package includes examples in the form of built-in vignettes:\n\n```r\nlibrary(uchronia)\nbrowseVignettes(\"uchronia\")\n```\n\n### Example in Python\n\n```python\nimport uchronia\n# etc.\n```\n\n## As a developer\n\n### using existing types of time series:\n\n```c++\n#include \"datatypes/time_series.hpp\"\n// \u003csnip\u003e other includes skipped\nusing namespace datatypes::timeseries;\nusing TS = TTimeSeries\u003cdouble\u003e;\n\nvoid simplest() {\n    vector\u003cdouble\u003e d = { 1,2,3,4,5,6,7 };\n    auto start = ptime(date(2017, 1, 1));\n    TS oneWeek(d, start, TimeStep::GetDaily());\n    double val = oneWeek[start + days(2)];\n    TS other = oneWeek + 3.0;\n}\n\nvoid ensembleForecasts() {\n    size_t tsEtsLength = 31 * 6;\n    size_t ensSize = 5;\n    size_t tsLength = 24;\n    ptime start(date(2008, 3, 4));\n    auto hourly = TimeStep::GetHourly();\n    TimeStep daily = TimeStep::GetDaily();\n    TimeStep etsTstep = hourly * 6;\n    TimeStep fcastTstep = hourly / 4;\n\n    // shorthand type aliases\n    using DTH = datatypes::tests::DataTestHelper\u003cdouble\u003e;\n    using EFTS = EnsembleForecastTimeSeries\u003c\u003e;\n    using MTSPTR = EFTS::ElementType;\n    using MTS = std::remove_pointer\u003cMTSPTR\u003e::type;\n\n    // a time series of ensembles of time series:\n    EFTS ensTs = DTH::CreateTsEnsembleTs(\n        tsEtsLength,\n        ensSize,\n        tsLength,\n        start,\n        etsTstep,\n        fcastTstep);\n    MTSPTR multiTs = ensTs[0];\n    TS* forecast = multiTs.Get(3);\n} \n```\n\n### Extending, customizing \n\nuchronia is largely template based, you can create time series for other item types such as spatial grids. Thanks to the static typing of C++ and its template metaprogramming features, errors are often caught at compile time, and several operations such as arithmetic ones will \"just work\":\n\n```c++ \n\nclass SpatialGrid\n{\nprivate:\n    std::vector\u003cdouble\u003e data;\npublic:\n    double easting, northing;\n    SpatialGrid operator+(const SpatialGrid\u0026 rhs) const {/*TODO*/ return SpatialGrid(); }\n    SpatialGrid operator+(double rhs) const {/*TODO*/ return SpatialGrid(); }\n};\n\nTEST_CASE(\"Extensibility of templated time series\")\n{\n    using SpatialTs = TTimeSeries\u003cSpatialGrid\u003e;\n\n    auto start = ptime(date(2017, 1, 1));\n    SpatialTs oneWeek(7, start, TimeStep::GetDaily());\n    SpatialGrid val = oneWeek[start + days(2)];\n    SpatialTs other = oneWeek + val;\n\n}\n```\n\n## Background\n\nEnsemble prediction techniques have been shown to produce more accurate predictions as well as formally quantify prediction uncertainty in a range of scientific applications. Statistically meaningful quantification of uncertainty can require very large ensembles, with associated increases in computation and data storage, particularly for predictions in the form of time series. In addition, the verification of statistical properties of an ensemble, such as the reliability of the ensemble spread, requires very long retrospective verification periods. This presents logistical and conceptual challenges for researchers and practitioners still transitioning from simulations based on deterministic, single instance realisations. A software system for handling such ensemble time series has to address several needs, notably: \n\n* retrospective ensemble predictions can quickly require several hundred gigabytes of data, and be accessible from workstations or on a high performance parallel compute cluster; \n* users should still have an interactive, responsive experience when processing that data, with little concern for on-disk logistics - a well-known principle that remains unsatisfactory in many implementations; and \n* the data infrastructure must promote strong data identity and versioning to help sustain a reproducible simulation outcome.   \n\nIn \"Uchronia\" the core entities of time series and ensembles are implemented in portable C++, using template metaprogramming. This permits a unified but versatile implementation for time series of various dimensional complexity. Time series elements can thus range from an atomic value, typically numeric, all the way up to a time series of ensemble forecasts. Object-oriented design patterns are used to allow for RAM caching of large data. A “C“ API permits convenient data manipulation from a variety of interactive higher-level technical computing languages such as Python and R. Time series can be accessed via a time series library. Time series creation and retrieval relies on string identifiers and metadata rather than the still prevalent paths to data files. Libraries can bring otherwise disparate data into a consistent data set for the simulation or analytical purpose. We envisage the time series library facilities are a solid basis for use in conjunction with federated data provenance infrastructure. \n\n## Acknowledgements\n\nContributions to this library were made to support some of the streamflow forecasting R\u0026D under the [Water Information Research And Development Alliance](https://www.csiro.au/en/Research/LWF/Areas/Water-resources/Assessing-water-resources/WIRADA/About) between the CSIRO and the Australian Bureau of Meteorology. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsiro-hydroinformatics%2Fuchronia-time-series","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcsiro-hydroinformatics%2Fuchronia-time-series","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcsiro-hydroinformatics%2Fuchronia-time-series/lists"}