Overview

This guide will walk you through signing up for the necessary account and then choosing between two methods to download and clip the tide model for use in CoastSeg.

Part 1: Signing Up for the FES2014 Model

Step 1: Register for an AVISO+ Account

Step 1: Register for an AVISO+ Account

1. Visit the registration form at AVISO+ Registration.(its free)
2. Fill out the form with your details
3. Make sure to select FES2014 / FES2012 (Oceanic Tides Heights) in the model selection section.
4. Submit the form and wait for a confirmation email.

Step 2: Verify Your AVISO+ Account

1. Check your email for a confirmation from AVISO+.
2. Click the verification link in the email to activate your account.

Step 3: Access Your Subscriptions

1. Log into your AVISO account.
2. Navigate to My products in the left side menu.
3. Confirm that FES2014 / FES2012 (Oceanic Tides Heights) is listed under Your current subscriptions.
   

Part 2: Downloading and Clipping the Tide Model

You have two options to download and clip the tide model: using a Jupyter Notebook (Recommended) or using a Script (Alternative). Choose one based on your comfort level and requirements.

Space and Time Requirements

• Storage Space: Ensure you have at least 14GB of free space available.
• Time Commitment: The download and setup process for the fes2014 model takes approximately 1-2 hours. This is a one-time requirement.

Option 1: Using the Download_tide_model.ipynb Notebook (Recommended)

The easiest way to download and clip the tide model is to use this notebook. Run all the code in the notebook and you're done!

1. Prepare: Ensure you have you are in an activated coastseg environment and know your AVISO email and password.
2. Open Notebook: Launch Download_tide_model.ipynb in Jupyter Notebook.

cd CoastSeg
jupyter lab Download_tide_model.ipynb

3.Run Code: Execute all cells in the notebook. The code will guide you through the download and clipping process automatically.

4.Check Results: Confirm that the model files are correctly downloaded and clipped in the specified directory.

• Example Output from Downloading Tide Model Step in Notebook

• Example Output from Clipping Tide Model Step in Notebook

5.Downloaded Tide Model Contents

Option 2: Using the Script (Alternative)

Setup

1. Create Directory: Navigate to your CoastSeg installation directory and create a new folder named tide_model.
2. Script Location: Change directory to the scripts folder within CoastSeg.

cd <location of your coastseg directory>
mkdir tide_model
cd scripts

Download & Clip

1. Run Download Script: Execute the aviso_fes_tides.py script with the necessary parameters, including your AVISO credentials and target directory for the tide model.

2. ⚠️ Enter your AVISO password when prompted. Note that the password won't display as you type. After you have finished typing, press Enter to proceed.

3. Replace C:\Users\Sample\coastseg with the actual location of your CoastSeg directory.
4. Example command:

 python aviso_fes_tides.py --user your_email@example.com -D C:\Users\Sample\coastseg\tide_model --load --log --tide FES2014 -G

1. Clip Model to Regions: After downloading, run the clip_and_write_new_nc_files_cmd_line.py script with the paths to your tide model directory and the regions geojson file.

To make the tide predictions compute faster we will clip the model it to various regions across the planet. After we've clipped the model to each region, when we want to predict the tide at a particular latitude and longitude we first figure out which region the point lies within, then we load the tide model we clipped to that region.

• -R or --regions_file the full path to the regions geojson file. You should find this file tide_regions_map.geojson in the scripts
• -T or --tide_model the full path to the directory containing the tide model downloaded
• Replace C:\Users\Sample\coastseg with the actual location of your CoastSeg directory.

python clip_and_write_new_nc_files_cmd_line.py -T C:\Users\Sample\coastseg\tide_model -R C:\Users\Sample\coastseg\scripts\tide_regions_map.geojson

1. Validate: Ensure each region directory under tide_model contains clipped tide model files.

2. Each region will have the same format as region0 the full list of files is omitted for brevity.

├── CoastSeg
|
|___scripts
|    |_ aviso_fes_tides.py
|    |_ clip_and_write_new_nc_files_cmd_line.py
|    |_ tide_regions_map.geojson
|
|___tide_model
|    |_ fes2014
|    |     |_load_tide
|    |     |       |__2n2.nc.gz
|    |     |       |__eps2.nc.gz
|    |     |       |__ ....
|    |     |_ocean_tide
|    |     |       |__2n2.nc.gz
|    |     |       |__eps2.nc.gz
|    |     |       |__ ....
|    |
|    |_ region0
|    |     |_fes2014
|    |     |       |__load_tide
|    |     |       |       |__2n2.nc
|    |     |       |       |__eps2.nc
|    |     |       |       |__....
|    |     |       |__ocean_tide
|    |     |       |       |__2n2.nc
|    |     |       |       |__eps2.nc
|    |     |       |       |__....
|    |_ region1
|    |_ region2
|    |_ region3
|    |_ region4
|    |_ region5
|    |_ region6
|    |_ region7
|    |_ region8
|    |_ region9
|    |_ region10

4.Downloaded Tide Model Contents

Running into Problems?

---

1. Your account may not be verified yet, which means you can't download the model
2. Occasionally the AVISO server goes down. Wait a few hours and try again and see if its working.

Troubleshooting

If you are running coastseg on a secure network you may need to make the following modifications to your .condarc file.

1. If you get an error message similar to CondaValueError: You have chosen a non-default solver backend(libmamba) but it was not recongized
2. Solution: comment out the line in the .condarc file solve:libmamba
3. You may also need to modify the ssl_verify to either True or False depending on your network security.
4. Always switch ssl_verify to True if you ever set it it to False for debugging purposes.

How to Perform Tide Correction

⚠️ You must have run the script to download the FES2014 tide model before attempting to correct tides This script provides utilities for modeling tides and correcting time series data based on tide predictions.

⚠️ Important: Read Before Using Tide Correction Button

If the tide model was NOT downloaded to CoastSeg/tide_model then the tide correction button will NOT work. The tide correction button will try to load the tide model from <CoastSeg location>/tide_model and an error will occur. Instead follow the instructions in at Option 2: Tide Correction Script

If you downloaded the tide model to a different location follow the instructions at Option 2: Tide Correction Script to use the script apply_tidal_correction.py

Option 1: Tide Correction Button Method

Ever since coastseg 1.1.0 released you can now use the correct tides button in coastseg to automatically correct the timeseries. This button will automatically find which files need to be tidally corrected and apply the tidal correction for you.

⚠️ Important

If the tide model was NOT downloaded to CoastSeg/tide_model then the tide correction button will NOT work. The tide correction button will try to load the tide model from <CoastSeg location>/tide_model and an error will occur. Instead follow the instructions in at Option 2: Tide Correction Script

Steps

WARNING You must have downloaded the tide model to the tide_model folder within coastseg for this button to work correctly.

1. Enter the beach slope

2. This is the beach slope in meters for the ROI you have selected.

3. Enter the beach elevation

4. This is the beach elevation in meters for the ROI you have selected.

5. Select the ROIs' ids to tidally correct

6. Click compute tides and wait a few minutes.

If you encounter any issues or have any questions please submit an issue at CoastSeg Issues

Option 2: Tide Correction Script

⚠️ If the tide model was NOT downloaded to CoastSeg/tide_model, then you must use the tide correction script.

Example 1: Apply Tide Correction to a session and provide tide model location

1. Choose a session
2. In this example I will be using session dnz3_extract_shorelines_10_yr and using ROI ID_dnz3_datetime12-22-23__09_10_44
3. Example: C:\development\doodleverse\coastseg\CoastSeg\sessions\dnz3_extract_shorelines_10_yr\ID_dnz3_datetime12-22-23__09_10_44
4. Get the location of the config_gdf.geojson file
5. This parameter is used after the -C
6. Example: -C "C:\development\doodleverse\coastseg\CoastSeg\sessions\dnz3_extract_shorelines_10_yr\ID_dnz3_datetime12-22-23__09_10_44\config_gdf.geojson"
7. Get the location of the transect_time_series.csv file
8. This parameter is used after the -T
9. Example: -T "C:\development\doodleverse\coastseg\CoastSeg\sessions\dnz3_extract_shorelines_10_yr\ID_dnz3_datetime12-22-23__09_10_44\transect_time_series.csv"
10. Get the location of the tide_model
11. This parameter is used after the -M
12. Example: -M "C:\development\doodleverse\coastseg\CoastSeg\tide_model"
13. Select a Beach Elevation
14. This is the elevation of the beach in meters for the ROI you have selected
15. Example: -E 3.2
16. Select a Beach Slope
17. This is the slope of the beach in meters for the ROI you have selected
18. Example: -S 2.1
19. Assemble the command
20. Assemble all commands into a single line. I recommended using notepad to combine all the commands into a single line

    python apply_tidal_correction.py -E 3.2 -S 2.1 -C
    "C:\development\doodleverse\coastseg\CoastSeg\sessions\dnz3_extract_shorelines_10_yr\ID_dnz3_datetime12-22-23__09_10_44\config_gdf.geojson" -T
    "C:\development\doodleverse\coastseg\CoastSeg\sessions\dnz3_extract_shorelines_10_yr\ID_dnz3_datetime12-22-23__09_10_44\transect_time_series.csv"
    -M "C:\development\doodleverse\coastseg\CoastSeg\tide_model"
    

21. Run the command
22. It takes a few minutes to predict the tides

Parameters:

1. -C (or -c) [CONFIG_FILE_PATH]

2. Description: Path to the configuration file.

3. Example: -C "path_to_config_file"

4. CONFIG_FILE_PATH: Path to the configuration file. This is the config_gdf.geojson in the session directory generated when shorelines were extracted

5. -T (or -t) [RAW_TIMESERIES_FILE_PATH]

6. Description: Path to the raw timeseries file.

7. Example: -T "path_to_timeseries_file"

8. RAW_TIMESERIES_FILE_PATH: Path to a csv file containing the time series created by extracting shorelines with coastseg. This timeseries represents the intersection of each transect with the shoreline extracted for a particular date and time. It is not tidally corrected.

9. -E (or -e) [REFERENCE_ELEVATION]

10. Description: Set the reference elevation value. This is a float number.

11. Example: -E 3

12. -S (or -s) [BEACH_SLOPE]

13. Description: Set the beach slope value. This is a float number.
14. Example: -S 2

Optional Configuration Options

If you didn't install the tide model in the default location you will need to modify the following variables

1. -P (or -p) [TIDE_PREDICTIONS_FILE_NAME]

2. Description: File name for saving a csv file containing the tide predictions for each date time in the timeseries provided.

3. By Default this file is named "tidal_predictions.csv"

4. Example: -P "tidal_predictions.csv"

5. -O (or -o) [TIDALLY_CORRECTED_FILE_NAME]

6. Description: File name for saving the tidally corrected time series csv file.

7. By Default this file is named "tidally_corrected_time_series.csv"

8. Example: -O "tidally_corrected_time_series.csv"

9. -R (or -r) [MODEL_REGIONS_GEOJSON_PATH]

10. Description: Path to the model regions GeoJSON file.

11. By default the program looks for tide_regions_map.geojson in the scripts directory
12. Example: -R "c:\coastseg\scripts\tide_regions_map.geojson"

13. MODEL_REGIONS_GEOJSON_PATH: Path to the location of the geojson file containing the regions used to create the clipped tide model in the previous steps. This file is typically located in the scripts directory within coastseg. "c:\coastseg\scripts\tide_regions_map.geojson"`

14. -M (or -m) [FES_2014_MODEL_PATH]

15. Description: Path to the FES 2014 tide model directory.
16. Example: -M "c:\coastseg\tide_model"
17. FES_2014_MODEL_PATH: Path to the FES 2014 tide model, by default attempts to load from coastseg\tide_model if you installed the tide_model from step 3 in a different location modify this variable to have the full location to the directory containing the clipped 2014 fes tide model.

Running the script:

Use the parameters as described while executing the script. Here's an example usage: Example 1: Only Required Parameter

cd scripts
python apply_tidal_correction.py -C "path_to_config" -T "path_to_timeseries" -E 3 -S 2

python apply_tidal_correction.py -E 3 -S 2 -C "C:\development\doodleverse\coastseg\CoastSeg\sessions\fire_island\ID_ham1_datetime08-03-23__10_58_34\config_gdf.geojson" -T "C:\development\doodleverse\coastseg\CoastSeg\sessions\fire_island\ID_ham1_datetime08-03-23__10_58_34\transect_time_series.csv"

Example 2: All Available Parameters

cd scripts
python apply_tidal_correction.py -C "path_to_config" -T "path_to_timeseries" -E 3 -S 2 -P "predictions.csv" -O "corrected.csv" -R "regions.geojson" -M "model_directory"

cd scripts
python apply_tidal_correction.py -E 3 -S 2 -C "C:\development\doodleverse\coastseg\CoastSeg\sessions\fire_island\ID_ham1_datetime08-03-23__10_58_34\config_gdf.geojson" -T "C:\development\doodleverse\coastseg\CoastSeg\sessions\fire_island\ID_ham1_datetime08-03-23__10_58_34\transect_time_series.csv" -P "tidal_predictions.csv" -O "tidally_corrected_time_series.csv" -R "C:\development\doodleverse\coastseg\CoastSeg\scripts\tide_regions_map.geojson" -M "C:\development\doodleverse\coastseg\CoastSeg\tide_model"

Results

The results will be located in the scripts directory where the apply_tidal_correction.py script is located.

• tidal_predictions.csv: Contains the tide predictions for each datetime in the timeseries csv file given by RAW_TIMESERIES_FILE_PATH.
• "tidally_corrected_time_series.csv": Contains the tidally corrected time series data based on the timeseries csv file given by RAW_TIMESERIES_FILE_PATH.

Credits

Thank you DEA-Coastlines for making a guide on how to use pyTMD and pyTMD for making a easy to use script to download the AVISO FES 2014 Model. The model_tides in this code has been modified and the original function was originally written by Robbi Bishop-Taylor for the dea-tools package https://github.com/GeoscienceAustralia/dea-notebooks/blob/develop/Tools/dea_tools/coastal.py#L466-L473