Development#

This software package is for the processing, data management, and visualization of micro-seismic data.

It is an evolution of the code found here: https://gitlab.seismo.ethz.ch/doetschj/DUG-Seis

The acquisition companion code can be found here: swiss-seismological-service/DUGseis-acquisition

Directory Structure#

As of August 2024 the directory structure is approximately as follows:

.
├── README.md
├── docs
│   └── ...
├── dug_seis
│   ├── __init__.py
│   ├── cmd_line.py
│   ├── coordinate_transforms.py
│   ├── db
│   ├── event_processing
│   ├── graphical_interface
│   ├── plotting
│   ├── project
│   ├── tests
│   ├── util.py
│   └── waveform_handler
├── scripts
│   └── ...
├── paper
│   └── ...
├── ...
└── pyproject.toml

README.md: Root level readme file.
docs: Sphinx based documentation.
dug_seis: Source code for the actual DUGSeis package.
dug_seis/cmd_line.py: Code for the command line interface.
dug_seis/coordinate_transforms.py: Coordinate transformations.
dug_seis/db: Submodule implementing the SeisComP compatible database interface.
dug_seis/event_processing: Submodule containing all detectors, pickers, location algorithms, magnitude estimation, …
dug_seis/graphical_interface: Submodule for the graphical Qt interface.
dug_seis/plotting: Submodule with plotting functions.
dug_seis/project: Submodule implementing the DUGSeisProject class.
dug_seis/pytest.ini: Configuration file for the unit tests.
dug_seis/tests: Unit tests for the DUGSeis package.
dug_seis/util.py: Utility functions useful across DUGSeis.
dug_seis/waveform_handler: Low-level implementation of the waveform data access.
scripts: A collection of useful scripts and examples.
paper: Paper files with figures and references.
pyproject.toml: Configuration file to install DUGSeis.

Testing#

Unit tests are written in the pytest framework.

To execute them make sure pytest is installed (pip install pytest) an run

py.test

in the DUGSeis code directory. The tests are not comprehensive but they do test a decent chunk of the complicated part of it and thus should always work.

Linting#

To adhere to the style guide and avoid silly errors always make sure black and flake8 pass (pip install DUG-Seis[linting]).

Just run the following in the DUGSeis source code directory:

black .
flake8 .

Both tools are configured in the pyproject.toml and the .flake8 files in the root source directory, respectively.

Documentation Building#

The documentation resides in the docs directory. It depends on the following packages:

sphinx
sphinx-book-theme
myst-parser

Once these are installed (pip install DUG-Seis[docsbuild]), just change to the docs directory and execute

make html

or (on Windows)

./make.bat html

and the HTML documentation will be saved to docs/_build/html.

Graphical Interface#

The .ui files in dug_seis/graphical_interface/ui_files can be graphically edited with the Qt Creator.

Once the UI files have been edited they can be converted to Python files like this:

For windows:

pyside6-uic .\main_window.ui -o main_window.py

For Linux/Mac:

pyside6-uic ./main_window.ui -o main_window.py

It works the same for the other UI files.

Misc#

Possible database migration path#

The SQLite database ORM is well tested in the sense that it can reliably round-trip data to and from QuakeML. It has seen little external validation for full compatibility with other tools able to work with SeisComP compatible databases.

If changes to the database implementation are necessary it should be possible to first export everything to QuakeML files and reimport these into the new database.

Dump whole archive to QuakeML by using the current DUGSeis version:

project.db.dump_as_quakeml_files(folder="/path/to/archive")

Then update the DUGSeis version and do:

for filename in pathlib.Path("/path/to/archive").glob(".xml"):
    for event in obspy.read_events(str(filename)):
        project.db.add_object(event)

Development

Contents