gomd 2.1.0__py3-none-any.whl

gomd/__init__.py

@@ -0,0 +1,380 @@
+"""
+GOMD — Official Python Scientific, Oceanographic, Maritime Decarbonization & Econometric SDK (v2.1.0)
+Global Ocean & Maritime Data Platform (Piri Reis University / COP31 Türkiye)
+https://gomd.pirireis.edu.tr | Documentation: https://gomd.pirireis.edu.tr/python_sdk_docs.php
+
+Modules included in gomd v2.1.0:
+  1. gomd.client   — Authenticated REST/Bulk Client, Multi-Indicator Panel Builder, SHA-256 Provenance & Local Disk Cache
+  2. gomd.ocean    — Physical & Biogeochemical Oceanography + Post-2020 Frontier Methods:
+                     EOS-80 Density, TEOS-10 GSW & Sallée (Nature 2021) Stratification, Garcia & Gordon DO Solubility & AOU,
+                     Marine Carbonate System & Omega_arag, Hobday MHW Detector, Gruber (Science 2021) & Burger (Nature 2022)
+                     Triple Compound MHW+OAX+LOX Event & Clarke (2021) Aerobic Growth Index (AGI), Carlson TSI & Vollenweider
+                     TRIX, Mucilage Risk Index, and Bertram (2021) / Rennert (Nature 2022) Blue Carbon SCC Valuation.
+  3. gomd.maritime — Maritime Decarbonization, Green Finance & Port State Control + Post-2020 Frontier Regulations:
+                     IMO CII AER & Rating A-E, Directive (EU) 2023/959 Maritime EU ETS Phase-in, Regulation (EU) 2023/1805
+                     FuelEU Maritime Well-to-Wake (WtW) GHG Intensity & RFNBO 2x Multiplier, IMO 2023 Revised GHG Strategy
+                     (MEPC.377(80)) Stranded-Asset & Carbon VaR, Bottom-Up AIS Admiralty-Cube Propulsion & Slow-Steaming
+                     Elasticity, Poseidon Principles Alignment, and Paris/Med MoU PSC Risk Profile.
+  4. gomd.stats    — Non-Parametric Environmental, Causal & Panel Econometrics + Post-2020 Frontier Methods:
+                     Mann-Kendall Trend, Theil-Sen Slope, Pettitt Regime Shift, Gumbel Return Levels, Engle-Granger
+                     Cointegration, One-Way Fixed Effects Panel Estimator, Arkhangelsky et al. (AER 2021) Synthetic
+                     Difference-in-Differences (SDID), Şen (2020/2021) Innovative Polygon & Sub-Regime Quantile Trend,
+                     and Runge et al. (Nature Comms / Nat. Rev. 2023) Information-Theoretic Shannon Transfer Entropy.
+  5. gomd.spatial  — Geodesic & Chokepoint Spatial Analytics (Haversine Distance & Bearing, IHO Sea-Basin Classifier,
+                     Global 10-Chokepoint Proximity Matrix, OGC CRS84 GeoJSON Exporter)
+  6. gomd.cli      — Command-Line Interface (`python -m gomd cite | cii | carbonate | basin`)
+  7. gomd.dynamics — Port, Fisheries & Climate Dynamics Toolkit (new in 2.1.0; methods used in the GOMD research papers):
+                     Symmetric (DHS) Growth, Static Principal-Component Global Factor & Variance Shares, Index of Dispersion,
+                     Cargo Bunching & Compound-Poisson Benchmark, Day-of-Week Profile, Gibrat's-Law & Volatility-Size Scaling,
+                     Portfolio Effect & Synchrony, Exceedance Return Interval, Benjamini-Hochberg FDR, Binomial Field
+                     Significance, and Event-Study Local Projections with Unit & Time Fixed Effects.
+
+Please cite GOMD in any academic publication, thesis, or policy report using this package:
+    >>> import gomd
+    >>> print(gomd.cite())
+"""
+
+from __future__ import annotations
+
+from . import cli, client, dynamics, maritime, ocean, spatial, stats
+from .client import (
+    CITATION_APA,
+    CITATION_BIBTEX,
+    CITATION_IEEE,
+    CITATION_TR,
+    GOMDClient,
+    GOMDError,
+    cite,
+)
+from .maritime import (
+    FUELEU_WTW_PROFILES,
+    ais_speed_power_emissions,
+    arctic_route_navigability_index,
+    calculate_eu_ets_exposure,
+    calculate_fueleu_maritime,
+    calculate_imo_cii,
+    desalination_brine_green_h2_nexus,
+    fueleu_cii_ets_compliance_cost,
+    global_chokepoint_disruption_index,
+    imo_2023_strive_trajectory,
+    kunming_montreal_30x30_gap,
+    marine_insurance_actuarial_pricing,
+    poseidon_principles_alignment,
+    psc_detention_risk_score,
+    rfmo_stock_iuu_sustainability,
+    seaborne_trade_climate_coupling_index,
+    subsea_corridor_vulnerability_index,
+)
+from .ocean import (
+    blue_carbon_sequestration_valuation,
+    carbonate_system,
+    climate_teleconnection_regime,
+    coastal_storm_surge_offshore_wind_nexus,
+    compound_mhw_oax_event,
+    coral_bleaching_dhw_risk,
+    cwon_wealth_accounting,
+    ectotherm_thermal_shock_index,
+    global_hypoxia_deadzone_index,
+    lme_trophic_hypoxia_stress,
+    marine_heatwave_detect,
+    marine_plastic_ghost_gear_risk,
+    mucilage_risk_index,
+    ocean_climate_velocity,
+    offshore_wind_marine_energy_lcoe,
+    oxygen_solubility,
+    polar_cryosphere_basal_melt_albedo,
+    river_delta_plastic_nutrient_export,
+    seawater_density_eos80,
+    sids_slr_cyclone_vulnerability,
+    sst_warming_velocity_profile,
+    stochastic_sst_memory_ou,
+    sustainable_insurance_cat_var,
+    teos10_gsw_stratification,
+    trophic_state_index,
+)
+from .spatial import (
+    GLOBAL_CHOKEPOINTS,
+    chokepoint_proximity,
+    classify_sea_basin,
+    haversine_distance,
+    mavi_vatan_eez_audit,
+    to_geojson,
+)
+from .dynamics import (
+    cargo_bunching,
+    common_factor_decomposition,
+    dispersion_index,
+    exceedance_return_interval,
+    fdr_benjamini_hochberg,
+    field_significance,
+    local_projection_event,
+    portfolio_effect,
+    size_growth_scaling,
+    symmetric_growth,
+    weekday_profile,
+)
+from .stats import (
+    audit_numeric_grounding,
+    cointegration_eg_test,
+    counter_r5_usage_econometrics,
+    extreme_return_levels,
+    innovative_polygon_trend,
+    mann_kendall_sen,
+    multivariate_data_mining_pipeline,
+    panel_fixed_effects,
+    pettitt_changepoint,
+    synthetic_did_ate,
+    transfer_entropy_causal,
+)
+
+_default_client: GOMDClient | None = None
+
+
+def _client() -> GOMDClient:
+    global _default_client
+    if _default_client is None:
+        _default_client = GOMDClient()
+    return _default_client
+
+
+def get_public_catalog():
+    return _client().get_public_catalog()
+
+
+def get_public_sources(as_df: bool = True):
+    return _client().get_public_sources(as_df=as_df)
+
+
+def search_indicators(keyword: str = "", category: str | None = None, source_key: str | None = None, as_df: bool = True):
+    return _client().search_indicators(keyword=keyword, category=category, source_key=source_key, as_df=as_df)
+
+
+def get_indicator_detail(indicator: str = "gml_mauna_loa_co2_ppm", dataset: str = "open"):
+    return _client().get_indicator_detail(indicator=indicator, dataset=dataset)
+
+
+def get_series(indicator: str = "gml_mauna_loa_co2_ppm", entity="WLD", period_from=None, period_to=None, limit: int = 5000, as_df: bool = True):
+    return _client().get_series(indicator=indicator, entity=entity, period_from=period_from, period_to=period_to, limit=limit, as_df=as_df)
+
+
+def get_blue_finance_atlas(
+    indicator: str = "iumi_marine_insurance_total_premium_usd_mn",
+    entities=("WLD", "EU27", "CHN", "USA", "NOR", "TUR"),
+    period_from: int = 1995,
+    period_to: int = 2025,
+    as_df: bool = True,
+):
+    return _client().get_blue_finance_atlas(
+        indicator=indicator,
+        entities=entities,
+        period_from=period_from,
+        period_to=period_to,
+        as_df=as_df,
+    )
+
+
+def get_mavi_vatan_jurisdiction(
+    indicator: str = "mavi_vatan_official_jurisdiction_km2",
+    entities=("TUR", "TRNC", "LBY", "EGY", "BGR", "ROU", "RUS", "UKR", "GEO", "GRC", "CYP"),
+    period_from: int = 1986,
+    period_to: int = 2026,
+    as_df: bool = True,
+):
+    return _client().get_mavi_vatan_jurisdiction(
+        indicator=indicator,
+        entities=entities,
+        period_from=period_from,
+        period_to=period_to,
+        as_df=as_df,
+    )
+
+
+def get_platform_telemetry_panel(
+    indicator: str = "counter_r51_scientific_portal_investigations",
+    entities=("TUR", "EU27", "USA", "GBR", "DEU", "WLD"),
+    period_from: int = 2018,
+    period_to: int = 2026,
+    as_df: bool = True,
+):
+    """Deprecated / bilgi amaçlı.
+
+    COUNTER R5.1 platform telemetri serileri GOMD veritabanında yayımlanmamaktadır
+    (canlı veritabanında 0 gözlem). Bu fonksiyon geriye dönük uyumluluk için korunur
+    ve genellikle boş sonuç döndürür. Platform kullanım istatistikleri için yöneticiler
+    ``platform_analytics.php`` panelini kullanmalıdır.
+    """
+    return _client().get_platform_telemetry_panel(
+        indicator=indicator,
+        entities=entities,
+        period_from=period_from,
+        period_to=period_to,
+        as_df=as_df,
+    )
+
+
+def analyze_gomd_series(indicator: str = "gml_mauna_loa_co2_ppm", entity: str = "WLD", period_from=None, period_to=None):
+    return _client().analyze_gomd_series(indicator=indicator, entity=entity, period_from=period_from, period_to=period_to)
+
+
+def analyze_gomd_basin(basin_code: str = "OCN_MED_LEVANTINE", salinity_psu=38.6, ph_total=8.06, total_alkalinity_umol_kg: float = 2610.0):
+    return _client().analyze_gomd_basin(basin_code=basin_code, salinity_psu=salinity_psu, ph_total=ph_total, total_alkalinity_umol_kg=total_alkalinity_umol_kg)
+
+
+def analyze_gomd_policy(indicator: str = "worldbank_primary_index_v2026", treated_entity: str = "TUR", control_entities=("DEU", "FRA", "ITA", "ESP", "GRC"), intervention_year: int = 2022, period_from: int = 2015, period_to: int = 2025):
+    return _client().analyze_gomd_policy(indicator=indicator, treated_entity=treated_entity, control_entities=control_entities, intervention_year=intervention_year, period_from=period_from, period_to=period_to)
+
+
+def build_panel(indicators=None, entities=None, period_from=1990, period_to=2025, dataset: str = "open_data_observations", limit_per_indicator: int = 10000, as_df: bool = True, indicator_keys=None, as_dataframe: bool | None = None):
+    if as_dataframe is not None:
+        as_df = bool(as_dataframe)
+    return _client().build_panel(indicators=indicators, entities=entities, period_from=period_from, period_to=period_to, dataset=dataset, limit_per_indicator=limit_per_indicator, as_df=as_df, indicator_keys=indicator_keys, as_dataframe=as_dataframe)
+
+
+def query(dataset: str = "open_data_observations", filters=None, search=None, period_from=None, period_to=None, order_by=None, order_dir: str = "DESC", limit: int = 1000, offset: int = 0, as_df: bool = True):
+    return _client().query(dataset=dataset, filters=filters, search=search, period_from=period_from, period_to=period_to, order_by=order_by, order_dir=order_dir, limit=limit, offset=offset, as_df=as_df)
+
+
+def timeseries(dataset: str = "open_data_observations", value_column: str = "value", filters=None, period_from=None, period_to=None, as_df: bool = True):
+    return _client().timeseries(dataset=dataset, value_column=value_column, filters=filters, period_from=period_from, period_to=period_to, as_df=as_df)
+
+
+def bulk_export(dataset: str = "open_data_observations", fmt: str = "csv", limit: int = 50000, period_from=None, period_to=None, as_df: bool = True):
+    return _client().bulk_export(dataset=dataset, fmt=fmt, limit=limit, period_from=period_from, period_to=period_to, as_df=as_df)
+
+
+def verify_provenance(payload, expected_sha256=None):
+    return GOMDClient.verify_provenance(payload=payload, expected_sha256=expected_sha256)
+
+
+def ask_assistant(question: str, lang: str = "tr", history=None):
+    """GOMD Veri Asistanı'na (RAG + araç çağırma) kaynak atıflı soru sorar."""
+    return _client().ask_assistant(question=question, lang=lang, history=history)
+
+
+def assistant_status():
+    """Veri Asistanı durumunu ve kalan günlük kotayı döndürür."""
+    return _client().assistant_status()
+
+
+__version__ = "2.1.0"
+__paper_url__ = "https://gomd.pirireis.edu.tr/sdk_paper.php"
+__citation__ = CITATION_APA
+__bibtex__ = CITATION_BIBTEX
+
+__all__ = [
+    # Core Client & Citations
+    "GOMDClient",
+    "GOMDError",
+    "cite",
+    "CITATION_APA",
+    "CITATION_IEEE",
+    "CITATION_TR",
+    "CITATION_BIBTEX",
+    "get_public_catalog",
+    "get_public_sources",
+    "search_indicators",
+    "get_indicator_detail",
+    "get_series",
+    "get_blue_finance_atlas",
+    "get_mavi_vatan_jurisdiction",
+    "get_platform_telemetry_panel",
+    "analyze_gomd_series",
+    "analyze_gomd_basin",
+    "analyze_gomd_policy",
+    "build_panel",
+    "query",
+    "timeseries",
+    "bulk_export",
+    "verify_provenance",
+    "ask_assistant",
+    "assistant_status",
+    # Submodules
+    "client",
+    "ocean",
+    "maritime",
+    "stats",
+    "dynamics",
+    "spatial",
+    "cli",
+    # Oceanography, Blue Carbon & Parametric Sustainability Insurance (gomd.ocean)
+    "seawater_density_eos80",
+    "teos10_gsw_stratification",
+    "oxygen_solubility",
+    "carbonate_system",
+    "marine_heatwave_detect",
+    "compound_mhw_oax_event",
+    "trophic_state_index",
+    "mucilage_risk_index",
+    "blue_carbon_sequestration_valuation",
+    "sustainable_insurance_cat_var",
+    "cwon_wealth_accounting",
+    "sst_warming_velocity_profile",
+    "ocean_climate_velocity",
+    "ectotherm_thermal_shock_index",
+    "stochastic_sst_memory_ou",
+    "global_hypoxia_deadzone_index",
+    "offshore_wind_marine_energy_lcoe",
+    "marine_plastic_ghost_gear_risk",
+    "coastal_storm_surge_offshore_wind_nexus",
+    "climate_teleconnection_regime",
+    "coral_bleaching_dhw_risk",
+    "lme_trophic_hypoxia_stress",
+    "river_delta_plastic_nutrient_export",
+    "sids_slr_cyclone_vulnerability",
+    "polar_cryosphere_basal_melt_albedo",
+    # Maritime, Decarbonization & Marine Insurance Underwriting (gomd.maritime)
+    "FUELEU_WTW_PROFILES",
+    "calculate_imo_cii",
+    "calculate_eu_ets_exposure",
+    "calculate_fueleu_maritime",
+    "imo_2023_strive_trajectory",
+    "ais_speed_power_emissions",
+    "poseidon_principles_alignment",
+    "psc_detention_risk_score",
+    "marine_insurance_actuarial_pricing",
+    "global_chokepoint_disruption_index",
+    "kunming_montreal_30x30_gap",
+    "arctic_route_navigability_index",
+    "seaborne_trade_climate_coupling_index",
+    "fueleu_cii_ets_compliance_cost",
+    "subsea_corridor_vulnerability_index",
+    "rfmo_stock_iuu_sustainability",
+    "desalination_brine_green_h2_nexus",
+    # Econometrics, Causal Inference & Climate Statistics (gomd.stats)
+    "mann_kendall_sen",
+    "pettitt_changepoint",
+    "extreme_return_levels",
+    "cointegration_eg_test",
+    "panel_fixed_effects",
+    "synthetic_did_ate",
+    "innovative_polygon_trend",
+    "transfer_entropy_causal",
+    "multivariate_data_mining_pipeline",
+    "counter_r5_usage_econometrics",
+    "audit_numeric_grounding",
+    # Spatial & Chokepoints (gomd.spatial)
+    "GLOBAL_CHOKEPOINTS",
+    "haversine_distance",
+    "classify_sea_basin",
+    "chokepoint_proximity",
+    "mavi_vatan_eez_audit",
+    "to_geojson",
+    # Metadata
+    # Port, Fisheries & Climate Dynamics (gomd.dynamics, new in 2.1.0)
+    "cargo_bunching",
+    "common_factor_decomposition",
+    "dispersion_index",
+    "exceedance_return_interval",
+    "fdr_benjamini_hochberg",
+    "field_significance",
+    "local_projection_event",
+    "portfolio_effect",
+    "size_growth_scaling",
+    "symmetric_growth",
+    "weekday_profile",
+    "__version__",
+    "__paper_url__",
+    "__citation__",
+    "__bibtex__",
+]
+

gomd/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for `python -m gomd`."""
+
+import sys
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

gomd/cli.py

@@ -0,0 +1,76 @@
+"""
+gomd.cli — Command-Line Interface for the GOMD Python SDK
+Usage:
+    python -m gomd cite [apa|tr|ieee|bibtex]
+    python -m gomd cii --fuel 4200 --dwt 82000 --nm 58000 --type bulk_carrier
+    python -m gomd carbonate --ph 8.06 --temp 18.5 --salinity 38.2
+    python -m gomd basin --lat 40.98 --lon 28.95
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, Optional
+
+from .client import GOMDClient, cite
+from .maritime import calculate_imo_cii
+from .ocean import carbonate_system, seawater_density_eos80
+from .spatial import chokepoint_proximity
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="gomd",
+        description="GOMD Official Scientific & Maritime Analytics CLI (https://gomd.pirireis.edu.tr)",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # 1. cite
+    p_cite = sub.add_parser("cite", help="Print official academic citation for GOMD")
+    p_cite.add_argument("style", nargs="?", default="all", choices=["all", "apa", "tr", "ieee", "bibtex"])
+
+    # 2. cii
+    p_cii = sub.add_parser("cii", help="Calculate IMO CII AER, Required CII & A-E Rating")
+    p_cii.add_argument("--fuel", type=float, required=True, help="Fuel consumption in metric tonnes")
+    p_cii.add_argument("--dwt", type=float, required=True, help="Deadweight tonnage (DWT)")
+    p_cii.add_argument("--nm", type=float, required=True, help="Distance sailed in nautical miles")
+    p_cii.add_argument("--type", default="bulk_carrier", help="Vessel type")
+    p_cii.add_argument("--fuel-type", default="vlsfo", help="Fuel type (vlsfo, hfo, mdo, lng, methanol)")
+    p_cii.add_argument("--year", type=int, default=2026, help="Reporting year")
+
+    # 3. carbonate
+    p_carb = sub.add_parser("carbonate", help="Solve surface ocean carbonate chemistry & Omega_arag")
+    p_carb.add_argument("--ph", type=float, required=True, help="Total-scale pH")
+    p_carb.add_argument("--temp", type=float, required=True, help="Sea surface temperature (C)")
+    p_carb.add_argument("--salinity", type=float, default=35.0, help="Salinity (PSU)")
+    p_carb.add_argument("--ta", type=float, default=2320.0, help="Total alkalinity (umol/kg)")
+
+    # 4. basin
+    p_basin = sub.add_parser("basin", help="Classify sea basin and compute chokepoint distances")
+    p_basin.add_argument("--lat", type=float, required=True, help="Latitude")
+    p_basin.add_argument("--lon", type=float, required=True, help="Longitude")
+
+    args = parser.parse_args(argv)
+    if args.command in (None, "cite"):
+        style = getattr(args, "style", "all")
+        print(cite(style))
+        return 0
+    if args.command == "cii":
+        res = calculate_imo_cii(args.fuel, args.dwt, args.nm, args.type, args.fuel_type, args.year)
+        print(json.dumps(res, indent=2))
+        return 0
+    if args.command == "carbonate":
+        res = carbonate_system(args.ph, args.temp, args.salinity, args.ta)
+        print(json.dumps(res, indent=2))
+        return 0
+    if args.command == "basin":
+        res = chokepoint_proximity(args.lat, args.lon)
+        print(json.dumps(res, indent=2))
+        return 0
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())