Metadata-Version: 2.1
Name: gomd
Version: 2.0.0
Summary: Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK for GOMD (Piri Reis University / COP31 Turkiye)
Home-page: https://gomd.pirireis.edu.tr
Author: Piri Reis University - Maritime Sustainability Research Centre
Author-email: gomd@pirireis.edu.tr
License: MIT
Project-URL: Homepage, https://gomd.pirireis.edu.tr
Project-URL: Documentation, https://gomd.pirireis.edu.tr/sdk_paper.php
Project-URL: Repository, https://gomd.pirireis.edu.tr/sdk/dist/simple/
Keywords: oceanography,maritime,decarbonization,imo-cii,eu-ets,marine-heatwaves,carbonate-chemistry,econometrics,cop31,sdg14,gomd
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: Oceanography
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Provides-Extra: pandas
Requires-Dist: pandas>=1.5.0 ; extra == 'pandas'
Provides-Extra: geo
Requires-Dist: pandas>=1.5.0 ; extra == 'geo'
Requires-Dist: geopandas>=0.12.0 ; extra == 'geo'

# `gomd` — Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK (v2.0.0)

[![Version](https://img.shields.io/badge/version-2.0.0-0ea5e9.svg)](https://gomd.pirireis.edu.tr/sdk_paper.php)
[![Python](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](https://opensource.org/licenses/MIT)
[![Reference Paper](https://img.shields.io/badge/Reference_Paper-GOMD_2026-indigo.svg)](https://gomd.pirireis.edu.tr/sdk_paper.php)

**`gomd` (v2.0.0)** is the official scientific computing, oceanographic modeling, maritime regulatory compliance, and climate econometric Python software development kit for the **Global Ocean & Maritime Data Platform (GOMD — Piri Reis University / COP31 Türkiye)**.

Unlike simple REST wrappers, `gomd` v2.0.0 includes **6 specialized scientific submodules and 44 peer-reviewed & post-2020 algorithms** with zero C/Fortran compilation requirements:

1. **`gomd.client`** — Authenticated REST & Bulk Client, Multi-Indicator Econometric Panel Builder (`build_panel`), Global Historical Blue & Marine Insurance Finance Atlas (`get_blue_finance_atlas`), Local SHA-256 Disk Cache (`~/.gomd_cache`), and Cryptographic Provenance Verification (`verify_provenance`).
2. **`gomd.ocean`** — Physical, Biogeochemical, Blue Carbon, CWON Natural Capital & Parametric Sustainability Insurance:
   - `seawater_density_eos80()` — UNESCO 1983 (EOS-80) equation of state ($\rho(S,T,p)$ & potential density anomaly $\sigma_0$).
   - `teos10_gsw_stratification()` — TEOS-10 Gibbs Seawater Absolute Salinity ($S_A$), Conservative Temperature ($\Theta$), and Sallée et al. (*Nature*, 2021) pycnocline stratification barrier ($N^2$).
   - `oxygen_solubility()` — Garcia & Gordon (1992) Dissolved Oxygen saturation ($\text{DO}_{\text{sat}}$), Apparent Oxygen Utilization ($\text{AOU}$), and Diaz & Rosenberg (2008) hypoxia staging.
   - `carbonate_system()` — Marine carbonate equilibrium solver (Dickson & Millero 1987; Lueker et al. 2000; Mucci 1983) for $p\text{CO}_2$, $\text{DIC}$, $[\text{HCO}_3^-]$, $[\text{CO}_3^{2-}]$, Aragonite saturation ($\Omega_{\text{arag}}$), and Calcite saturation ($\Omega_{\text{calc}}$).
   - `marine_heatwave_detect()` & `compound_mhw_oax_event()` — Hobday et al. (2016) MHW detector and Gruber et al. (*Science*, 2021) / Burger et al. (*Nature*, 2022) Triple Compound MHW+OAX+LOX & Clarke (2021) Aerobic Growth Index (AGI).
   - `trophic_state_index()` & `mucilage_risk_index()` — Carlson (1977) TSI, Vollenweider (1998) TRIX, and composite 0–100 marine mucilage hazard index.
   - `blue_carbon_sequestration_valuation()` — Bertram et al. (*Nature Climate Change*, 2021) & Rennert et al. (*Nature*, 2022, $\$185/\text{tCO}_2$) coastal blue carbon NPV & Paris Agreement Article 6 VCM valuation.
   - `sustainable_insurance_cat_var()` — **UNEP FI Principles for Sustainable Insurance (PSI, 2023)**, **Reguero et al. (*Nature Comms*, 2020)** & **Beck et al. (*Nature Sustainability*, 2022)** parametric coral reef, mangrove & seagrass wave-attenuation catastrophe risk-transfer and resilience Benefit-Cost Ratio (BCR) model.
   - `cwon_wealth_accounting()` — **World Bank Changing Wealth of Nations (CWON 2021/2024)** & **Dasgupta Review (2021)** Adjusted Net Savings (ANS / Genuine Savings) and Blue-Inclusive Natural Capital Depletion Accounting.
3. **`gomd.maritime`** — Maritime Decarbonization, Marine Hull/P&I Underwriting (IUMI / PPMI), Green Finance & Port State Control:
   - `calculate_imo_cii()` — IMO MEPC.336(76)–MEPC.354(78) Attained AER, Required CII reference line, annual reduction factor $Z\%$, and A–E rating boundaries.
   - `calculate_eu_ets_exposure()` & `calculate_fueleu_maritime()` — Directive (EU) 2023/959 Maritime EU ETS and Regulation (EU) 2023/1805 FuelEU Maritime Well-to-Wake (WtW) GHG intensity & RFNBO $2\times$ multiplier.
   - `imo_2023_strive_trajectory()` & `ais_speed_power_emissions()` — IMO MEPC.377(80) (2023 Revised GHG Strategy) Stranded-Asset Year & AIS Admiralty-Cube propulsion elasticity.
   - `poseidon_principles_alignment()` & `psc_detention_risk_score()` — Poseidon Principles ship finance alignment ($\Delta_{\text{PP}}\%$) and Paris/Med MoU PSC detention risk profile.
   - `marine_insurance_actuarial_pricing()` — **IUMI Global Marine Insurance Report (2025)**, **International Group of P&I Clubs (IG P&I)** mutual pool call, Cargo CIF-FOB, War-Risk chokepoint surcharge, **Poseidon Principles for Marine Insurance (PPMI, 2024)** climate alignment delta ($\Delta_{\text{PPMI}}\%$), and Solvency II 99.5% Marine Underwriting VaR.
4. **`gomd.stats`** — Non-Parametric Environmental, Causal & Panel Econometrics:
   - `mann_kendall_sen()`, `pettitt_changepoint()`, `extreme_return_levels()`, `cointegration_eg_test()`, `panel_fixed_effects()`, `synthetic_did_ate()` (Arkhangelsky et al., *AER* 2021), `innovative_polygon_trend()` (Şen, 2020/2021), and `transfer_entropy_causal()` (Runge et al., *Nature Comms* 2019 / *Nat. Rev.* 2023).
5. **`gomd.spatial`** — Geodesic & Chokepoint Spatial Analytics (`haversine_distance`, `classify_sea_basin`, `chokepoint_proximity`, `to_geojson`).
6. **`gomd.cli`** — Command-Line Interface (`python -m gomd cite | cii | carbonate | basin`).

---

## Installation

Install directly from the GOMD PEP 503 Simple Repository Index:

```bash
pip install gomd --extra-index-url https://gomd.pirireis.edu.tr/sdk/dist/simple/
# Or direct wheel installation (Google Colab zero-cache recommended):
!pip install -q --force-reinstall --no-cache-dir https://gomd.pirireis.edu.tr/sdk/dist/gomd-2.0.0-py3-none-any.whl
```

### Official Documentation & 10 Downloadable Real-Data Google Colab Case Studies (`.ipynb` & `.py`)
- **Interactive Python SDK Documentation & Case Studies Hub:** `https://gomd.pirireis.edu.tr/python_sdk_docs.php`
  1. **Case Study 01 (`cs01_multivariate_ocean_climate_data_mining.ipynb`):** Eastern Mediterranean Multivariate Ocean-Climate Regime Mining (8 Live GOMD Series, Spectral PCA, K-Means++, Walk-Forward Ridge CV & Shannon Transfer Entropy)
  2. **Case Study 02 (`cs02_maritime_decarbonization_cii_ets_fueleu.ipynb`):** Commercial Fleet Decarbonization Mining (Live GOMD IMO CII, EEXI, Directive 2023/959 Maritime EU ETS, FuelEU Maritime WtW & 8-Country Transport $\text{CO}_2$ Panel)
  3. **Case Study 03 (`cs03_blue_finance_actuarial_insurance_cwon.ipynb`):** Global Blue Finance, Marine Hull/P&I Underwriting (IUMI/PPMI), Parametric Reef/Mangrove Insurance (UNEP FI PSI) & World Bank CWON Natural Capital Accounting (14 Live Series)
  4. **Case Study 04 (`cs04_marmara_mucilage_eutrophication_acidification.ipynb`):** Sea of Marmara Mucilage Hazard Index, Sub-Halocline Hypoxia, Vollenweider TRIX & Carlson TSI Coastal Eutrophication & TEOS-10 Stratification (7 Live Series)
  5. **Case Study 05 (`cs05_mavi_vatan_icj_delimitation_causal_sdid.ipynb`):** Mavi Vatan (UN A/74/757) ICJ Equitable Delimitation Audit, Global Maritime Chokepoint Geodesics & Real-Panel Synthetic Difference-in-Differences (SDID) Policy Evaluation
  6. **Case Study 06 (`cs06_blacksea_med_fisheries_biodiversity_medits.ipynb`):** Black Sea & Mediterranean Fisheries, Aquaculture Transition (1970–2024) & 5-Basin MEDITS Benthic Trawl Impact Panel (`panel_fixed_effects`, `transfer_entropy_causal`)
  7. **Case Study 07 (`cs07_global_carbon_budget_mauna_loa_ocean_sink_cointegration.ipynb`):** Global Carbon Budget (1959–2025), Mauna Loa $\text{CO}_2$, Ocean Sink Cointegration (`cointegration_eg_test`), Ocean Heat Content & Arctic Sea Ice Attribution
  8. **Case Study 08 (`cs08_high_frequency_metocean_wave_extremes_chokepoints.ipynb`):** High-Frequency Met-Ocean Wave Extremes (`extreme_return_levels`), Swell Energy & Thermal Shock Across 10 Sea Basins & Maritime Chokepoints ($N=5,580$ Live Observations)
  9. **Case Study 09 (`cs09_energy_transition_sectoral_ghg_green_shipping_corridors.ipynb`):** COP31 Energy Transition, Renewable Share & Sectoral GHG Decarbonization Panel Across 6 Mediterranean & European Economies ($N=192$)
  10. **Case Study 10 (`cs10_maritime_trade_port_connectivity_logistics_panel.ipynb`):** Global Maritime Trade, Container Port Throughput (TEU), UNCTAD Liner Connectivity (LSCI) & World Bank LPI Econometric Panel ($N=96$)

---

## Quick Start Examples

### 1. Data Retrieval, Multi-Indicator Panel Construction & Provenance
```python
import gomd

# Print official APA, IEEE, and BibTeX citations
gomd.cite()

client = gomd.GOMDClient(api_key="gomd_live_ent_YOUR_KEY", enable_cache=True)

# Search across 764 indicators
matches = client.search_indicators(keyword="aragonite")

# Build an entity-by-period panel combining multiple indicators
panel = client.build_panel(
    indicator_keys=[
        "ocean_ph_in_situ_total_scale",
        "omega_aragonite_saturation_state",
        "copernicus_sst_med_anomaly",
    ],
    period_from="2015",
    period_to="2025",
    as_dataframe=True,
)
```

### 2. Oceanographic & Biogeochemical Modeling (`gomd.ocean`)
```python
from gomd.ocean import seawater_density_eos80, carbonate_system, trophic_state_index, mucilage_risk_index

# UNESCO EOS-80 Seawater Density & Potential Density Anomaly
eos = seawater_density_eos80(salinity_psu=38.5, temp_c=24.2, pressure_dbar=50)
print(eos["density_kg_m3"], eos["sigma_t_kg_m3"])

# Marine Carbonate Equilibrium & Aragonite Saturation (Omega_arag)
carb = carbonate_system(ph_total=8.04, temp_c=22.0, salinity_psu=38.4, ta_umol_kg=2560)
print(carb["pCO2_uatm"], carb["omega_aragonite"], carb["calcification_regime"])

# Sea of Marmara Mucilage Hazard Index
muc = mucilage_risk_index(sst_anomaly_c=2.4, n_p_molar_ratio=4.8, wind_speed_ms=1.9, residence_time_days=45, chl_a_ug_l=11.5)
print(muc["mucilage_risk_index_0_100"], muc["alert_level"])
```

### 3. Maritime Decarbonization & Green Shipping Finance (`gomd.maritime`)
```python
from gomd.maritime import calculate_imo_cii, calculate_eu_ets_exposure, poseidon_principles_alignment

# IMO CII Rating (A-E) for an 85,000 DWT Bulk Carrier burning VLSFO in 2026
cii = calculate_imo_cii(
    fuel_consumption_tonnes=6400,
    dwt_or_gt=85000,
    distance_nm=58000,
    ship_type="bulk_carrier",
    fuel_type="VLSFO",
    year=2026,
)
print(cii["attained_aer_g_co2_dwt_nm"], cii["cii_rating"], cii["rating_boundaries"])

# EU ETS Maritime Exposure (2026 = 100% phase-in + CH4 & N2O included)
ets = calculate_eu_ets_exposure(co2_tonnes=18500, ch4_tonnes=12.4, n2o_tonnes=0.8, voyage_scope="eu_extra", year=2026, eua_price_eur=74.5)
print(ets["surrender_allowances_eua"], ets["estimated_cost_eur"])
```

### 4. Climate Trend Detection & Panel Econometrics on Live GOMD Series (`gomd.stats`)
```python
import gomd
from gomd.stats import mann_kendall_sen, pettitt_changepoint, multivariate_data_mining_pipeline

client = gomd.GOMDClient()
sst_rows = client.get_series("copernicus_sst_med", entity="TUR", period_from=1990, period_to=2026, as_df=False)
co2_rows = client.get_series("gml_mauna_loa_co2_ppm", entity="WLD", period_from=1990, period_to=2026, as_df=False)
ph_rows  = client.get_series("socat_surface_ph_total_scale", entity="TUR", period_from=1990, period_to=2026, as_df=False)

sst_series = [float(r["value"]) for r in sst_rows]
years      = [int(str(r["period"])[:4]) for r in sst_rows]

mk = mann_kendall_sen(sst_series, years)
print(mk["theil_sen_slope"], mk["p_value"], mk["trend_classification"])

cp = pettitt_changepoint(sst_series, labels=years)
print(cp["changepoint_label"], cp["pre_regime_mean"], cp["post_regime_mean"])

# Multivariate Ocean & Maritime Data Mining Pipeline (PCA + K-Means++ + Time-Series CV Ridge)
n_common = min(len(sst_rows), len(co2_rows), len(ph_rows))
dm = multivariate_data_mining_pipeline(
    feature_matrix=[[float(sst_rows[i]["value"]), float(co2_rows[i]["value"]), float(ph_rows[i]["value"])] for i in range(n_common)],
    feature_names=["SST_C", "CO2_ppm", "pH_Total"],
    period_labels=[str(sst_rows[i]["period"])[:4] for i in range(n_common)],
    target_index=0,
    k_clusters=3,
)
print(dm["pca"]["cumulative_variance_pc1_pc2_pct"], dm["kmeans_regimes"]["silhouette_score"])
```

### 5. Maritime Jurisdiction ("Mavi Vatan" — UN Letter A/74/757) & ICJ Equitable Delimitation Audit (`gomd.spatial`)
```python
import gomd

# ICJ Coastal-Length Proportionality & Third-Party Geodatabase (VLIZ/Seville Map) Audit
audit = gomd.mavi_vatan_eez_audit(
    mainland_coast_km=1577.0,
    opposite_coast_km=19.0,
    un_registered_area_km2=462000.0,
    provider_polygon_area_km2=254026.0,
)
print(audit["provider_area_discrepancy_km2"], audit["equitable_delimitation_compliance_score"])

# Query Official Turkish MFA / SHODB / DEHUKAM Maritime Jurisdiction Series (1986-2026)
df_mv = gomd.get_mavi_vatan_jurisdiction("mavi_vatan_official_jurisdiction_km2", entities=["TUR", "TRNC", "LBY", "BGR", "ROU"])

# Project COUNTER Release 5.1 & Make Data Count Scientific Portal Usage Econometrics
usage = gomd.counter_r5_usage_econometrics(
    pageviews_by_module={"ocean_observations": 14800, "maritime_decarbonization": 9600, "blue_finance": 7400, "cop31_governance": 6200, "sdk_research": 5100},
    dau=420, wau=1850, mau=4900, authenticated_sessions=6400, total_sessions=21500
)
print(usage["counter_r51_metrics"], usage["information_theory_concentration"]["shannon_attention_entropy_bits"])

# Source-Grounded Retrieval-Augmented Data Assistant & Numeric Grounding Audit
res = gomd.ask_assistant("Ege'de 2015 sonrası deniz yüzeyi sıcaklığı eğilimi nedir?", lang="tr")
print(res["answer"], res["citations"])
grounding = gomd.audit_numeric_grounding(res["answer"], [19.4, 21.8, 0.042], question="Ege'de 2015 sonrası eğilim")
print(grounding["grounding_rate"], grounding["unverified"])
```

---

## Mandatory Academic Citation

If you use the GOMD platform, its curated datasets, or the `gomd` Python/R software packages in any scientific publication, thesis, or policy report, **please cite the official GOMD reference paper**:

> Piri Reis University Maritime Sustainability Research Centre, & GOMD Scientific Consortium. (2026). *GOMD: A Global Ocean, Maritime, and Climate Data Platform with Official Python and R Software Development Kits for Reproducible Marine Governance* (Version 2.0.0) [Computer software & Dataset]. *GOMD Technical & Scientific Reference Series*, 1(1), 1–28. https://gomd.pirireis.edu.tr/sdk_paper.php
