EIDA Embargo Roller

Description

This program processes a stationXML file in input and updates channels epochs to reflect the embargo start date specified.

Processing Logic:

1. If the channel epoch ends before the embargo: No changes are made.
2. If the channel epoch ends after the embargo:
   • If the epoch starts before the embargo and the restriction policy is closed, the epoch is split at the embargo date:
     1. The restriction policy before the embargo is forced to open.
     2. The restriction policy after the embargo remains closed.
3. After processing, the program merges channels that are contiguous in time and have the same content.

Usage

You can run eida_embargo_roller in two ways:

1. Using uv (Recommended)
2. Directly via Python

Installation

Option 1: Using uv (Recommended)

Install and run using uvx

uvx eida_embargo_roller [-i] [-e YYYY-MM-DD] station.xml

Or install from the repository:

#Clone the repository
git clone https://github.com/your-repo/embargo-roller.git
cd embargo-roller

# Sync dependencies
uv sync 

# Run the script
uv run eida_embargo_roller -e YYYY-MM-DD station.xml

If uv is not already installed, you can add it by following this guide.

Rust and Cargo Requirement

Certain dependencies (e.g., pendulum) require Rust and Cargo to build. If you encounter errors such as maturin failing due to missing Cargo, install Rust and Cargo by following the official Rust installation guide.

Option 2: Using pip

1. Install the package via pip:

python -m pip install --user eida_embargo_roller

2. Run the script:

eida_embargo_roller -e YYYY-MM-DD station.xml

Examples

This section provides examples of how to use eida_embargo_roller in different scenarios.

Writing a New XML File

To write a new XML file with an embargo date:

uvx eida_embargo_roller Z3.A190A.xml -e 2023-01-01 > result.xml

or without uv:

eida_embargo_roller Z3.A190A.xml -e 2023-01-01 > result.xml

Modifying an Existing XML File (In-Place)

To transform the file in place:

uvx eida_embargo_roller -e 2023-01-01 -i Z3.A190A.xml

or without uv:

eida_embargo_roller -e 2023-01-01 -i Z3.A190A.xml

Tests and Debugging

Running Tests

To run the entire test suite using pytest, execute:

uv run pytest

PyPI package

The EIDA Embargo Roller is also available as a PyPI package: https://pypi.org/project/eida-embargo-roller/

Updating SeisComP configuration

Embargo roller works with FDSN XML only, not with inventoryXML used by SeisComP. Following steps describe the procedure for updating config:

1. Convert to stationXML:

   fdsnxml2inv --to-staxml inventory.xml > FDSNstation.xml

2. Update embargo period:

   uv run eida_embargo_roller -e 2022-12-31 FDSNstation.xml > FDSNstation-embargoFree.xml

3. Replace restrictedStatus “partial” by “open” in FDSNstation-embargoFree.xml (Seiscomp does not recognize “partial” status):

   sed -e 's/"partial"/"open"/'

4. Convert FDSNstation-embargoFree.xml to invXML:

   fdsnxml2inv FDSNstation-embargoFree.xml > inventory-embargoFree.xml

5. Update SEISCOMP:

   scinv sync [--test]
   seiscomp update-config
   seiscomp restart

6. Test query for open data: https://EIDA-node/fdsnws/dataselect/1/query?start=2022-12-22T00:00:00&end=2022-12-22T00:10:00&net=XX&sta=YYY&cha=*Z