Welcome to metocean-api’s documentation!

metocean-api is a Python tool to extract time series of metocean data from global/regional/coastal hindcasts/reananalysis.

The package contains functions to extract time series to csv-format from:

NORA3 hindcast dataset
ERA5 reanalysis dataset

Installing metocean-api

Alternative 1: Using Mambaforge (alternative to Miniconda)

Install mambaforge (download)
Set up a Python 3 environment for metocean-api and install metocean-api

$ mamba create -n metocean-api python=3 metocean-api
$ conda activate metocean-api

Alternative 2: Using Mambaforge (alternative to Miniconda) and Git

Install mambaforge (download)
Clone metocean-api:

$ git clone https://github.com/MET-OM/metocean-api.git
$ cd metocean-api/

Create environment with the required dependencies and install metocean-api

$ mamba env create -f environment.yml
$ conda activate metocean-api
$ pip install --no-deps -e .

This installs the metocean-api as an editable package. Therefore, you can directly make changes to the repository or fetch the newest changes with git pull.

To update the local conda environment in case of new dependencies added to environment.yml:

$ mamba env update -f environment.yml

Creating a TimeSeries-object

This section documents the ts-module. The ts-object is initialized with the following python command:

from metocean_api import ts
df_ts = ts.TimeSeries(lon=1.320, lat=53.324,
                   start_time='2000-01-01', end_time='2000-03-31' ,
                   product='NORA3_wind_wave')

Several options for product are available. Please check the data catalog for the time coverage:

For wind NORA3 sub data (Nordic Area): product=’NORA3_wind_sub’

Dataset: https://thredds.met.no/thredds/catalog/nora3_subset_atmos/wind_hourly/catalog.html
For atmospheric (pressure,temperature,precipitation,humidity, radiation) NORA3 sub data (Nordic Area): product=’NORA3_atm_sub’

Dataset: https://thredds.met.no/thredds/catalog/nora3_subset_atmos/atm_hourly/catalog.html
For wave NORA3 sub data (Nordic Seas): product=’NORA3_wave_sub’

Dataset: https://thredds.met.no/thredds/catalog/nora3_subset_wave/wave_tser/catalog.html
For combined wind and wave NORA3 sub data (Nordic Seas): product=’NORA3_wind_wave’
For wave NORA3 data (Nordic Seas + Arctic): product=’NORA3_wave’

Dataset: https://thredds.met.no/thredds/catalog/windsurfer/mywavewam3km_files/catalog.html
For sea level NORA3 data (Nordic Seas): product=’NORA3_stormsurge’

Dataset: https://thredds.met.no/thredds/catalog/stormrisk/catalog.html
For coastal wave NORA3 data: product=’NORAC_wave’

Dataset: https://thredds.met.no/thredds/catalog/norac_wave/field/catalog.html
For global reananalysis ERA5 (wind and waves): product=’ERA5’

The user needs to install the CDS API key according to https://cds.climate.copernicus.eu/api-how-to ,

Dataset: https://doi.org/10.24381/cds.adbb2d47

Import data from server to ts-object and save it as csv:

df_ts.import_data(save_csv=True)

Data is saved in:

print(df_ts.datafile) #'NORA3_wind_wave_lon1.32_lat53.324_20000101_20000331.csv'

To import data from a local csv-file to ts-object:

df_ts.load_data(local_file=df_ts.datafile)
print(df_ts.data)

To combine several csv-files produced by metocean-api:

df = ts.ts_mod.combine_data(list_files=['NORA3_wind_sub_lon1.32_lat53.324_20210101_20210131.csv',
                                        'NORA3_atm_sub_lon1.32_lat53.324_20210101_20210331.csv'],
                                output_file='combined_NORA3_lon1.32_lat53.324.csv')