• Overview
• Installation
• Getting Started
• Gallery
• Documentation
• License
• Contributions
• Acknowledgments
• How to Cite
• Contacts

pyTCR is a physics-based model developed in python to estimate rainfall induced by tropical cyclones (TCs). It is largely based on the TCR model described by Zhu et al., 2013 and Lu et al., 2018. PyTCR simulates convective TC rainfall by correlating the precipitation rate with the total upward velocity within the TC vortex. It integrates seamlessly with outputs from a tropical cyclone downscaling model (see Lin et al., 2023) to generate detailed spatial-temporal rainfall patterns that align with hurricane tracks.

1. To install the latest stable release from PyPI:

   pip install pyTCR

   OR conda:

   conda install -c conda-forge pyTCR

   💡 Note: Python 3.11 or higher is required for installing pyTCR.

2. To get the latest (unstable) development version from GitHub:

   git clone https://github.com/levuvietphong/pyTCR.git
   cd pyTCR
   pip install .

   💡 Note: This installs the most recent updates, which may include new features and bug fixes that are not yet available in the stable release.

This repository provides a collection of jupyter notebooks designed to facilitate the use of PyTCR for generating and visualizing rainfall and wind speed induced by TCs. To access the tutorials, clone the repository locally. These notebooks cover various use cases and data sources, providing comprehensive guidance for users.

0. Downloading Tropical Cyclone Data: illustrates the process of downloading CMIP6 tropical cyclone tracks that have undergone downscaling using the tropical cyclone downscaling model.

1. Visualizing Tropical Cyclone Tracks: showcases the visualization of tropical cyclone tracks and their density, utilizing both observational data and downscaled CMIP6 outputs.

2. Rainfall Simulation: uses outputs from the tropical cyclone downscaling model to simulate rainfall driven by tropical cyclones. This includes rainfall at a specific location and over the entire domain of the tropical cyclone tracks.

3. Wind Speed Generation: demonstrates the generation of spatially and temporally varying wind speeds from downscaled CMIP6 outputs.

4. Rainfall within a Polygon: outlines the process of generating total rainfall within polygons loaded from shapefiles.

5. Multiple Rainfall Events within a Polygon: generates multiple total rainfall events from multiple tropical cyclone tracks within a polygon.

The following figures illustrate the inputs used and results obtained from PyTCR:

• Tropical cyclone tracks: The figure below shows the tracks of tropical cyclones downscaled from outputs from E3SM v1.0 model, Reanalysis ERA5, and best track observations.

• Spatial Distribution of Total Rainfall: The image below shows the spatial distribution of total rainfall along three storm tracks that made landfall in the Southeast Texas (SETx) region.

• Time Series of Precipitation: The figure below depicts the time series of precipitation at a specific location (29.907°N, 94.900°W) within the SETx region.

The official documentation is hosted on Read the Docs.

Distributed under the MIT License. See LICENSE for more information.

All contributions, bug reports, bug fixes, documentation improvements, enhancements, and ideas are welcome. A detailed overview on how to contribute can be found in the contributing guide.

This work was supported by the Southeast Texas Urban Integrated Field Lab project, one of four Urban Integrated Field Laboratories (UIFLs). The software was mostly developed at . We extend our gratitude to the SETx-UIFL team for their support and collaboration.

If you are using this library, please consider citing the following paper:

• Le et al., (2025). pyTCR: A tropical cyclone rainfall model for python. Journal of Open Source Software, 10(110), 8074, https://doi.org/10.21105/joss.08074.

Bibtex:

@article{Le2025, 
    title = {pyTCR: A tropical cyclone rainfall model for python},
    author = {Phong V. V. Le and Geeta Persad and Gabriel Perez and Ifeanyichukwu C. Nduka and William Mobley and Ethan T. Coon},
    journal = {Journal of Open Source Software},
    volume = {10},
    number = {110},
    pages = {8074},    
    year = {2025},    
    doi = {10.21105/joss.08074},
}

For questions and feedback, please contact:

• Phong Le (levuvietphong@gmail.com)

Go to Top