# Stream Seasonal Thermal Regimes
This repository contains reusable code (R script and Python package) for analyzing stream seasonal thermal regimes, in the form of an annual temperature cycle function, using the ``three-sine'' approach. Notes on research use and reproducibility (for the associated manuscript) and citation information are included at the end of the README, in the [Research Data and Use](#Research-Data-and-Use) section. This upper portion deals with the use of the R script and the Python package.
## Overview
The stream seasonal thermal regime - i.e., long-term seasonal behavior of stream temperatures - can be described using the annual temperature cycle, or the general pattern of stream temperatures throughout the year. As a function, mean temperature = f(day of year). The three-sine approach (Philippus et al., 2024; see [Citation](#Citation)) is a general function that captures the annual temperature cycle with very high accuracy for streams across the United States, including high-elevation/snow-dominated watersheds, arid regions, etc. Thus, detailed stream seasonal thermal behavior can be summarized using eight coefficients, from which almost any seasonal summary statistic of interest can be extracted (by recreating the annual temperature cycle in full, then computing the summary statistic). This repository contains Python and R implementations for fitting three-sine coefficients to data from a given stream as well as recreating an annual temperature cycle timeseries from the coefficients.
## Usage
The R version is just available as source code; simply download and `source` the file `functions.R`. The Python version is available on the Python Package Index as `rtseason` and can be installed from pip: `pip install rtseason`.
This applies to both Python and R. There are two key functions for the end user: `fit.sins` (R) / `fit_sins` (Python) and `make.sints` (R) / `make_sints` (Python).
The `fit.sins` function accepts as its main argument a data frame containing columns for `day` (day of year, as an integer) and `temperature` (observed temperature). This data frame may be day-of-year means already, but it can also be an observed timeseries with multiple entries per day (e.g., by date over several years). The function will compute day-of-year means. Observations must be available for at least 180 days. The R version has several other arguments that were used for generating data for the paper but can be left as default by the end user.
The result of `fit.sins` is a data frame containing the eight three-sine coefficients as well as fit statistics. The coefficients are labeled Intercept (annual mean), Amplitude (main cosine amplitude), FallWinter, SpringSummer (autumn-winter and spring-summer coefficients), FallDay, WinterDay, SpringDay, and SummerDay (days-of-year of anomaly peaks). The last two columns are R2 and RMSE for the three-sine fit versus the observed day-of-year means. In Python, the optional argument `return.object` can be set to `True` to return, instead of a data frame, a three-sine fit object with the above results as properties and a `generate_ts` method for generating a timeseries.
The `make.sints` function accepts a three-sine coefficient data frame (R2/RMSE not required) as an argument and returns a data frame containing `day` (day of year) and `actemp` (annual cycle temperature, or day-of-year mean temperature) columns.
In Python, the actual three-sine functionality is implemented through the `ThreeSine` class with fitting (`ThreeSine.from_data()`) and timeseries-generation (`.generate_ts`) methods, but the above functions are provided so that the interface is (roughly) the same as the R version.
# Research Data and Use
## Reproducibility
This repository contains analysis code used to develop an analysis of stream seasonal thermal regimes in the United States. The R Notebook, `analysis.Rmd`, will reproduce all supporting analysis and generate figures when run with the data files downloaded into a `Data` subdirectory of the working directory. `analysis.Rmd` calls more involved functions from `functions.R`. The knitted version of the notebook is also included as `analysis.pdf`.
To run the Notebook, in the working directory there must be a `Data` directory containing the data files and a `Figures` directory with a `MovingWindowSeasons` subdirectory, where figures will be stored. For map generation, `functions.R` will also look for an EPA Level I Ecoregions (https://gaftp.epa.gov/EPADataCommons/ORD/Ecoregions/cec_na/na_cec_eco_l1.zip) shapefile in an `Ecoregions` directory.
The required data can be downloaded from [Hydroshare](http://www.hydroshare.org/resource/7d960b7fdfee480895fd845bade1b75a).
## Citation
The three-sine approach implemented here is introduced and analyzed in the paper: "Improved Annual Temperature Cycle Function for Stream Seasonal Thermal Regimes" (Philippus, Corona and Hogue 2024), in JAWRA.
(Note: as of this writing, the paper has been accepted but is not yet available online, so the link won't work yet.)
Link: https://doi.org/10.1111/1752-1688.13228
Citation BibTeX:
```
@article{,
title = {Improved Annual Temperature Cycle Function for Stream Seasonal Thermal Regimes},
journal = {Journal of the American Water Resources Association},
doi = {10.1111/1752-1688.13228},
year = {2024},
author = {Philippus, Daniel and Corona, Claudia R. and Hogue, Terri S.}
}
```
Raw data
{
"_id": null,
"home_page": "https://github.com/quantum-dan/seasonality",
"name": "rtseason",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.0",
"maintainer_email": null,
"keywords": null,
"author": "Daniel Philippus",
"author_email": "daniel@dphilippus.com",
"download_url": "https://files.pythonhosted.org/packages/ba/07/54599909bfd22e4564edf2dcd39e6737107146fdf6889039691ba06034e5/rtseason-1.1.2.tar.gz",
"platform": null,
"description": "# Stream Seasonal Thermal Regimes\r\n\r\nThis repository contains reusable code (R script and Python package) for analyzing stream seasonal thermal regimes, in the form of an annual temperature cycle function, using the ``three-sine'' approach. Notes on research use and reproducibility (for the associated manuscript) and citation information are included at the end of the README, in the [Research Data and Use](#Research-Data-and-Use) section. This upper portion deals with the use of the R script and the Python package.\r\n\r\n## Overview\r\n\r\nThe stream seasonal thermal regime - i.e., long-term seasonal behavior of stream temperatures - can be described using the annual temperature cycle, or the general pattern of stream temperatures throughout the year. As a function, mean temperature = f(day of year). The three-sine approach (Philippus et al., 2024; see [Citation](#Citation)) is a general function that captures the annual temperature cycle with very high accuracy for streams across the United States, including high-elevation/snow-dominated watersheds, arid regions, etc. Thus, detailed stream seasonal thermal behavior can be summarized using eight coefficients, from which almost any seasonal summary statistic of interest can be extracted (by recreating the annual temperature cycle in full, then computing the summary statistic). This repository contains Python and R implementations for fitting three-sine coefficients to data from a given stream as well as recreating an annual temperature cycle timeseries from the coefficients.\r\n\r\n## Usage\r\n\r\nThe R version is just available as source code; simply download and `source` the file `functions.R`. The Python version is available on the Python Package Index as `rtseason` and can be installed from pip: `pip install rtseason`.\r\n\r\nThis applies to both Python and R. There are two key functions for the end user: `fit.sins` (R) / `fit_sins` (Python) and `make.sints` (R) / `make_sints` (Python).\r\n\r\nThe `fit.sins` function accepts as its main argument a data frame containing columns for `day` (day of year, as an integer) and `temperature` (observed temperature). This data frame may be day-of-year means already, but it can also be an observed timeseries with multiple entries per day (e.g., by date over several years). The function will compute day-of-year means. Observations must be available for at least 180 days. The R version has several other arguments that were used for generating data for the paper but can be left as default by the end user.\r\n\r\nThe result of `fit.sins` is a data frame containing the eight three-sine coefficients as well as fit statistics. The coefficients are labeled Intercept (annual mean), Amplitude (main cosine amplitude), FallWinter, SpringSummer (autumn-winter and spring-summer coefficients), FallDay, WinterDay, SpringDay, and SummerDay (days-of-year of anomaly peaks). The last two columns are R2 and RMSE for the three-sine fit versus the observed day-of-year means. In Python, the optional argument `return.object` can be set to `True` to return, instead of a data frame, a three-sine fit object with the above results as properties and a `generate_ts` method for generating a timeseries.\r\n\r\nThe `make.sints` function accepts a three-sine coefficient data frame (R2/RMSE not required) as an argument and returns a data frame containing `day` (day of year) and `actemp` (annual cycle temperature, or day-of-year mean temperature) columns.\r\n\r\nIn Python, the actual three-sine functionality is implemented through the `ThreeSine` class with fitting (`ThreeSine.from_data()`) and timeseries-generation (`.generate_ts`) methods, but the above functions are provided so that the interface is (roughly) the same as the R version.\r\n\r\n# Research Data and Use\r\n\r\n## Reproducibility\r\n\r\nThis repository contains analysis code used to develop an analysis of stream seasonal thermal regimes in the United States. The R Notebook, `analysis.Rmd`, will reproduce all supporting analysis and generate figures when run with the data files downloaded into a `Data` subdirectory of the working directory. `analysis.Rmd` calls more involved functions from `functions.R`. The knitted version of the notebook is also included as `analysis.pdf`.\r\n\r\nTo run the Notebook, in the working directory there must be a `Data` directory containing the data files and a `Figures` directory with a `MovingWindowSeasons` subdirectory, where figures will be stored. For map generation, `functions.R` will also look for an EPA Level I Ecoregions (https://gaftp.epa.gov/EPADataCommons/ORD/Ecoregions/cec_na/na_cec_eco_l1.zip) shapefile in an `Ecoregions` directory.\r\n\r\nThe required data can be downloaded from [Hydroshare](http://www.hydroshare.org/resource/7d960b7fdfee480895fd845bade1b75a).\r\n\r\n## Citation\r\n\r\nThe three-sine approach implemented here is introduced and analyzed in the paper: \"Improved Annual Temperature Cycle Function for Stream Seasonal Thermal Regimes\" (Philippus, Corona and Hogue 2024), in JAWRA.\r\n\r\n(Note: as of this writing, the paper has been accepted but is not yet available online, so the link won't work yet.)\r\n\r\nLink: https://doi.org/10.1111/1752-1688.13228\r\n\r\nCitation BibTeX:\r\n\r\n```\r\n@article{,\r\n title = {Improved Annual Temperature Cycle Function for Stream Seasonal Thermal Regimes},\r\n journal = {Journal of the American Water Resources Association},\r\n doi = {10.1111/1752-1688.13228},\r\n year = {2024},\r\n author = {Philippus, Daniel and Corona, Claudia R. and Hogue, Terri S.}\r\n}\r\n```\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Analyzing river seasonal thermal regimes in Python",
"version": "1.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/quantum-dan/seasonality/issues",
"Homepage": "https://github.com/quantum-dan/seasonality"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3dd49180b9195519a6e1941e1139221b9b5fa8e2bbd78183fdc49e5017c75457",
"md5": "cbe058d87a4772d1256848df8dd2301e",
"sha256": "11a39c1fd443d3618b0d3eb15fc5b2e932bf43bef62402ce1472215eb43f379b"
},
"downloads": -1,
"filename": "rtseason-1.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cbe058d87a4772d1256848df8dd2301e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.0",
"size": 7389,
"upload_time": "2024-08-19T19:38:30",
"upload_time_iso_8601": "2024-08-19T19:38:30.526870Z",
"url": "https://files.pythonhosted.org/packages/3d/d4/9180b9195519a6e1941e1139221b9b5fa8e2bbd78183fdc49e5017c75457/rtseason-1.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ba0754599909bfd22e4564edf2dcd39e6737107146fdf6889039691ba06034e5",
"md5": "e7d88b29334f9466ae579d81dc3a1a97",
"sha256": "7af9888a921cfeef9fc1eb6a6af6501b9a800f313401f741c63951b3ffa5cf7d"
},
"downloads": -1,
"filename": "rtseason-1.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e7d88b29334f9466ae579d81dc3a1a97",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.0",
"size": 7177,
"upload_time": "2024-08-19T19:38:31",
"upload_time_iso_8601": "2024-08-19T19:38:31.926451Z",
"url": "https://files.pythonhosted.org/packages/ba/07/54599909bfd22e4564edf2dcd39e6737107146fdf6889039691ba06034e5/rtseason-1.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-19 19:38:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "quantum-dan",
"github_project": "seasonality",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "rtseason"
}
JSON
