Metadata-Version: 2.5
Name: wis2box-json2bufr_WaveBuoyJson
Version: 0.0.5
Summary: This is a wis2box plug in that can convert wavebuoy json to bufr. It converts the json to csv and then uses the existing wis2box csv2bufr facility in the wis2box-api container
Project-URL: Homepage, https://github.com/willself/wis2box-json2bufr_WaveBuoyJson
Project-URL: Issues, https://github.com/willself/wis2box-json2bufr_WaveBuoyJson/issues
Author-email: Bill Self <bill.k.self@gmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# WIS2BOX Wave Buoy JSON to BUFR Plugin

A custom [WIS2BOX](https://github.com/World-Meteorological-Organization/wis2box) data plugin for ingesting wave buoy observations in JSON format and converting them into WMO BUFR messages.

The plugin takes JSON observations from a wave buoy, maps the observation data into the fields defined by a json2csv mapping document and a csv2bufr template, and uses the existing WIS2BOX `wis2box-csv2bufr` process to generate BUFR output.

## Overview

WIS2BOX CSV2BUFR provides a mechanism for converting CSV observations into BUFR, but JSON data needs to be transformed into the expected CSV structure first.

This plugin provides that bridge and was developed for fixed Wave buoy observations. Although it aims to be as generic as possible, being driven by the csv2bufr template, it is untested with any other json. The json2csv part of the plugin uses a template to map the json keys to csv columns. The name of that template file is currently hard coded as WIS2BOX itself needs an update to allow passing the mapping name to the plugin.

### Processing workflow

1. Receive JSON data containing wave buoy observations.
2. Extract the observation data and station metadata.
3. Parse the observation timestamps and convert them to UTC.
4. Map JSON observation fields to the corresponding CSV2BUFR template fields.
5. Populate station identifiers, coordinates and observation date/time fields.
6. Generate CSV data dynamically using the configured CSV2BUFR template.
7. Submit the generated CSV to the WIS2BOX API's existing `wis2box-csv2bufr` process.
8. Return the resulting BUFR data for publication through WIS2BOX.

## Supported observations

The plugin is currently tested handling the following wave observation parameters:

| JSON field | Description |
|---|---|
| `significant_wave_height` | Significant wave height |
| `peak_wave_period` | Spectral peak wave period |
| `peak_wave_direction` | Direction from which dominant waves are coming |
| `time` | Observation timestamp |

Additional fields can be mapped to the CSV2BUFR template using the plugin's JSON field mapping.

## Example input

The plugin expects JSON containing station information and an array of observations.

An individual set of observations has the following structure:

```json
{
    "id": Numeric,
    "wigos_id": "0-nnnnn-0-nnnnnnn",
    "station_id": "Numeric",
    "display_name": "A-Za-z",
    "station_description": "A-Za-z",
    "type": "Wave Buoy",
    "longitude": degrees,
    "latitude": degrees,
    "data_labels": "significant_wave_height,peak_wave_period,peak_wave_direction,time",
    "bad_data": null,
    "mean": 0.0,
    "chart_type": "line",
    "data_limit": 100,
    "data": [{
            "significant_wave_height": 0.37,
            "peak_wave_period": 20.48,
            "peak_wave_direction": 225.718,
            "time": "2026-08-14T02:23:31.000Z"
        }, {
            "significant_wave_height": 0.33,
            "peak_wave_period": 10.24,
            "peak_wave_direction": 28.597,
            "time": "2026-08-14T01:53:31.000Z"
        }, {
            "significant_wave_height": 0.32,
            "peak_wave_period": 20.48,
            "peak_wave_direction": 201.857,
            "time": "2026-08-14T01:23:31.000Z"
        }, {
            "significant_wave_height": 0.28,
            "peak_wave_period": 25.6,
            "peak_wave_direction": 220.914,
            "time": "2026-08-14T00:53:31.000Z"
        }]
}
```

The timestamp is parsed and converted to UTC before being used to populate the corresponding BUFR date and time fields.

The output will be a series of bufr files for each observation timestamp, each with the station data, e.g. wigos id parts. 

## Configuration

The plugin uses the WIS2BOX [CSV2BUFR](https://csv2bufr.readthedocs.io/en/latest/development.html) template to determine the CSV fields required for BUFR encoding.

The template defines:

- BUFR descriptors and their associated CSV fields.
- WIGOS station identifier components.
- Observation date and time fields.
- Station location and other metadata.
- Wave observation parameters.
- Replicated descriptors and their associated fields.

The plugin maps the JSON observation fields to the corresponding template fields before generating the CSV. The [CSV2BUFR](https://csv2bufr.readthedocs.io/en/latest/development.html) tool can be used to generate a csv to bufr template files on the cli.

## BUFR conversion

Rather than implementing a separate BUFR encoder, the plugin uses the existing WIS2BOX API process:

`wis2box-csv2bufr`

The generated CSV is submitted to this process along with the configured channel, metadata identifier and template.

This keeps the BUFR encoding consistent with the existing WIS2BOX CSV2BUFR implementation.

## Installation

Installation and configuration should follow the [WIS2BOX custom plugin](https://docs.wis2box.wis.wmo.int/en/latest/reference/extending-wis2box.html) deployment process.

**Plugin configuration and deployment instructions:** 

Install the plug in in the wis2box management container from [pypi](https://pypi.org/project/wis2box-json2bufr-WaveBuoyJson/)

Place the csv2bufr template in
[WIS2BOX-DATADIR]/mappings/

Place the json mappings file "jsonwave2csv" (the name is currently hardcoded so must match this) in [WIS2BOX-DATADIR]/mappings/

## Requirements

- WIS2BOX
- A configured WIS2BOX data mapping and CSV2BUFR template
- Access to the WIS2BOX API and its `wis2box-csv2bufr` process
- JSON input containing wave buoy observations and station metadata

example data_mappings: config
```yaml
    data_mappings:
        plugins:
            json:
                - plugin: wis2box_json2bufr_WaveBuoyJson.wavejson2bufr.WaveBuoyJson
                  notify: true
                  template: waveob-bufr-mappings
                  # jsonmapping not implemented, plugin will default to this mapping name.
                  jsonmapping: jsonwave2csv
                  buckets:
                    - ${WIS2BOX_STORAGE_INCOMING}
                  file-pattern: '^.*_(\d{8})_.*\.json$'
            bufr4:
                - plugin: wis2box.data.bufr2geojson.ObservationDataBUFR2GeoJSON
                  buckets:
                    - ${WIS2BOX_STORAGE_PUBLIC}
                  file-pattern: '^WIGOS_(\d-\d+-\d+-\w+)_.*\.bufr4$'
```

## Development

The plugin is written in Python and uses the WIS2BOX data plugin framework.

The main processing logic is contained in:

`wavejson2bufr.py`

The plugin handles JSON parsing, observation mapping and CSV generation. BUFR encoding is delegated to the existing WIS2BOX API process.

## Licence

[LICENSE](https://github.com/willself/wis2box-json2bufr_WaveBuoyJson/edit/main/LICSNSE)

