gomd 2.1.0__tar.gz

gomd-2.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Piri Reis University — Maritime Sustainability Research Centre (GOMD / COP31 Türkiye)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gomd-2.1.0/PKG-INFO

@@ -0,0 +1,277 @@
+Metadata-Version: 2.4
+Name: gomd
+Version: 2.1.0
+Summary: Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK for GOMD (Piri Reis University / COP31 Türkiye)
+Home-page: https://gomd.pirireis.edu.tr
+Author: Piri Reis University Global Ocean & Maritime Data Platform (GOMD)
+Author-email: "Piri Reis University Global Ocean & Maritime Data Platform (GOMD)" <gomd@pirireis.edu.tr>
+License: MIT
+Project-URL: Homepage, https://gomd.pirireis.edu.tr
+Project-URL: Documentation, https://gomd.pirireis.edu.tr/python_sdk_docs.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
+License-File: LICENSE
+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"
+Dynamic: author
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# `gomd` — Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK (v2.1.0)
+
+[![Version](https://img.shields.io/badge/version-2.1.0-0ea5e9.svg)](https://gomd.pirireis.edu.tr)
+[![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)
+[![Documentation](https://img.shields.io/badge/Documentation-GOMD_SDK_Manual-indigo.svg)](https://gomd.pirireis.edu.tr/python_sdk_docs.php)
+
+**`gomd` (v2.1.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.1.0 includes **7 specialized scientific submodules** 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.1.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$)
+
+---
+
+## What's new in 2.1.0 — `gomd.dynamics`
+
+Eleven pure-Python functions with the analysis methods used in the GOMD research papers
+(<https://gomd.pirireis.edu.tr/publications.php>). All are also exported at package level.
+
+| Function | What it computes |
+|---|---|
+| `symmetric_growth` | Symmetric (Davis–Haltiwanger–Schuh) growth rate, e.g. year-on-year growth of monthly port calls |
+| `common_factor_decomposition` | Static principal-component global factor, loadings and the share of each series' variance it explains |
+| `dispersion_index` | Variance-to-mean ratio of counts (1 = Poisson arrivals) with a dispersion test |
+| `cargo_bunching` | Cargo per call, coefficient of variation of daily cargo and its compound-Poisson benchmark |
+| `weekday_profile` | Day-of-week profile and weekend ratio of a daily series |
+| `size_growth_scaling` | Gibrat's-law test and the size scaling of growth volatility |
+| `portfolio_effect` | Portfolio effect, synchrony and effective number of components of an aggregate |
+| `exceedance_return_interval` | Empirical return interval of threshold exceedances, with an early/late comparison |
+| `fdr_benjamini_hochberg` | Benjamini–Hochberg false-discovery-rate adjustment |
+| `field_significance` | Binomial field-significance test for a collection of local tests |
+| `local_projection_event` | Event-study local projections with unit and time fixed effects and unit-clustered standard errors |
+
+```python
+import gomd
+rows = gomd.get_series("IMF_PW_PORT_CALLS_D", entity="IMF_PORT_2049", as_df=False)   # daily port calls, Ambarli
+calls = [r["value"] for r in rows]
+print(gomd.dispersion_index(calls))                                   # 1 = Poisson arrivals
+print(gomd.weekday_profile([r["period"] for r in rows], calls))       # weekend dip
+print(gomd.fdr_benjamini_hochberg([0.001, 0.02, 0.04, 0.30, 0.75]))
+```
+
+GOMD-derived indicators and their methods: <https://gomd.pirireis.edu.tr/derived_methodology.php>
+
+## 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 all harmonized indicators (live counts: https://gomd.pirireis.edu.tr)
+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"])
+
+# Global Chokepoint Disruption, Kunming-Montreal 30x30 MPA Gap & Coastal Hypoxia Dead-Zone Index
+choke = gomd.global_chokepoint_disruption_index(baseline_transits=25840, observed_transits=13120, reroute_extra_nm=3500.0)
+mpa_gap = gomd.kunming_montreal_30x30_gap(current_mpa_pct=8.35, eez_area_km2=137000000.0)
+hypoxia = gomd.global_hypoxia_deadzone_index(subpycnocline_do_mg_l=1.42, chlorophyll_a_ug_l=11.2, secchi_depth_m=2.1, din_dip_molar_ratio=28.4)
+print(choke["disruption_severity_index_0_100"], mpa_gap["required_cagr_pct"], hypoxia["oxygen_regime"])
+
+# Coupled Teleconnections (ENSO/IOD/PDO/AMO/AMOC), Coral Bleaching DHW, UN 66 LMEs, 50 River Deltas & Subsea Corridors
+tele = gomd.climate_teleconnection_regime(enso_oni_c=1.35, iod_dmi_c=0.52, amoc_26n_sv=16.1)
+coral = gomd.coral_bleaching_dhw_risk(dhw_c_weeks=9.8, hotspot_sst_anomaly_c=1.6, omega_aragonite=3.05)
+lme = gomd.lme_trophic_hypoxia_stress(primary_productivity_mgc_m2_d=720.0, fish_landings_mt_yr=1.85, mean_trophic_level=3.18)
+delta = gomd.river_delta_plastic_nutrient_export(discharge_km3_yr=480.0, plastic_export_tonnes_yr=34000.0, din_export_kt_n_yr=620.0, dip_export_kt_p_yr=45.0)
+fueleu_cost = gomd.fueleu_cii_ets_compliance_cost(annual_fuel_tonnes=12000.0, wtw_ghg_intensity_gco2e_mj=91.2, target_wtw_gco2e_mj=89.34)
+subsea = gomd.subsea_corridor_vulnerability_index(daily_vessel_transits=62.0, rerouting_detour_nm=3500.0, subsea_cable_count=18)
+```
+
+---
+
+## How to Cite GOMD
+
+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 GOMD platform**:
+
+> Piri Reis University Global Ocean & Maritime Data Platform (GOMD). (2026). *gomd: Official Python and R Scientific, Oceanographic, Maritime & Econometric Software Development Kits (Version 2.1.0)* [Computer software & Data platform]. https://gomd.pirireis.edu.tr

gomd-2.1.0/README.md

@@ -0,0 +1,236 @@
+# `gomd` — Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK (v2.1.0)
+
+[![Version](https://img.shields.io/badge/version-2.1.0-0ea5e9.svg)](https://gomd.pirireis.edu.tr)
+[![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)
+[![Documentation](https://img.shields.io/badge/Documentation-GOMD_SDK_Manual-indigo.svg)](https://gomd.pirireis.edu.tr/python_sdk_docs.php)
+
+**`gomd` (v2.1.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.1.0 includes **7 specialized scientific submodules** 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.1.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$)
+
+---
+
+## What's new in 2.1.0 — `gomd.dynamics`
+
+Eleven pure-Python functions with the analysis methods used in the GOMD research papers
+(<https://gomd.pirireis.edu.tr/publications.php>). All are also exported at package level.
+
+| Function | What it computes |
+|---|---|
+| `symmetric_growth` | Symmetric (Davis–Haltiwanger–Schuh) growth rate, e.g. year-on-year growth of monthly port calls |
+| `common_factor_decomposition` | Static principal-component global factor, loadings and the share of each series' variance it explains |
+| `dispersion_index` | Variance-to-mean ratio of counts (1 = Poisson arrivals) with a dispersion test |
+| `cargo_bunching` | Cargo per call, coefficient of variation of daily cargo and its compound-Poisson benchmark |
+| `weekday_profile` | Day-of-week profile and weekend ratio of a daily series |
+| `size_growth_scaling` | Gibrat's-law test and the size scaling of growth volatility |
+| `portfolio_effect` | Portfolio effect, synchrony and effective number of components of an aggregate |
+| `exceedance_return_interval` | Empirical return interval of threshold exceedances, with an early/late comparison |
+| `fdr_benjamini_hochberg` | Benjamini–Hochberg false-discovery-rate adjustment |
+| `field_significance` | Binomial field-significance test for a collection of local tests |
+| `local_projection_event` | Event-study local projections with unit and time fixed effects and unit-clustered standard errors |
+
+```python
+import gomd
+rows = gomd.get_series("IMF_PW_PORT_CALLS_D", entity="IMF_PORT_2049", as_df=False)   # daily port calls, Ambarli
+calls = [r["value"] for r in rows]
+print(gomd.dispersion_index(calls))                                   # 1 = Poisson arrivals
+print(gomd.weekday_profile([r["period"] for r in rows], calls))       # weekend dip
+print(gomd.fdr_benjamini_hochberg([0.001, 0.02, 0.04, 0.30, 0.75]))
+```
+
+GOMD-derived indicators and their methods: <https://gomd.pirireis.edu.tr/derived_methodology.php>
+
+## 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 all harmonized indicators (live counts: https://gomd.pirireis.edu.tr)
+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"])
+
+# Global Chokepoint Disruption, Kunming-Montreal 30x30 MPA Gap & Coastal Hypoxia Dead-Zone Index
+choke = gomd.global_chokepoint_disruption_index(baseline_transits=25840, observed_transits=13120, reroute_extra_nm=3500.0)
+mpa_gap = gomd.kunming_montreal_30x30_gap(current_mpa_pct=8.35, eez_area_km2=137000000.0)
+hypoxia = gomd.global_hypoxia_deadzone_index(subpycnocline_do_mg_l=1.42, chlorophyll_a_ug_l=11.2, secchi_depth_m=2.1, din_dip_molar_ratio=28.4)
+print(choke["disruption_severity_index_0_100"], mpa_gap["required_cagr_pct"], hypoxia["oxygen_regime"])
+
+# Coupled Teleconnections (ENSO/IOD/PDO/AMO/AMOC), Coral Bleaching DHW, UN 66 LMEs, 50 River Deltas & Subsea Corridors
+tele = gomd.climate_teleconnection_regime(enso_oni_c=1.35, iod_dmi_c=0.52, amoc_26n_sv=16.1)
+coral = gomd.coral_bleaching_dhw_risk(dhw_c_weeks=9.8, hotspot_sst_anomaly_c=1.6, omega_aragonite=3.05)
+lme = gomd.lme_trophic_hypoxia_stress(primary_productivity_mgc_m2_d=720.0, fish_landings_mt_yr=1.85, mean_trophic_level=3.18)
+delta = gomd.river_delta_plastic_nutrient_export(discharge_km3_yr=480.0, plastic_export_tonnes_yr=34000.0, din_export_kt_n_yr=620.0, dip_export_kt_p_yr=45.0)
+fueleu_cost = gomd.fueleu_cii_ets_compliance_cost(annual_fuel_tonnes=12000.0, wtw_ghg_intensity_gco2e_mj=91.2, target_wtw_gco2e_mj=89.34)
+subsea = gomd.subsea_corridor_vulnerability_index(daily_vessel_transits=62.0, rerouting_detour_nm=3500.0, subsea_cable_count=18)
+```
+
+---
+
+## How to Cite GOMD
+
+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 GOMD platform**:
+
+> Piri Reis University Global Ocean & Maritime Data Platform (GOMD). (2026). *gomd: Official Python and R Scientific, Oceanographic, Maritime & Econometric Software Development Kits (Version 2.1.0)* [Computer software & Data platform]. https://gomd.pirireis.edu.tr