IceNet SIPN South Diagnostics Generator

Welcome to the IceNet SIPN South Diagnostics Generator. This Python-based project is designed to compute and visualise various diagnostics as per the SIPN South call for contribution. It covers. It can take either individual ensemble member Sea Ice Concentration or the mean and compute the necessary diagnostics for submission to SIPN South. The primary goal of this tool is to provide an easy-to-use interface for generating the diagnostic outputs in the required format for submission to SIPN South.

This has only been tested on a Linux x86 system.

Table of Contents

1. Installation
2. Usage
   • Python Diagnostics Generation
   • Plotting Sea Ice Area Time Series
   • CLI Diagnostics Generation
3. Contributing
4. License

Installation

To use this tool, first clone the repository and install its dependencies using pip:

git clone https://github.com/icenet-ai/icenet-sipn-south.git
cd icenet-sipn-south
pip install -e .[docs]

Usage

Python: Sea Ice Area Calculation

The SIPNSouthOutputs class is at the core of this project. It provides methods to compute daily and monthly sea ice area (SIA) from IceNet model outputs, OSI-SAF observations, or IceNet ensemble runs.

As a prerequisite, icenet should be installed in the Python environment.

If Masks data has not previously been downloaded with IceNet, run:

icenet_data_masks south

If hindcasting, the observational OSI-SAF data should already be downloaded. E.g.:

icenet_data_sic south -d 2022-12-1 2022-2-28

Here's a basic example of how to use this package to generate the diagnostic outputs for SIPN South submission:

from icenet_sipn_south import SIPNSouthOutputs

# Location of the icenet-pipeline with the prediction outputs
root = "../../pipeline"

# Name of the prediction run, found under `pipeline/results/predict/`
predict_name = "fc.2024-11-30_south"

# Start date for our forecast
forecast_init_date = "2022-11-30"

# IceNet by default forecasts up to 93 days ahead, can instead limit forecast end date for analysis
forecast_leadtime = 90

prediction = SIPNSouthOutputs(prediction_pipeline_path=root,
                        prediction_name=predict_name,
                        forecast_init_date=forecast_init_date,
                        forecast_leadtime=forecast_leadtime, # Optional
                        hemisphere="south", # This code is meant for the Southern hemisphere
                        get_obs=True, # Set to False if not hindcasting or OSI-SAF
                                      # observational data not already downloaded
                        )

# Diagnostic 1
# Antarctic (circumpolar) daily mean sea-ice area from December 1st 2022 to February 28th 2023 included (90 days).
prediction.diagnostic_1(method=method)

# Diagnostic 2
# February Antarctic daily mean sea-ice area per 10° longitude bin, from December 1st 2022 to February 28th 2023 included (90 days).
prediction.diagnostic_2(method=method)

# Diagnostic 3
# February Antarctic daily mean sea-ice concentration Format: A NetCDF file with 90 timesteps (one per day from December 1st 2022 to February 28th 2023). Each time step displays the spatial field of sea-ice concentration.
prediction.diagnostic_3(method=method)

Plotting Sea Ice Area Time Series

Once you've computed the SIA data by generating diagnostic_1, you can generate a time series plot using the plot_sia() method:

prediction.plot_sia()

This will produce an interactive plot showing mean sea ice area from the IceNet model, along with optional ensemble run results and observed SIA from OSI-SAF (if available).

CLI: Diagnostics Generation

A simpler approach would be to use the command line option:

$ icenet_sipnsouth_diagnostics ../../pipeline fc.2022-11-30_south 2022-11-30 -d 1,2,3 -p -m ensemble -fl 90

To get help on what the default and optional arguments do:

$ icenet_sipnsouth_diagnostics --help
usage: icenet_sipnsouth_diagnostics [-h] [-d DIAGNOSTICS] [-fl FORECAST_LEADTIME] [-go] [-m {ensemble,mean}] [-p] pipeline_path predict_name forecast_init_date

positional arguments:
  pipeline_path         Path to the root IceNet-pipeline directory
  predict_name          Name of prediction (found under `pipeline/results/predict/`)
  forecast_init_date    Start date of the forecast to use

options:
  -h, --help            show this help message and exit
  -d DIAGNOSTICS, --diagnostics DIAGNOSTICS
                        Comma separated list of diagnostics to run, Options: `1,2,3`
  -fl FORECAST_LEADTIME, --forecast_leadtime FORECAST_LEADTIME
                        IceNet by default forecasts up to 93 days ahead, can instead specify how many days to process for this diagnostic, Default=90
  -go, --get-obs        Whether to include OSI-SAF observational data in plot/processing
  -m {ensemble,mean}, --method {ensemble,mean}
                        Whether to process ensemble of predictions or ensemble mean
  -p, --plot            Whether to show any plots

Documentation

To build and view the Sphinx documentation, generate and open the HTML documentation via the following commands:

make html
make open

Contributing

Contributions are welcome! If you encounter any bugs or have suggestions for improvement, please submit an issue or pull request. To contribute:

1. Fork this repository.
2. Create a new branch: git checkout -b new-branch.
3. Make your changes and commit them: git commit -m 'Commit message'.
4. Push to the branch: git push origin new-branch.
5. Submit a pull request.

License

This project is licensed under the MIT License. See the LICENSE file for more details.

---