Create SIMA Scatter

Source Code

create_sima_scatter.py
  1
  2"""
  3# Create SIMA Scatter Tables
  4
  5This example demonstrates how to create metocean scatter tables and save them in 
  6SIMA-compatible format using the SIMAPy API.
  7
  8## Description
  9
 10The script shows how to create metocean scatter tables from external data sources
 11(using the [metocean stats library](https://metocean-stats.readthedocs.io)) and save them for use in SIMA. 
 12The workflow includes:
 13
 141. Using the `metocean_stats` library to retrieve wave data for a specific location and time period
 152. Calculating a scatter table from the time series data (significant wave height vs. peak period)
 163. Converting the data to SIMA's internal scatter table format
 174. Exporting the scatter table to a SIMA-compatible HDF5 file
 18
 19## Key Features
 20
 21- **Metocean Data Access**: Demonstrates accessing wave data from the NORA3 dataset
 22- **Statistical Analysis**: Shows how to generate scatter tables from time series data
 23- **SIMA Integration**: Converts the data to SIMA's internal data structures
 24- **DMT Export**: Saves the data in SIMA's Data Model Technology (DMT) format
 25
 26## Usage
 27
 28This example is particularly useful for:
 29
 30- Creating site-specific metocean data for marine simulations
 31- Preparing environmental conditions for design or operational analysis
 32- Generating scatter tables for fatigue analysis or operational assessments
 33
 34```python
 35# Basic usage of this script
 36python create_sima_scatter.py
 37```
 38
 39The exported HDF5 file can be imported directly into SIMA by right-clicking on a 
 40Metocean Task and selecting "Import metocean data".
 41"""
 42from pathlib import Path
 43import pandas as pd
 44from metocean_api import ts
 45from metocean_stats.stats.general import calculate_scatter
 46from simapy.metocean.scatter.scatter import Scatter as SimaScatter
 47from simapy.metocean.scatter.sector import Sector
 48from simapy.metocean.scatter.wave import Wave
 49from dmt.dmt_writer import DMTWriter
 50
 51
 52def _create_sima_scatter(scatter: pd.DataFrame) -> SimaScatter:
 53    """
 54    Convert a pandas DataFrame scatter table to a SIMA scatter object.
 55    
 56    This function takes a pandas DataFrame containing a wave scatter table
 57    (with significant wave height as index and peak period as columns)
 58    and converts it to a SIMA scatter object that can be saved in SIMA's
 59    native format.
 60    
 61    Args:
 62        scatter (pd.DataFrame): DataFrame containing the scatter table with
 63                               Hs as index and Tp as columns
 64                               
 65    Returns:
 66        SimaScatter: A SIMA scatter object ready for export
 67    """
 68    sima_scatter = SimaScatter()
 69    sima_scatter.name = "Scatter"
 70    hs = scatter.index
 71    tp = scatter.columns
 72    occurences = scatter.values
 73
 74    sima_scatter.hsUpperLimits = hs
 75    sima_scatter.tpUpperLimits = tp
 76
 77    omni = Sector()
 78    omni.name = "Omni"
 79    omni.description = f"Omni-directional scatter table created from product {product} for the period {start_date} to {end_date}"
 80    sima_scatter.omni = omni
 81    wave = Wave()
 82    wave.occurrence = occurences
 83    omni.wave = wave
 84    return sima_scatter
 85
 86if __name__ == "__main__":
 87    lat_pos = 62.5365
 88    lon_pos = 4.1770
 89    start_date = "2020-10-21"
 90    end_date = "2020-11-21"
 91
 92    product = "NORA3_wave_sub"
 93    var1_name = "hs"
 94    var2_name = "tp"
 95
 96    var1_block_size = 1.0
 97    var2_block_size = 2.0
 98
 99    requested_values = [var1_name, var2_name]
100
101    df_ts = ts.TimeSeries(
102        lon=lon_pos,
103        lat=lat_pos,
104        start_time=start_date,
105        end_time=end_date,
106        variable=requested_values,
107        product=product,
108    )
109
110    df_ts.import_data(save_csv=False, save_nc=False, use_cache=True)
111
112    scatter: pd.DataFrame = calculate_scatter(df_ts.data, var1_name, var1_block_size, var2_name, var2_block_size)
113
114    sima_scatter = _create_sima_scatter(scatter)
115
116    path = Path(f"./output/simamet/scatter_{product}-{start_date}-{end_date}.h5")
117    path.parent.mkdir(parents=True, exist_ok=True)
118    DMTWriter().write(sima_scatter, path)
119    print(f"Saved to {path.resolve()}")