| _version_ | 1866902107851849728 |
|---|---|
| author | Robledo Delgado, Vanessa Vergara, Humberto |
| author_facet | Robledo Delgado, Vanessa Vergara, Humberto |
| contents | <p dir="auto">TITO is a framework designed to run the EF5 hydrologic model operationally, integrating satellite data and machine learning techniques to support real-time forecasting and hydrologic analysis.</p> <div dir="auto"> <h2>Installation Instructions</h2> </div> <p dir="auto"><strong>1. Clone the repository</strong></p> <div dir="auto"> <pre>git clone https://github.com/AHWALab/TITO.git</pre> <div> </div> </div> <p dir="auto"><strong>2. Navigate to the repository folder</strong></p> <div dir="auto"> <pre>cd TITO/<br><br></pre> </div> <p dir="auto"><strong>3. Run the set up code</strong> This step might take few minutes.</p> <div dir="auto"> <pre>./setup_tito.sh</pre> <div> </div> </div> <p dir="auto"><strong>4. Add the new conda env to your routines</strong> Open <code>pipeline.sh</code> and change the path to the conda environment, should be something like this:</p> <div> <pre><code>source /Users/$username$/miniconda3/etc/profile.d/conda.sh </code></pre> <div> </div> </div> <p dir="auto">After installation, ensure that your TITO folder contains the following subdirectories and files.</p> <div dir="auto"> <h2>Repository structure</h2> </div> <p dir="auto">This repository is desiged to run EF5 operational over West Africa. Users must populate the required folders with topographic and parameter grids for their region of interest, and modify the EF5 control file (<code>templates/ef5_control_template.txt</code>) accordingly. A guide step-by-step to create the needed layers can be found in: <a href="https://github.com/AHWALab/EF5-builder-toolkit">EF5-builder-toolkit</a>.</p> <div dir="auto"> <h3>Key Files & Folders</h3> </div> <ul> <li><strong><code>westafrica1km_config.py</code></strong> – Configuration file to set up your operational run.</li> <li><strong><code>orchestrator.py</code></strong> – Main Python script that manages the entire workflow.</li> <li><strong><code>pipeline.sh</code></strong> – Bash script that activates the <code>tito_env</code> Conda environment and executes <code>orchestrator.py</code> using settings from <code>westafrica1km_config.py</code>.</li> </ul> <div dir="auto"> <h3>Input / Output Directories</h3> </div> <ul> <li><strong><code>basic/</code></strong> – Contains DEM, FAC, and FDIR files.</li> <li><strong><code>pet/</code></strong> – Contains monthly PET (Potential Evapotranspiration) grids.</li> <li><strong><code>parameters/</code></strong> – Contains distributed parameters for the KW and CREST models.</li> <li><strong><code>states/</code></strong> – Stores model state files generated during operational runs.</li> <li><strong><code>outputs/</code></strong> – Output folder where simulation results are saved.</li> <li><strong><code>precip/</code></strong> – IMERG QPE files are downloaded here; QPF files generated by the nowcasting system are also stored here.</li> <li><strong><code>precipEF5/</code></strong> – QPE and QPF files are reformatted and copied here to be ingested by EF5.</li> <li><strong><code>templates/</code></strong> – Stores EF5 control file templates, which are dynamically updated during each run.</li> <li><strong><code>qpf_store/</code></strong> – Stores QPF files for fallback use in case QPE retrieval fails.</li> <li><strong><code>ML/</code></strong> – Contains machine learning routines used to generate QPF forecasts.</li> <li><strong><code>tito_utils/</code></strong> – Collection of utility modules and helper scripts used internally by TITO.</li> </ul> <div dir="auto"> <h2>How to run?</h2> </div> <p dir="auto"><strong>1. Edit the config file:</strong> After completing the installation of the required environment and populating the corresponding EF5 folders, open <code>westafrica_1km_config.py</code> file. There are few lines users need to change in this config file to run TITO successfully:</p> <ul> <li><strong>ef5Path:</strong> Update this path to the corresponding ef5's binary path in your system.</li> <li><strong>HindCastMode:</strong> If you are running an event happened in the PAST, set <code>HindCastMode = True</code> and write the date of interest in <code>HindCastDate</code>, use the format "YYYY-MM-DD HH:MM". If you want to run it in Nowcast Mode (meaning TITO will start running in the present time) set <code>HindCastMode = False</code></li> <li><strong>email_gpm:</strong> This version of TITO uses IMERG Early V07 as QPE, you will need to create and account in GPM server to download precipitation files, please visit <a href="https://registration.pps.eosdis.nasa.gov/registration/" rel="nofollow">NASA GPM registration web page</a> and follow the instruction provided in the webpage. <strong>Important:</strong> use your registration email as password so TITO can use it in the routines.</li> </ul> <p dir="auto"><strong>What if I want to use TITO in other regions?</strong></p> <p dir="auto">If you plan to run TITO outside the default West Africa domain, there are a few important considerations. The machine learning routines were designed and trained using IMERG V07 data (0.1° resolution) over the West Africa region (xmin = −21.4, xmax = 30.4; ymin = −2.9, ymax = 33.1), corresponding to a grid size of <strong>518 × 360 pixels</strong>.</p> <p dir="auto">If you intend to apply TITO to a different region, we recommend selecting an area with the same spatial dimensions (518 × 360 pixels) to ensure compatibility with the input structure. For applications outside the original training domain, we suggest using one of the advection-based algorithms included in the repository—LINDA, STEPS, or the Lagrangian method. Unlike the ConvLSTM-based model, these methods do not require prior training and are not dependent on region-specific climatology or data-driven learning. They rely on physical principles of motion and can be applied directly to precipitation fields in any region, provided the input data has a compatible resolution and format.</p> <p dir="auto"><strong>2. Run TITO:</strong> Run the following line in your terminal:</p> <div dir="auto"> <pre>./pipeline.sh</pre> <div> </div> </div> <div dir="auto"> <h2>Contact</h2> </div> <p dir="auto">Please contact Vanessa Robledo at <a href="mailto:vanessa-robledodelgado@uiowa.edu">vanessa-robledodelgado@uiowa.edu</a> or the <a href="https://ahwa.lab.uiowa.edu/" rel="nofollow">AHWA Laboratory</a> Development team at <a href="mailto:engr-ahwa-lab@uiowa.edu">engr-ahwa-lab@uiowa.edu</a>.</p> <p dir="auto"><strong>For more updates about this package follow our <a href="https://github.com/AHWALab/TITO" target="_blank" rel="noopener">Github Repository</a> </strong></p> |
| format | Recurso digital |
| id | zenodo_https___doi_org_10_5281_zenodo_16753855 |
| institution | Zenodo |
| language | |
| publishDate | 2025 |
| publisher | Zenodo |
| record_format | zenodo |
| spellingShingle | Threading Inputs to Outputs (TITO) Robledo Delgado, Vanessa Vergara, Humberto <p dir="auto">TITO is a framework designed to run the EF5 hydrologic model operationally, integrating satellite data and machine learning techniques to support real-time forecasting and hydrologic analysis.</p> <div dir="auto"> <h2>Installation Instructions</h2> </div> <p dir="auto"><strong>1. Clone the repository</strong></p> <div dir="auto"> <pre>git clone https://github.com/AHWALab/TITO.git</pre> <div> </div> </div> <p dir="auto"><strong>2. Navigate to the repository folder</strong></p> <div dir="auto"> <pre>cd TITO/<br><br></pre> </div> <p dir="auto"><strong>3. Run the set up code</strong> This step might take few minutes.</p> <div dir="auto"> <pre>./setup_tito.sh</pre> <div> </div> </div> <p dir="auto"><strong>4. Add the new conda env to your routines</strong> Open <code>pipeline.sh</code> and change the path to the conda environment, should be something like this:</p> <div> <pre><code>source /Users/$username$/miniconda3/etc/profile.d/conda.sh </code></pre> <div> </div> </div> <p dir="auto">After installation, ensure that your TITO folder contains the following subdirectories and files.</p> <div dir="auto"> <h2>Repository structure</h2> </div> <p dir="auto">This repository is desiged to run EF5 operational over West Africa. Users must populate the required folders with topographic and parameter grids for their region of interest, and modify the EF5 control file (<code>templates/ef5_control_template.txt</code>) accordingly. A guide step-by-step to create the needed layers can be found in: <a href="https://github.com/AHWALab/EF5-builder-toolkit">EF5-builder-toolkit</a>.</p> <div dir="auto"> <h3>Key Files & Folders</h3> </div> <ul> <li><strong><code>westafrica1km_config.py</code></strong> – Configuration file to set up your operational run.</li> <li><strong><code>orchestrator.py</code></strong> – Main Python script that manages the entire workflow.</li> <li><strong><code>pipeline.sh</code></strong> – Bash script that activates the <code>tito_env</code> Conda environment and executes <code>orchestrator.py</code> using settings from <code>westafrica1km_config.py</code>.</li> </ul> <div dir="auto"> <h3>Input / Output Directories</h3> </div> <ul> <li><strong><code>basic/</code></strong> – Contains DEM, FAC, and FDIR files.</li> <li><strong><code>pet/</code></strong> – Contains monthly PET (Potential Evapotranspiration) grids.</li> <li><strong><code>parameters/</code></strong> – Contains distributed parameters for the KW and CREST models.</li> <li><strong><code>states/</code></strong> – Stores model state files generated during operational runs.</li> <li><strong><code>outputs/</code></strong> – Output folder where simulation results are saved.</li> <li><strong><code>precip/</code></strong> – IMERG QPE files are downloaded here; QPF files generated by the nowcasting system are also stored here.</li> <li><strong><code>precipEF5/</code></strong> – QPE and QPF files are reformatted and copied here to be ingested by EF5.</li> <li><strong><code>templates/</code></strong> – Stores EF5 control file templates, which are dynamically updated during each run.</li> <li><strong><code>qpf_store/</code></strong> – Stores QPF files for fallback use in case QPE retrieval fails.</li> <li><strong><code>ML/</code></strong> – Contains machine learning routines used to generate QPF forecasts.</li> <li><strong><code>tito_utils/</code></strong> – Collection of utility modules and helper scripts used internally by TITO.</li> </ul> <div dir="auto"> <h2>How to run?</h2> </div> <p dir="auto"><strong>1. Edit the config file:</strong> After completing the installation of the required environment and populating the corresponding EF5 folders, open <code>westafrica_1km_config.py</code> file. There are few lines users need to change in this config file to run TITO successfully:</p> <ul> <li><strong>ef5Path:</strong> Update this path to the corresponding ef5's binary path in your system.</li> <li><strong>HindCastMode:</strong> If you are running an event happened in the PAST, set <code>HindCastMode = True</code> and write the date of interest in <code>HindCastDate</code>, use the format "YYYY-MM-DD HH:MM". If you want to run it in Nowcast Mode (meaning TITO will start running in the present time) set <code>HindCastMode = False</code></li> <li><strong>email_gpm:</strong> This version of TITO uses IMERG Early V07 as QPE, you will need to create and account in GPM server to download precipitation files, please visit <a href="https://registration.pps.eosdis.nasa.gov/registration/" rel="nofollow">NASA GPM registration web page</a> and follow the instruction provided in the webpage. <strong>Important:</strong> use your registration email as password so TITO can use it in the routines.</li> </ul> <p dir="auto"><strong>What if I want to use TITO in other regions?</strong></p> <p dir="auto">If you plan to run TITO outside the default West Africa domain, there are a few important considerations. The machine learning routines were designed and trained using IMERG V07 data (0.1° resolution) over the West Africa region (xmin = −21.4, xmax = 30.4; ymin = −2.9, ymax = 33.1), corresponding to a grid size of <strong>518 × 360 pixels</strong>.</p> <p dir="auto">If you intend to apply TITO to a different region, we recommend selecting an area with the same spatial dimensions (518 × 360 pixels) to ensure compatibility with the input structure. For applications outside the original training domain, we suggest using one of the advection-based algorithms included in the repository—LINDA, STEPS, or the Lagrangian method. Unlike the ConvLSTM-based model, these methods do not require prior training and are not dependent on region-specific climatology or data-driven learning. They rely on physical principles of motion and can be applied directly to precipitation fields in any region, provided the input data has a compatible resolution and format.</p> <p dir="auto"><strong>2. Run TITO:</strong> Run the following line in your terminal:</p> <div dir="auto"> <pre>./pipeline.sh</pre> <div> </div> </div> <div dir="auto"> <h2>Contact</h2> </div> <p dir="auto">Please contact Vanessa Robledo at <a href="mailto:vanessa-robledodelgado@uiowa.edu">vanessa-robledodelgado@uiowa.edu</a> or the <a href="https://ahwa.lab.uiowa.edu/" rel="nofollow">AHWA Laboratory</a> Development team at <a href="mailto:engr-ahwa-lab@uiowa.edu">engr-ahwa-lab@uiowa.edu</a>.</p> <p dir="auto"><strong>For more updates about this package follow our <a href="https://github.com/AHWALab/TITO" target="_blank" rel="noopener">Github Repository</a> </strong></p> |
| title | Threading Inputs to Outputs (TITO) |
| url | https://doi.org/10.5281/zenodo.16753855 |