bluemath_tk.downloaders.noaa package

Submodules

bluemath_tk.downloaders.noaa.noaa_downloader module

class bluemath_tk.downloaders.noaa.noaa_downloader.NOAADownloader(base_path_to_download: str, debug: bool = True, check: bool = False)[source]

Bases: BaseDownloader

This is the main class to download and read data from NOAA.

config

The configuration for NOAA data sources loaded from JSON file.

Type:

dict

base_path_to_download

Base path where the data is stored.

Type:

Path

debug

Whether to run in debug mode.

Type:

bool

Examples

from bluemath_tk.downloaders.noaa.noaa_downloader import NOAADownloader

noaa_downloader = NOAADownloader(
    base_path_to_download="/path/to/NOAA/",  # Will be created if not available
    debug=True,
    check=True,
)

# Download buoy bulk parameters and load DataFrame
result = noaa_downloader.download_data(
    data_type="bulk_parameters",
    buoy_id="41001",
    years=[2020, 2021, 2022],
    load_df=True
)
print(result)

None
config = {'data_types': {'bulk_parameters': {'columns': ['YYYY', 'MM', 'DD', 'hh', 'mm', 'WD', 'WSPD', 'GST', 'WVHT', 'DPD', 'APD', 'MWD', 'BAR', 'ATMP', 'WTMP', 'DEWP', 'VIS', 'TIDE'], 'dataset': 'buoy_data', 'description': 'Wind, wave, temperature, and pressure measurements', 'fallback_urls': ['view_text_file.php?filename={buoy_id}h{year}.txt.gz&dir=data/historical/stdmet/', 'stdmet/{year}/{buoy_id}h{year}.txt.gz'], 'file_format': 'txt.gz', 'long_name': 'Standard Meteorological Data', 'name': 'bulk_parameters', 'url_pattern': 'historical/stdmet/{buoy_id}h{year}.txt.gz'}, 'directional_spectra': {'coefficients': {'d': {'name': 'alpha1', 'url_pattern': 'historical/swdir/{buoy_id}d{year}.txt.gz'}, 'i': {'name': 'alpha2', 'url_pattern': 'historical/swdir2/{buoy_id}i{year}.txt.gz'}, 'j': {'name': 'r1', 'url_pattern': 'historical/swr1/{buoy_id}j{year}.txt.gz'}, 'k': {'name': 'r2', 'url_pattern': 'historical/swr2/{buoy_id}k{year}.txt.gz'}, 'w': {'name': 'c11', 'url_pattern': 'historical/swden/{buoy_id}w{year}.txt.gz'}}, 'dataset': 'buoy_data', 'description': 'Fourier coefficients for directional wave spectra', 'file_format': 'txt.gz', 'long_name': 'Directional Wave Spectra Coefficients', 'name': 'directional_spectra'}, 'wave_spectra': {'dataset': 'buoy_data', 'description': 'Wave energy density spectra', 'file_format': 'txt.gz', 'long_name': 'Wave Spectral Density', 'name': 'wave_spectra', 'url_pattern': 'historical/swden/{buoy_id}w{year}.txt.gz'}, 'wind_forecast': {'dataset': 'forecast_data', 'description': 'Wind speed and direction forecast from GFS model', 'file_format': 'netcdf', 'long_name': 'GFS Wind Forecast', 'name': 'wind_forecast', 'output_variables': {'u10': 'ugrd10m', 'v10': 'vgrd10m'}, 'variables': ['ugrd10m', 'vgrd10m']}}, 'datasets': {'buoy_data': {'base_url': 'https://www.ndbc.noaa.gov/data', 'description': 'Historical buoy measurements from NDBC', 'mandatory_fields': ['buoy_id', 'year'], 'name': 'NOAA Buoy Data', 'template': {'buoy_id': None, 'data_type': 'bulk_parameters', 'year': None}}, 'forecast_data': {'base_url': 'https://nomads.ncep.noaa.gov/dods/gfs_0p25_1hr', 'description': 'GFS 0.25 degree forecast data', 'mandatory_fields': ['date'], 'name': 'NOAA GFS Forecast Data', 'template': {'date': None}}}}
property data_types: dict
property datasets: dict
download_data(data_type: str, load_df: bool = False, **kwargs) → DataFrame | Dataset | str[source]

Downloads the data for the specified data type.

Parameters:

  • data_type (str) – The data type to download. - ‘bulk_parameters’ - ‘wave_spectra’ - ‘directional_spectra’ - ‘wind_forecast’

  • load_df (bool, optional) – Whether to load and return the DataFrame after downloading. Default is False. If True and multiple years are specified, all years will be combined into a single DataFrame.

  • **kwargs – Additional keyword arguments specific to each data type.

Returns:

Downloaded data or status message.

Return type:

Union[pd.DataFrame, xr.Dataset, str]

Raises:

ValueError – If the data type is not supported.

list_data_types() → List[str][source]

Lists the available data types.

Returns:

The list of available data types.

Return type:

List[str]

list_datasets() → List[str][source]

Lists the available datasets.

Returns:

The list of available datasets.

Return type:

List[str]

num_workers: int
read_bulk_parameters(buoy_id: str, years: int | List[int]) → DataFrame | None[source]

Read bulk parameters for a specific buoy and year(s).

Parameters:

  • buoy_id (str) – The buoy ID.

  • years (Union[int, List[int]]) – The year(s) to read data for. Can be a single year or a list of years.

Returns:

DataFrame containing the bulk parameters, or None if data not found.

Return type:

Optional[pd.DataFrame]

read_directional_spectra(buoy_id: str, years: int | List[int]) → Tuple[DataFrame | None, ...][source]

Read directional spectra data for a specific buoy and year(s).

Parameters:

  • buoy_id (str) – The buoy ID

  • years (Union[int, List[int]]) – The year(s) to read data for. Can be a single year or a list of years.

Returns:

Tuple containing DataFrames for alpha1, alpha2, r1, r2, and c11, or None for each if data not found

Return type:

Tuple[Optional[pd.DataFrame], …]

read_wave_spectra(buoy_id: str, years: int | List[int]) → DataFrame | None[source]

Read wave spectra data for a specific buoy and year(s).

Parameters:

  • buoy_id (str) – The buoy ID.

  • years (Union[int, List[int]]) – The year(s) to read data for. Can be a single year or a list of years.

Returns:

DataFrame containing the wave spectra, or None if data not found

Return type:

Optional[pd.DataFrame]

show_markdown_table() → None[source]

Create a Markdown table from the configuration dictionary and print it.

Module contents