OGS Seismology Toolkit: An End-to-End Python Solution for Seismic Catalog Analysis in Northeastern Italy

Abstract: A comprehensive Python toolset for seismic catalog parsing, clustering, comparison, and visualization, supporting multiple data formats and 13 clustering algorithms, suitable for seismological research.

This toolkit is an end-to-end Python solution for seismic catalog analysis in Northeastern Italy, covering the entire workflow from data acquisition, parsing, management, clustering to comparison, providing systematic support for seismological research. The following floors will introduce its background, functions, technical highlights, application scenarios, and future directions.

In seismological research, standardized data processing and cross-source comparison have always been core challenges. Seismic catalogs from different institutions with different formats are often difficult to integrate directly, and manual processing is not only inefficient but also prone to human errors. The Italian National Institute of Oceanography and Applied Geophysics (OGS) has long monitored seismic activities in Northeastern Italy and surrounding areas, accumulating a large amount of multi-format historical data, and urgently needs a systematic tool to achieve standardized data management and in-depth analysis.

This open-source toolkit came into being; it is not just a data converter but a complete seismological research workflow platform. From the download of raw waveform data, to the parsing and integration of multi-format catalogs, to machine learning-based seismic event clustering analysis, the entire process is encapsulated in a unified Python framework. For researchers engaged in seismology, geophysics, and spatiotemporal data analysis, this provides a directly reusable technical foundation.

The toolkit adopts a modular design, with clear data flow interfaces connecting components. Core modules include:

Data Acquisition Layer: ogsdownloader.py is implemented based on ObsPy's MassDownloader, supporting batch download of waveform data from multiple FDSN data centers such as INGV, GFZ, IRIS, ETH, ORFEUS. It supports rectangular or circular geographic area selection, automatic directory storage by date, and EIDA token authentication for restricted data access.

Format Parsing Layer: For the four proprietary formats (.dat, .hpl, .pun, .txt) historically used by OGS, dedicated parsers are implemented respectively, exposing a consistent interface through the unified OGSDataFile abstract base class. The parsed data is converted into the standard Pandas DataFrame format for subsequent analysis.

Catalog Management Core: ogscatalog.py is the heart of the entire toolkit, providing advanced functions such as lazy loading, geofence filtering, and Parquet partition storage. It supports efficient filtering by date range and geographic polygon, with built-in visualization methods including event distribution maps, cumulative curves, magnitude histograms, etc.

Clustering Analysis Engine: ogsclustering.py implements 13 clustering algorithms, including K-Means, MiniBatchKMeans, BisectingKMeans, DBSCAN, HDBSCAN, OPTICS, Advanced Density Peaks, Hierarchical Clustering, Feature Hierarchical Clustering, Affinity Propagation, Mean Shift, Spectral Clustering, and Birch. Each algorithm is equipped with a hyperparameter optimization mechanism and performance comparison through a unified evaluation index interface (Silhouette Coefficient, Calinski-Harabasz Index, Davies-Bouldin Index, etc.).

Catalog Comparison System: ogscompare.py implements a catalog comparison framework based on the Bipartite Graph Matching Algorithm (BGMA), supporting event and phase matching between two catalogs within time and space tolerance ranges, generating confusion matrices and true positive/false negative/false positive statistics.

Intelligent Matching Algorithm: BGMA (Bipartite Graph Matching Algorithm) is one of the innovations of the toolkit. Traditional seismic catalog comparison often uses simple spatiotemporal proximity search, while BGMA models the problem as a maximum weight matching problem of a weighted bipartite graph and solves it using NetworkX. Phase matching uses a composite distance function of 97% time + 2% phase type + 1% probability, and event matching uses a weighted strategy of 99% time +1% space, achieving a good balance between computational efficiency and matching accuracy.

Partition Storage Strategy: Large-scale seismic catalog data is stored in Parquet format partitioned by date (events/YYYY-MM-DD, assignments/YYYY-MM-DD), which not only ensures query efficiency but also facilitates integration with big data tools like Spark.

Geofence Calculation: Polygon inclusion detection is implemented using matplotlib.path.Path, supporting the definition of arbitrarily complex research areas. The toolkit predefines the research area of Northeastern Italy and neighboring countries (approximately 9.5-15.0°E, 44.3-47.5°N), and has built-in fast filtering functions by geographic region codes (A, C, E, F, G, L, O, R, S, T, V represent different regions respectively).

For seismological researchers, this toolkit can significantly reduce the time cost of data preprocessing. What used to take weeks of manual sorting can now be automated via scripts. More importantly, standardized data formats and unified analysis interfaces make it feasible for results reproduction and comparison between different research teams.

For machine learning practitioners, the toolkit provides a high-quality spatiotemporal dataset and a complete clustering experiment framework. The parallel comparison mechanism of 13 algorithms can serve as a teaching case for algorithm selection strategies. The spatiotemporal clustering problem of seismic events itself is also uniquely challenging—seismic activities have obvious spatial aggregation characteristics and time-dependent self-excitation characteristics, and traditional clustering assumptions are often not fully applicable, which provides a real test scenario for algorithm research.

The architecture design of the toolkit fully considers extension requirements. Supporting new data formats only requires inheriting OGSDataFile and implementing parsing logic to integrate into the existing workflow; new clustering algorithms can be seamlessly integrated into the comparison framework by inheriting BaseClusterer. The OGSClusteringZoo factory pattern enables flexible configuration of algorithm instantiation and hyperparameter search.

Possible future enhancement directions include: introducing deep learning models for automatic seismic event classification, integrating real-time data stream processing capabilities, developing web visualization interfaces, etc. The current version already provides a solid technical foundation, sufficient to support various scenarios from academic research to business applications.

The OGS Seismology Toolkit demonstrates how to use modern software engineering methods to solve practical problems in the traditional earth science field. It is not a simple collection of scripts but a carefully designed, maintainable, and extensible research platform. For any researcher who needs to process spatiotemporal clustering data, regardless of their specific field (seismology, epidemiology, or traffic flow analysis), the design ideas and implementation techniques of this toolkit are of reference value.