Metadata-Version: 2.4
Name: rtide
Version: 1.0.0
Summary: RTide: A python implementation of the ML Response Framework for Tidal Analyis and Prediction
Home-page: https://github.com/thomasmonahan/RTide
Author: Thomas Monahan
Author-email: thomas.monahan@eng.ox.ac.uk
License: Business Source License 1.1
Classifier: Programming Language :: Python :: 3
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: tensorflow
Requires-Dist: utide
Requires-Dist: scipy
Requires-Dist: skyfield
Requires-Dist: shap
Requires-Dist: matplotlib
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# RTide
A Python implementation of the framework for [Automating the tidal response method](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2024JH000525) and [Response-based prediction of tidal currents](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2025JC022758). The method is an extension of the response method created by Munk and Cartwright in: 'Tidal Spectroscopy and Prediction'. RTide can be used for conventional tidal analysis and prediction, and is well suited to problems involving non-stationary contamination such as tidal rivers, and meteorological forcing. 

# Installation
```
pip install rtide
```
# Usage
## Standard Analysis
Suppose we have a pandas dataframe containing sea-level measurements with a date-time index containing the time of each measurement. A complete RTide analysis can be run in just three lines of code: 
```
df = pd.DataFrame({'observations': observations}, index = times)

model = RTide(df, lat, lon)
model.Prepare_Inputs()
model.Train()
```
A model has now been trained, and the response approximated directly from the provided data. We can now use the learned model to generate predictions whenever we want. All we need is to provide a pandas time-index with the desired times:
```
model.Predict(test_df)
```
## Multivariate Analysis
Now, suppose that we know that our reference site is 'contaminated' by some form of non-stationary forcing (e.g. river outflow). RTide can learn the coupled response to these exogenous inputs directly by simply passing them as an additional column in the input dataframe:
```
df = pd.DataFrame({'observations': observations, 'exogenous_data':river_outflow}, index = times)
model = RTide(df, lat, lon)
...
```
The syntax for the remaining analysis is identical to before. However, several customizations are possible including the selection of custom lags for the multivariate inputs. This is useful in situtations where the dynamics of the interactions with exogenous inputs act on different timescales than the tidal response. 

## Interpretability
The trained RTide model can provide interesting insights into the dynamics of both tidal and non-tidal processes. Standard visualizations for the trained models are provided using the built in 'Visualize_Predictions()' and 'Visualize_Residuals' functions. Physical insights can be obtained using shap analysis as shown in [Response Framework: Tidal analysis and prediction through physics-informed ML](https://www.researchsquare.com/article/rs-3289185/v1). Complete SHAP analysis of the learned model can be performed by calling:
```
model.Shap_Analysis()
```

# Contributions
If you have used RTide for a usecase which is not already covered in the examples section then please reach out by creating an issue. 

# Citing RTide
Bibtex:
```
@article{monahan2025rtide,
  title={RTide: Automating the tidal response method},
  author={Monahan, Thomas and Tang, Tianning and Roberts, Stephen and Adcock, Thomas AA},
  journal={Journal of Geophysical Research: Machine Learning and Computation},
  volume={2},
  number={2},
  pages={e2024JH000525},
  year={2025},
  publisher={Wiley Online Library}
}
```
```
@article{monahan2025response,
  title={Response-based prediction of tidal currents},
  author={Monahan, Thomas and Tang, Tianning and Roberts, Stephen and Adcock, Thomas AA},
  journal={Journal of Geophysical Research: Oceans},
  volume={130},
  number={12},
  pages={e2025JC022758},
  year={2025},
  publisher={Wiley Online Library}
}
```
# Commercialization Details:
Note for RTide 1.0, commercial use requires a paid license. See LICENSE for details. Questions can be emailed to thomas.monahan@eng.ox.ac.uk. Personal and academic usage is permitted freely. 

# Useful Response Method References
[1] Munk, Walter Heinrich, and David Edgar Cartwright. "Tidal spectroscopy and prediction." Philosophical Transactions of the Royal Society of London. Series A, Mathematical and Physical Sciences 259.1105 (1966): 533-581.

[2] Cartwright, David Edgar. "A unified analysis of tides and surges round north and east Britain." Philosophical Transactions of the Royal Society of London. Series A, Mathematical and Physical Sciences 263.1134 (1968): 1-55.

[3] Zetler, Bernard, David Cartwright, and Saul Berkman. "Some comparisons of response and harmonic tide predictions." The International Hydrographic Review (1979).

[4] Zetler, Bernard D., and Walter H. Munk. 1975. "The optimum wiggliness of tidal admittances." Journal of Marine Research 33, (S). 

[5] Zetler, Bernard D. "The Evolution of Modern Tide Analysis and Prediction—Some Personal Memories." The International Hydrographic Review (1987).

[6] Amin, M., and G. W. Lennon. "On anomalous tides in Australian waters." The International Hydrographic Review (1992).
