SelectionEarthquake

Deprem kayitlarini AFAD, PEER NGA-West2, ESM ve FDSN servislerinden cekip ortak kolon semasina normalize eden; arama kriterlerine gore puanlayan ve TBDY 2018'e uygun, bolge ozelliklerine (buyukluk, uzaklik, mekanizma, zemin) benzeyen deprem kayitlarini seçen Python kutuphanesi.

Kapsam. Bu kutuphane aday kayit arama ve secimi yapar. Ivme spektrumu hesabi, olceklendirme ve spektral eslestirme kapsam disindadir; secilen kayitlari bu isleri yapan bir arac (ornegin kendi sinyal isleme uygulamaniz) devralir.

Icindekiler

• Hizli baslangic
• Kurulum
• Veri saglayicilar
• Nasil calisir?
• Arama kriterleri
• Secim stratejileri ve scoring
• TBDY 2018 uyumu
• Veri kalitesi: eksik veri ve tekrar tespiti
• Ciktilar ve rapor
• Waveform indirme ve FDSN
• Komut satiri
• Python API ozeti
• Mimari
• Gelistirme
• 1.x'ten 2.0'a gecis
• Dokumantasyon
• Yol haritasi

Hizli baslangic

Asagidaki ornek ag baglantisi gerektirmez (paketle gelen NGA-West2 verisini kullanir). Marmara/Kuzey Anadolu benzeri bir senaryo icin 22 kayit (TBDY: her yon 11 kayit) arar:

from selection_service import EarthquakeAPI, DesignCode, ProviderName
from selection_service.processing.criteria import ScoringWeights, SearchCriteria, SelectionConfig
from selection_service.processing.strategies import TBDY2018ConstraintStrategy

strategy = TBDY2018ConstraintStrategy(
    SelectionConfig(
        design_code=DesignCode.TBDY_2018,
        num_records=22,       # 11 x 2 yon
        max_per_event=3,      # ayni depremden en fazla 3 kayit
        max_per_station=3,
        min_score=0,
    )
)

criteria = SearchCriteria(
    start_date="1990-01-01",
    end_date="2025-01-01",
    min_magnitude=6.5, max_magnitude=7.8,
    min_Rjb=0, max_Rjb=60,
    min_vs30=200, max_vs30=500,
    mechanisms=["StrikeSlip"],
    bbox=(34, 43, 25, 45),   # (min_lat, max_lat, min_lon, max_lon)
    weights=ScoringWeights.from_preset("tbdy_2018_record_selection"),
)

api = EarthquakeAPI(provider_names=[ProviderName.PEER], strategies=[strategy], use_cache=False)
result = api.run_sync(criteria=criteria, strategy_name=strategy.get_name())

if result.success:
    run = result.value
    print(run.selected_df[["PROVIDER", "RSN", "EVENT", "YEAR", "MAGNITUDE",
                           "RJB(km)", "VS30(m/s)", "SCORE"]].head())
    print(run.report["compliance"])      # 22 kayit / olay basina 3 kurali kontrolu
else:
    print(result.error)

Ornek cikti (paketle gelen PEER verisiyle gercek bir calistirma; secili kolonlar):

  PROVIDER   RSN            EVENT  YEAR  MAGNITUDE  RJB(km)  VS30(m/s)      SCORE
     PEER  1162  Kocaeli, Turkey  1999       7.51    31.74     347.62  92.724459
     PEER  1615    Duzce, Turkey  1999       7.14     9.14     338.00  91.005081
     PEER  1620    Duzce, Turkey  1999       7.14    45.16     411.91  89.551056
     PEER  1602    Duzce, Turkey  1999       7.14    12.02     293.57  88.978679
     PEER  1177  Kocaeli, Turkey  1999       7.51    51.98     341.56  85.627623

Bu dar kriterlerle yalnizca 7 kayit bulunur; compliance bunu acikca soyler (bkz. TBDY 2018 uyumu).

Kurulum

pip install earthquake-selection

Paket adi earthquake-selection, import adi selection_service'dir.

Python 3.10 - 3.13 desteklenir. Yerel gelistirme:

git clone https://github.com/muhammedsural/SelectionEarthquake.git
cd SelectionEarthquake
pip install -e ".[dev]"

Veri saglayicilar

Birden fazla provider ayni anda kullanilabilir; sonuclar ortak kolon semasinda birlesir. Yeni provider eklemek icin Provider Gelistirme sayfasina bakin.

Nasil calisir?

flowchart LR
    A[SearchCriteria] --> B[Provider'lar<br/>AFAD / PEER / FDSN]
    B --> C[Mapper<br/>STANDARD_COLUMNS]
    C --> D[Birlestirme<br/>+ tekrar tespiti]
    D --> E[Strateji<br/>sert filtre / puanlama / secim]
    E --> F[PipelineResult<br/>selected_df, scored_df, report]

1. Girdi: SearchCriteria provider'a ozel parametrelere donusur (to_afad_params(), to_peer_params(), to_fdsn_params()).
2. Cekme: Provider'lar sync veya async calisir; basarisiz olan provider failed_providers listesine eklenir, digerleri devam eder. use_cache=True ile sonuclar .cache/ altinda 24 saat onbelleklenir.
3. Normalizasyon: Mapper'lar ham kolonlari 33 kolonluk STANDARD_COLUMNS semasina cevirir.
4. Birlestirme: Provider'lar arasi ayni deprem/kayit tekrarlari tespit edilir (EVENT_GROUP).
5. Secim: Strateji kayitlari filtreler, puanlar ve kisitlara (kayit sayisi, olay/istasyon limiti) gore secer; her kayit icin SELECTION_REASON yazilir.
6. Rapor: PipelineResult secilen/tum kayitlari ve izlenebilir bir rapor icerir.

Arama kriterleri

SearchCriteria tum provider'lar icin ortak modeldir (tum alanlar Pydantic ile dogrulanir).

Hedef sirasi: target_* verildiyse o deger; verilmediyse ve hem min hem max varsa (min + max) / 2; aksi halde kriter puanlamaya katilmaz.

Tek tarafli sinir yalnizca filtredir (2.1.0). Yalnizca min_magnitude=5.0 vermek "M >= 5.0 olan kayitlar" demektir, "M5'e yakin kayitlar" degil. Bu durumda hedef olusmaz; hicbir kriter icin hedef yoksa adaylar varsayilan duzende siralanir: once buyuk MAGNITUDE, sonra kucuk mesafe (Rjb, yoksa Rrup, yoksa Repi) ve min_score esigi uygulanmaz. Belirli bir buyukluge yakin kayit istiyorsaniz target_magnitude=... ya da iki tarafli aralik (min_magnitude + max_magnitude) verin. Ayrintilar: Arama Kriterleri.

Secim stratejileri ve scoring

Iki strateji de ayni depremden/istasyondan secilebilecek kayit sayisini (max_per_event, max_per_station) uygular. Hangisini secmeli?

• Kriterleriniz kesin sinirlar ise (ornegin Vs30 200-500 m/s disina cikilamaz): TBDY2018ConstraintStrategy.
• Hedefe yakinlik onemliyse ve sinirlar esnekse: TBDYSelectionStrategy.

Hazir agirlik setleri ScoringWeights.from_preset(...) ile secilir:

from selection_service.processing.criteria import ScoringWeights
print(ScoringWeights.preset_descriptions())

Mevcut sonuc uzerinde kriterleri degistirip yeniden secmek icin api.re_selection(df, strategy_name, new_criteria) kullanilir (provider'lara yeniden gitmez).

TBDY 2018 uyumu

TBDY 2018 zaman tanim alaninda hesap icin deprem kaydi secimini sunlara baglar; kutuphanedeki karsiliklari:

Secim sonunda rapor, sartlarin saglanip saglanmadigini bildirir:

print(result.value.report["compliance"])

{
  "selected_count": 7,
  "required_count": 22,
  "shortfall": 15,
  "max_per_event_limit": 3,
  "max_selected_per_event": 3,
  "max_per_event_ok": true,
  "compliant": false,
  "warnings": ["Yetersiz kayıt: 7/22 seçilebildi. Arama kriterlerini (büyüklük, uzaklık, Vs30, mekanizma) genişletin."]
}

Ayni uyarilar result.value.logs icinde [WARN] olarak da yer alir. Yeterli kayit bulunamazsa kriterleri genisletin veya baska bir provider ekleyin.

Ortalama spektrumun tasarim spektrumuna uygunlugu (olcekleme, periyot araligi) bu kutuphanenin degil, secilen kayitlari isleyen aracin sorumlulugundadir.

Veri kalitesi: eksik veri ve tekrar tespiti

Eksik veri

• Ciktilar: selected_df, scored_df ve combined_df icindeki sayisal bosluklar 0 ile doludur (asagi akis hesaplari NaN ile hata verdigi icin).
• Secim sirasinda: Algoritma bosluklari gorur. VS30(m/s) ve MAGNITUDE icin 0 "bilinmiyor" sayilir; Vs30 araligi verildiyse Vs30'u bilinmeyen kayit missing:VS30(m/s) nedeniyle elenir (bilinmeyen istasyon "Vs30 = 0 m/s" gibi puanlanmaz).

Provider'lar arasi tekrar tespiti

Ayni deprem AFAD ve PEER'da farkli adlarla gelebilir. Birden fazla provider kullaniliyorsa pipeline:

• Olaylari eslestirir: ayni yil, buyukluk farki <= 0.5, episantr mesafesi <= 50 km ve birbirinin en yakin adayi olan farkli-provider olaylari tek EVENT_GROUP olur (ayni provider'daki artci soklar birlestirilmez).
• Tekrar kaydi eler: ayni grupta, istasyon konumu <= 1 km olan ikinci kopya aday havuzundan cikarilir.

Davranis SelectionConfig.dedup ile ayarlanir:

from selection_service import DesignCode, ProviderName
from selection_service.processing.criteria import DedupConfig, SelectionConfig

config = SelectionConfig(
    design_code=DesignCode.TBDY_2018,
    dedup=DedupConfig(
        prefer_provider=ProviderName.AFAD,  # tekrar kayitlarda AFAD korunur
        max_event_distance_km=50,
        max_mag_diff=0.5,
        max_station_distance_km=1.0,
        # enabled=False -> birlestirme ve eleme kapali
    ),
)

Sonuc report["deduplication"] icinde (merged_event_groups, duplicate_records_removed) raporlanir. Eslestirme sezgiseldir; ortak bir olay kimligi yoktur.

Ciktilar ve rapor

api.run_sync(...) basariliysa result.value bir PipelineResult'tir:

report anahtarlari: selected_count, total_considered, strategy, providers, records, statistics, selection_summary (secilen/reddedilen sayilari ve eleme gerekceleri), score_breakdown, error_metrics, compliance, deduplication.

scored_df izlenebilirlik kolonlari: SCORE, SCORE_BREAKDOWN, SELECTION_STATUS (selected / rejected), SELECTION_REASON (selected, score_below_min_score:55.0, max_per_event:3, max_per_station:3, num_records_limit:22, vs30_below_min:200.0 ...), EVENT_GROUP; constraint stratejisinde ayrica HARD_FILTERS, ERROR_METRICS, ERROR_TOTAL.

Disa aktarma:

run.selected_df.to_csv("selected_records.csv", index=False)

import json
with open("selection_report.json", "w", encoding="utf-8") as f:
    json.dump(run.report, f, indent=2, ensure_ascii=False, default=str)

Waveform indirme ve FDSN

AFAD (secilen kayitlari indirme): download desteklemeyen provider'lar (PEER gibi) atlanir.

download = api.download_waveforms(
    run.selected_df,
    export_type="mseed",   # "mseed" | "asc2" | "asd"
    batch_size=10,
)
if not download.success:
    print(download.error)

Tek dosyalik ve sorunlu kayit iceren partiler dogru islenir (tek sorunlu kayit tum partiyi dusurmez). Ayrintilar: Waveform Indirme.

FDSN istasyon ve waveform servisleri:

api = EarthquakeAPI(provider_names=[ProviderName.FDSN], strategies=[strategy])

stations = api.search_fdsn_stations(
    network="TU", station="*", channel="HN?",
    starttime="2023-02-06", endtime="2023-02-07",
)
traces = api.search_fdsn_waveforms(
    network="TU", station="ANK", location="*", channel="HN?",
    starttime="2023-02-06T01:16:00Z", endtime="2023-02-06T01:17:00Z",
)

Istasyon sonucu kanal basina bir DataFrame satiri, waveform sonucu selection_service.waveform.Trace listesidir. Metotlarin _async surumleri de vardir. Kayit aramasi ve indirme: FDSN Saglayicisi.

Komut satiri

Kurulumdan sonra quake-sel komutu uctan uca arama, secim ve rapor uretir:

quake-sel --providers peer --num-records 22 \
          --report-path selection_report.json --selected-csv selected_records.csv

# AFAD: arama + secilen kayitlarin waveform'larini indirme (ag gerekir)
quake-sel --providers afad --download-waveforms --export-type mseed

Ayrintilar: CLI.

Python API ozeti

Sonuclar Result tipiyle doner (result.success, result.value, result.error); hatalar istisna firlatmak yerine tasinir.

Mimari

selection_service/
  core/         EarthquakeAPI (facade), pipeline, config, hata tipleri, logging
  services/     Sorgu servisi, provider kayit defteri, waveform indirme servisi
  providers/    AFAD, PEER, FDSN, cache, provider sozlesmeleri (interfaces.py)
  processing/   criteria (SearchCriteria, SelectionConfig, DedupConfig),
                strategies/ (base, tbdy, eurocode), mappers, dedup, Result
  enums/        ProviderName, DesignCode
  utility/      Veri dosyasi yukleme yardimcilari
  data/         Paketle gelen NGA-West2 flatfile ve istasyon verisi
tests/          pytest paketi
examples/       Kullanim ornekleri ve notebook'lar
docs/           MkDocs dokumantasyonu

Gelistirme

pip install -e ".[dev]"

python -m pytest                                              # testler
python -m pytest --cov=src/selection_service --cov-fail-under=80   # coverage (CI esigi)
flake8 src --select=E9,F63,F7,F82                             # CI lint
pip install -r requirements-docs.txt && mkdocs build --strict # dokumantasyon

CI (GitHub Actions) Python 3.10 - 3.13 uzerinde testleri, lint'i ve coverage esigini calistirir. Katki icin: branch acin, davranis degisikligine test ekleyin, dokuman orneklerinin gercek API ile calistigini dogrulayin (Test ve Kalite).

2.3.0: ObsPy'siz FDSN ve FDSN kayit indirme

FDSN provider'i olay, istasyon ve dataselect servislerini dogrudan HTTP ile kullanir; ObsPy bagimliligi kalkti ([fdsn] extra'si bos, eski komutlar calismaya devam eder). record_search=True ile her deprem icin cevredeki ivme olcer istasyonlari aranir, kayit basina satir doner ve kayitlar indirilebilir: mseed ham, asc2 kanal duyarliligiyla cm/s^2'ye cevrilmis ESM benzeri ASCII. Yeni selection_service.waveform modulu miniSEED 2 (Steim1/2, tamsayi, kayan nokta) okur ve ASCII yazar.

Uyumluluk notlari: FDSNProvider artik ObsPy client/station_client/ waveform_client yerine session (requests) alir; search_fdsn_waveforms ObsPy Stream yerine Trace listesi dondurur; olay satirlarinda EVENT katalogun kisa kimligidir (ornegin us6000jllz). FDSN satirlari (FDSN_USGS gibi etiketler) indirme servisinde FDSN provider'ina yonlendirilir. Ayrintilar: FDSN Saglayicisi.

ESM arama ve indirme duzeltmesi (2.3.0)

2.2.0'da ESM flatfile sorgusu servisin tanimadigi u_ia/v_ia alanlarini istedigi icin her arama HTTP 400 ("try_funct has failed") ile dusuyordu; rotD50_* ve u_T90 adlari da buyuk harf yuzunden eslesmiyordu. Alanlar artik ESM'deki kucuk harfli adlarla istenir ve Arias siddeti rotd50_ai alanindan okunur. Indirmede bos konum kodu location=-- olarak gidip yine HTTP 400 aliyordu; konum bossa parametre gonderilmez.

2.2.0: ESM saglayicisi

ProviderName.ESM Engineering Strong-Motion veritabanini (esm-db.eu, ORFEUS/INGV) ekler. Arama esmws/flatfile/1 servisinden kayit basina bir satir alir: tarih, buyukluk, derinlik, deprem kutusu, Vs30, Rjb, ag/istasyon ve faylanma turu sunucuda; Rrup, Repi, Rhyp, PGA/PGV/PGD, daire ve secilen buyukluk turu (oncelik Mw) istemcide uygulanir. Indirme esmws/eventdata/1 ile yapilir: FILE_NAME_H1 AG.ISTASYON.KONUM.KANAL bicimindedir, uc bilesen birlikte iner; AFAD tarzi file_status (RawAcc -> CV, Acc/Vel/Disp -> elle islenmis MP) ve export_type (asc2 -> ascii, mseed) karsiliklari desteklenir. Yalniz herkese acik veri desteklenir (kisitli veri token ister). Ayrintilar: ESM Saglayicisi.

api = EarthquakeAPI(provider_names=[ProviderName.ESM, ProviderName.AFAD], strategies=[strategy])

2.1.1 duzeltmesi: AFAD mesafe filtreleri

AFAD GetWaveforms servisi fromRrup/toRrup verildiginde (ornegin 0-30 km) her zaman bos liste donduruyor; bu yuzden Rrup araligi verilen her AFAD aramasi bos geliyordu. 2.1.1 ile mesafe sinirlari (Repi, Rhyp, Rjb, Rrup) AFAD'a gonderilmez, yanit geldikten sonra istemci tarafinda uygulanir (sinirlar dahil; sinir verilmis mesafesi bos olan kayit elenir). Vs30 filtresi AFAD'da dogru calistigi icin sunucuda kalir.

2.1.0 davranis degisikligi

2.0.x'te tek tarafli sinir (yalnizca min_X veya yalnizca max_X) hedef gibi kullaniliyordu; ornegin yalnizca min_magnitude=5.0 ile secim M5 civarina yigiliyor, buyuk depremler num_records_limit ile eleniyordu. 2.1.0 ile tek tarafli sinir yalnizca filtredir; hedef target_X ya da iki tarafli araligin ortasidir. Hedef yoksa siralama: buyuk MAGNITUDE once, sonra kucuk mesafe. Esit skor/hata durumunda da ayni duzen kullanilir. Eski davranisi istiyorsaniz target_magnitude=5.0 gibi acik hedef verin.

1.x'ten 2.0'a gecis

2.0.0 kirici degisiklikler icerir. from selection_service import ... ile yapilan ust duzey import'lar degismedi; modul yollari degisti:

Tum modul adlari snake_case oldu. Tam liste ve davranis duzeltmeleri: 2.0 Gecis Rehberi.

Dokumantasyon

Tum dokumantasyon: https://muhammedsural.github.io/SelectionEarthquake

Yol haritasi

• FDSN waveform sonuclarini dosyaya aktarma ve secim akisiyla iliskilendirme.
• Eurocode 8 stratejisini gercek kurallarla doldurma (EurocodeSelectionStrategy su an yer tutucudur; DesignCode yalnizca TBDY_2018 icerir).
• Rapor ciktilarini HTML/PDF formatina genisletme.
• Dedup eslestirmesini tam olay tarihini kullanacak sekilde iyilestirme.

Lisans

MIT License