eptr2 1.4.0__tar.gz → 1.4.1.dev0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/PKG-INFO +1 -1
  2. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/pyproject.toml +1 -1
  3. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/eptr2_api_schema.json +13 -8
  4. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +1 -1
  5. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +2 -0
  6. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +8 -3
  7. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/idm.py +2 -2
  8. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/dabi_idm.py +9 -10
  9. eptr2-1.4.1.dev0/src/eptr2/composite/idm_log.py +278 -0
  10. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/org_activity.py +55 -117
  11. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/periodic_orgs.py +14 -1
  12. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/plant_costs.py +5 -0
  13. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/price_and_cost.py +11 -6
  14. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/main.py +8 -1
  15. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/help.py +2 -2
  16. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/processing.py +4 -1
  17. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/postprocess/items.py +12 -0
  18. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/util/costs.py +21 -14
  19. eptr2-1.4.0/src/eptr2/composite/idm_log.py +0 -131
  20. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/LICENSE +0 -0
  21. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/README.md +0 -0
  22. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md +0 -0
  23. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md +0 -0
  24. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml +0 -0
  25. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/src/eptr2/mcp/README.md +0 -0
  26. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md +0 -0
  27. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/pyproject.toml +0 -0
  28. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/.gitignore +0 -0
  29. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/LICENSE +0 -0
  30. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/README.md +0 -0
  31. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/docs/assets/README.md +0 -0
  32. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/examples/README.md +0 -0
  33. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/__init__.py +0 -0
  34. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/__main__.py +0 -0
  35. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/agentic/__init__.py +0 -0
  36. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/agentic/discovery.py +0 -0
  37. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/agentic/schema.py +0 -0
  38. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/agentic/skills.py +0 -0
  39. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/agentic/validation.py +0 -0
  40. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/__init__.py +0 -0
  41. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/mcp.json +0 -0
  42. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/plugin.json +0 -0
  43. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +0 -0
  44. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-api-discovery/scripts/list_endpoints.py +0 -0
  45. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +0 -0
  46. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +0 -0
  47. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +0 -0
  48. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +0 -0
  49. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +0 -0
  50. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +0 -0
  51. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +0 -0
  52. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-market-operations/examples.md +0 -0
  53. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +0 -0
  54. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +0 -0
  55. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +0 -0
  56. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/__init__.py +0 -0
  57. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/ancillary.py +0 -0
  58. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/bilateral.py +0 -0
  59. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/bpm.py +0 -0
  60. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/consumption.py +0 -0
  61. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/dam.py +0 -0
  62. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/dams.py +0 -0
  63. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/general.py +0 -0
  64. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/generation.py +0 -0
  65. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/imbalance.py +0 -0
  66. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/mms.py +0 -0
  67. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/ng_general.py +0 -0
  68. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/ng_sgp.py +0 -0
  69. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/ng_transmission.py +0 -0
  70. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/ng_vgp.py +0 -0
  71. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/renewables.py +0 -0
  72. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/reporting.py +0 -0
  73. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/retroactive.py +0 -0
  74. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/transmission.py +0 -0
  75. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/vep.py +0 -0
  76. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/calls/yek_g.py +0 -0
  77. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/cli.py +0 -0
  78. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/__init__.py +0 -0
  79. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/ancillary.py +0 -0
  80. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/bpm.py +0 -0
  81. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/consumption.py +0 -0
  82. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/ids.py +0 -0
  83. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/mms.py +0 -0
  84. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/composite/production.py +0 -0
  85. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/__init__.py +0 -0
  86. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/checks.py +0 -0
  87. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/parameters.py +0 -0
  88. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mapping/path.py +0 -0
  89. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mcp/README.md +0 -0
  90. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mcp/__init__.py +0 -0
  91. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/mcp/server.py +0 -0
  92. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/__init__.py +0 -0
  93. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/postprocess/__init__.py +0 -0
  94. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/preprocess/__init__.py +0 -0
  95. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/preprocess/calls.py +0 -0
  96. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/processing/preprocess/params.py +0 -0
  97. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/util/__init__.py +0 -0
  98. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/util/certificate.py +0 -0
  99. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/util/evaluation.py +0 -0
  100. {eptr2-1.4.0 → eptr2-1.4.1.dev0}/src/eptr2/util/time.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: eptr2
3
- Version: 1.4.0
3
+ Version: 1.4.1.dev0
4
4
  Summary: EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed
5
5
  Project-URL: Homepage, https://github.com/Tideseed/eptr2
6
6
  Project-URL: Documentation, https://tideseed.github.io/eptr2/
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "eptr2"
3
- version = "1.4.0"
3
+ version = "1.4.1.dev0"
4
4
  description = "EPIAS Transparency Platform v2.0 Python client by Robokami / Tideseed"
5
5
  authors = [{ name = "Tideseed", email = "info@tideseed.com" }]
6
6
  license = { text = "Apache License 2.0" }
@@ -5,7 +5,7 @@
5
5
  },
6
6
  "composite_functions": {
7
7
  "calculate_idm_contract_stats": {
8
- "module": "eptr2.composite.org_activity",
8
+ "module": "eptr2.composite.idm_log",
9
9
  "signature": "(log_df: pandas.DataFrame) -> pandas.DataFrame",
10
10
  "summary": "Calculates per contract intraday statistics from the IDM trade log (idm-log or idm_log_longer output)."
11
11
  },
@@ -114,6 +114,11 @@
114
114
  "signature": "(start_date: str, end_date: str, eptr: eptr2.main.EPTR2 | None = None, org_id: str | None = None, uevcb_id: str | None = None, verbose: bool = False, include_contract_symbol: bool = True, skip_kgup: bool = False, skip_kgup_v1: bool = False, skip_kudup: bool = False, **kwargs)",
115
115
  "summary": "This composite function gets KGUP v1, KGUP and KUDUP data and merges them."
116
116
  },
117
+ "get_idm_contract_stats": {
118
+ "module": "eptr2.composite.idm_log",
119
+ "signature": "(start_date: str, end_date: str, eptr: eptr2.main.EPTR2 | None = None, idm_log_df: pandas.DataFrame | None = None, export_to_csv: bool = True, export_dir: str = 'data', check_existing: bool = True, verbose: bool = False, **kwargs: Any) -> pandas.DataFrame",
120
+ "summary": "Market wide intraday (GİP) statistics per hourly contract for the given period (start_date and end_date inclusive), from the IDM trade log: idm_wap, idm_mad (MAD, mean absolute deviation, TL/MWh), idm_tad (TAD, total absolute deviation, TL), idm_trade_count and idm_volume_mwh. See calculate_idm_contract_stats."
121
+ },
117
122
  "get_kgup_bulk_range": {
118
123
  "module": "eptr2.composite.production",
119
124
  "signature": "(start_date: str, end_date: str, uevcb_ids: list, eptr: eptr2.main.EPTR2 | None = None, verbose: bool = False, strict: bool = True, include_contract_symbol: bool = True, **kwargs) -> pandas.DataFrame",
@@ -136,7 +141,7 @@
136
141
  },
137
142
  "get_org_estimated_activity": {
138
143
  "module": "eptr2.composite.org_activity",
139
- "signature": "(start_date: str, end_date: str, org_id: str | int, eptr: eptr2.main.EPTR2 | None = None, include_pnl: bool = False, include_tad: bool = False, idm_log_df: pandas.DataFrame | None = None, export_to_csv: bool = False, export_dir: str = 'data', check_existing: bool = True, verbose: bool = True, **kwargs) -> pandas.DataFrame",
144
+ "signature": "(start_date: str, end_date: str, org_id: str | int, eptr: eptr2.main.EPTR2 | None = None, include_pnl: bool = False, include_tad: bool = False, idm_log_df: pandas.DataFrame | None = None, export_to_csv: bool = True, export_dir: str = 'data', check_existing: bool = True, verbose: bool = True, **kwargs) -> pandas.DataFrame",
140
145
  "summary": "Estimates an organization's (company's) trading activity for the given period (start_date and end_date inclusive) on an hourly contract basis."
141
146
  },
142
147
  "get_periodic_generation_organization_lists": {
@@ -146,7 +151,7 @@
146
151
  },
147
152
  "get_reference_imbalance_costs": {
148
153
  "module": "eptr2.composite.price_and_cost",
149
- "signature": "(start_date: str, end_date: str, eptr: eptr2.main.EPTR2 | None = None)",
154
+ "signature": "(start_date: str, end_date: str, eptr: eptr2.main.EPTR2 | None = None, **kwargs)",
150
155
  "summary": "Get reference imbalance cost for a given period. Reference imbalance cost means the average of positive imbalance and negative imbalance costs. Imbalance costs are calculated as the difference from PTF/MCP, always positive values."
151
156
  },
152
157
  "get_rt_gen_bulk_range": {
@@ -208,12 +213,12 @@
208
213
  },
209
214
  "calculate_imbalance_costs": {
210
215
  "module": "eptr2.util.costs",
211
- "signature": "(data=None, actual: float | None = None, forecast: float | None = None, date=None, category: str = 'other', is_producer: bool = True, prices=None, eptr=None, include_maintenance_penalty: bool = False, return_df: bool = True, **kwargs)",
216
+ "signature": "(data: 'pd.DataFrame | list[dict] | None' = None, actual: float | None = None, forecast: float | None = None, date: str | datetime.datetime | None = None, category: str = 'other', is_producer: bool = True, prices: 'pd.DataFrame | list[dict] | None' = None, eptr: 'EPTR2 | None' = None, include_maintenance_penalty: bool = False, return_df: bool = True, **kwargs: float) -> 'pd.DataFrame | list[dict]'",
212
217
  "summary": "Imbalance and KUPST costs of actual vs forecast quantities, with every"
213
218
  },
214
219
  "calculate_imbalance_prices": {
215
220
  "module": "eptr2.util.costs",
216
- "signature": "(start_date=None, end_date=None, prices=None, eptr=None, kupst_category: str = 'other', include_maintenance_penalty: bool = False, return_df: bool = True, include_calculated: bool = False, **kwargs)",
221
+ "signature": "(start_date: str | datetime.datetime | None = None, end_date: str | datetime.datetime | None = None, prices: 'pd.DataFrame | list[dict] | None' = None, eptr: 'EPTR2 | None' = None, kupst_category: str = 'other', include_maintenance_penalty: bool = False, return_df: bool = True, include_calculated: bool = False, **kwargs: float) -> 'pd.DataFrame | list[dict]'",
217
222
  "summary": "Hourly imbalance prices, unit costs and every regulation parameter used to"
218
223
  },
219
224
  "calculate_kupst_cost": {
@@ -1437,8 +1442,8 @@
1437
1442
  "call_path": "electricity-service/v1/markets/idm/data/matching-quantity",
1438
1443
  "category": "GİP",
1439
1444
  "desc": {
1440
- "en": "It is the total matching quantity in the intraday market which is categorized as hourly or block depending on the contract type.",
1441
- "tr": "Gün İçi Piyasası’nda kontrat türüne göre saatlik veya blok olarak gösterilen toplam eşleşme miktarıdır."
1445
+ "en": "It is the total matching quantity in the intraday market which is categorized as hourly or block depending on the contract type. EPİAŞ returns purchases as clearingQuantityAsk and sales as clearingQuantityBid; the eptr2 DataFrame corrects them: clearingQuantityBid = bought, clearingQuantityAsk = sold (the raw response with postprocess=False is unchanged).",
1446
+ "tr": "Gün İçi Piyasası’nda kontrat türüne göre saatlik veya blok olarak gösterilen toplam eşleşme miktarıdır. EPİAŞ alışı clearingQuantityAsk, satışı clearingQuantityBid olarak döndürür; eptr2 DataFrame'inde bunlar düzeltilmiştir: clearingQuantityBid = alış, clearingQuantityAsk = satış (postprocess=False ham yanıtı değiştirmez)."
1442
1447
  },
1443
1448
  "optional_params": [
1444
1449
  "org_id"
@@ -4780,7 +4785,7 @@
4780
4785
  "url": "https://seffaflik.epias.com.tr/electricity/electricity-transmission/zero-balance-adjustment/monthly-zero-balance-adjustment"
4781
4786
  }
4782
4787
  },
4783
- "eptr2_version": "1.4.0",
4788
+ "eptr2_version": "1.4.1.dev0",
4784
4789
  "schema_format_version": "2.0",
4785
4790
  "usage": {
4786
4791
  "cli": "eptr2 call <key> --start-date ... --end-date ...",
@@ -12,7 +12,7 @@ The installed catalog is the authoritative list; use `eptr2 categories` and `ept
12
12
  | Actual generation | `rt-gen`, `rt-gen-bulk` |
13
13
  | Generation plans | `kgup`, `kgup-v1`, `kudup`, `dpp-bulk` |
14
14
  | Settlement generation | `uevm` |
15
- | Market volumes | `dam-clearing`, `idm-qty`, `bi-long`, `bi-short` |
15
+ | Market volumes | `dam-clearing`, `idm-qty` (raw bid/ask swapped by EPİAŞ, corrected in the DataFrame from 1.4.1), `bi-long`, `bi-short` |
16
16
  | Natural gas | Search `gas`; inspect the matching `ng-*` calls |
17
17
 
18
18
  ## IDs are endpoint-specific
@@ -32,6 +32,8 @@ print(prices.head())
32
32
 
33
33
  `get_kgup` requires the `region` argument even though the generic call can default it. Inspect each wrapper's signature for these differences. Examples of real names include `get_wap`, `get_imb_vol`, `get_imb_qty`, and `get_kgup`; do not invent `get_idm_wap`, `get_imbalance_volume`, or `get_dpp`.
34
34
 
35
+ Trap: `get_idm_qty` (GİP matching quantity, `idm-qty`). EPİAŞ's raw response has bid/ask swapped (`clearingQuantityAsk` = bought, `clearingQuantityBid` = sold). From eptr2 1.4.1 the DataFrame corrects them (`clearingQuantityBid` = bought, `clearingQuantityAsk` = sold); `postprocess=False` and eptr2 1.4.0 or earlier keep the swapped labels. For per-organization positions prefer `eptr2.composite.get_dabi_idm_data`, whose `idm_long` / `idm_short` are unambiguous.
36
+
35
37
  Most tabular endpoints return pandas DataFrames when pandas is installed. Some calls return dictionaries, lists, or scalars; `postprocess=False` preserves the decoded response envelope. Omitting `eptr` constructs a client and authenticates, so discovery should use imports/signatures rather than executing a wrapper.
36
38
 
37
39
  For composite analysis, import from `eptr2.composite` and pass the client as `eptr=...` after the date arguments. The available Python, shell, or MCP facility is a runtime choice; these examples do not depend on a specific agent vendor.
@@ -35,10 +35,15 @@ For organization-specific analyses, resolve the organization and pass its ID onl
35
35
  `da_long`/`da_short` (GÖP purchases/sales), `bi_long`/`bi_short` (bilateral), `idm_long`/`idm_short` (GİP), the nets
36
36
  `dabi_net`, `idm_net`, `dabi_idm_net` (**long minus short = net purchases**) and `net_sales` (positive = net seller).
37
37
 
38
- **EPİAŞ swaps bid/ask on the per-organization GİP endpoint:** in `idm-qty` with `org_id`, `clearingQuantityAsk` is what the
39
- organization BOUGHT and `clearingQuantityBid` what it SOLD. The composite maps this; raw `idm-qty` users must too.
38
+ **Trap: EPİAŞ swaps bid/ask on the GİP matching quantity endpoint.** The raw `idm-qty` response labels the
39
+ organization's purchases (Alış) `clearingQuantityAsk` and its sales (Satış) `clearingQuantityBid`, the opposite of the
40
+ platform page. From eptr2 1.4.1 the `idm-qty` DataFrame (`eptr.call("idm-qty", ...)`, `get_idm_qty`) corrects them:
41
+ `clearingQuantityBid` = bought, `clearingQuantityAsk` = sold. `postprocess=False` returns the raw, still swapped response,
42
+ and eptr2 1.4.0 and earlier return the swapped labels in the DataFrame too; check `eptr2.__version__` before reusing
43
+ older code or data. `get_dabi_idm_data` (`idm_long` / `idm_short`) is correct in every version. Check against the
44
+ platform's "GİP Eşleşme Miktarı" page (Eşleşen Alış / Satış Miktarı) when in doubt.
40
45
  `dam-clearing` per organization is not swapped (`matchedBids` = purchases, `matchedOffers` = sales).
41
46
 
42
- For an organization's estimated trading activity, use `eptr2.composite.get_org_estimated_activity(start_date, end_date, org_id=..., eptr=eptr)`: per hourly contract it splits day-ahead (GÖP + İA) open / intraday close (`dabi_idm_close`), intraday day trade (`min(idm_long, idm_short)`), the day-ahead (GÖP + İA) net position `dabi_net` and the total net `dabi_idm_net` to be consumed (+) or generated (−), using only the organization's GÖP, İA and GİP matchings (fast). `include_pnl=True` adds a fictitious PnL of day-ahead open / intraday close trades (`dabi_idm_pnl`) from MCP and the published WAP. `include_tad=True` adds the TAD (total absolute deviation: quantity-weighted mean of |price − WAP|) of each contract from the market-wide `idm-log` and `day_trade_tad = day_trade × TAD`; these are volatility metrics, not PnL, and need no `include_pnl`. The log is much slower (roughly 30–70 s per week, depending on EPİAŞ). `verbose=True` shows progress. `export_to_csv=True` writes the raw data (positions, MCP, WAP, trade log, per-contract WAP/TAD) and the result to `export_dir`; `check_existing=True` reads files of the same period instead of fetching, so the market-wide data is recycled across organizations. `end_date` must be before today (Europe/Istanbul), otherwise it raises `ValueError`. `idm-log` quantities are lots of 0.1 MWh. The PnL is an estimate, not the organization's realized result: its own trade prices are not public.
47
+ For an organization's estimated trading activity, use `eptr2.composite.get_org_estimated_activity(start_date, end_date, org_id=..., eptr=eptr)`: per hourly contract it splits day-ahead (GÖP + İA) open / intraday close (`dabi_idm_close`), intraday day trade (`min(idm_long, idm_short)`), the day-ahead (GÖP + İA) net position `dabi_net` and the total net `dabi_idm_net` to be consumed (+) or generated (−), using only the organization's GÖP, İA and GİP matchings (fast). `include_pnl=True` adds a fictitious PnL of day-ahead open / intraday close trades (`dabi_idm_pnl`) from MCP and the published WAP. `include_tad=True` adds the MAD (`idm_mad`, mean absolute deviation in TL/MWh: quantity-weighted mean of |price − WAP|) of each contract from the market-wide `idm-log` and `day_trade_tad = day_trade × idm_mad`, the TAD (total absolute deviation, TL) of the day-trade volume; these are volatility metrics, not PnL, and need no `include_pnl`. The log is much slower (roughly 30–70 s per week, depending on EPİAŞ). `verbose=True` shows progress. By default (`export_to_csv=True`, `check_existing=True`) it writes the raw data (positions, MCP, WAP, trade log, per-contract WAP/MAD) and the result as CSV to `export_dir` (`"data"`) and reads files of the same period instead of fetching; pass `export_to_csv=False` to write nothing, so the market-wide data is recycled across organizations. `end_date` must be before today (Europe/Istanbul), otherwise it raises `ValueError`. For market-wide price dispersion per contract use `eptr2.composite.get_idm_contract_stats(start_date, end_date, eptr=eptr)`: `idm_wap`, `idm_mad` (MAD, TL/MWh), `idm_tad` (TAD, TL = `idm_mad × idm_volume_mwh`), trade count and volume. It writes the trade log and the statistics to CSV in `export_dir` and reads them back before fetching (both on by default); `get_org_estimated_activity` shares these files. `idm-log` quantities are lots of 0.1 MWh. The PnL is an estimate, not the organization's realized result: its own trade prices are not public.
43
48
 
44
49
  Read [examples.md](examples.md) for discovery and a bounded raw-response query.
@@ -110,10 +110,10 @@ def get_idm_qty(start_date: str, end_date: str, org_id: str | int | None = None,
110
110
  Category: GİP
111
111
 
112
112
  EN (IDM Matching Quantity):
113
- It is the total matching quantity in the intraday market which is categorized as hourly or block depending on the contract type.
113
+ It is the total matching quantity in the intraday market which is categorized as hourly or block depending on the contract type. EPİAŞ returns purchases as clearingQuantityAsk and sales as clearingQuantityBid; the eptr2 DataFrame corrects them: clearingQuantityBid = bought, clearingQuantityAsk = sold (the raw response with postprocess=False is unchanged).
114
114
 
115
115
  TR (GİP Eşleşme Miktarı):
116
- Gün İçi Piyasası’nda kontrat türüne göre saatlik veya blok olarak gösterilen toplam eşleşme miktarıdır.
116
+ Gün İçi Piyasası’nda kontrat türüne göre saatlik veya blok olarak gösterilen toplam eşleşme miktarıdır. EPİAŞ alışı clearingQuantityAsk, satışı clearingQuantityBid olarak döndürür; eptr2 DataFrame'inde bunlar düzeltilmiştir: clearingQuantityBid = alış, clearingQuantityAsk = satış (postprocess=False ham yanıtı değiştirmez).
117
117
 
118
118
  Reference: https://seffaflik.epias.com.tr/electricity/electricity-markets/intraday-market-idm/idm-matching-quantity
119
119
  """
@@ -18,11 +18,11 @@ def process_idm_data(
18
18
  """
19
19
  Fetch one organisation's intraday (GİP / IDM) matched quantities per contract (call key ``idm-qty`` with ``org_id``).
20
20
 
21
- EPİAŞ's column names are swapped on this endpoint: ``clearingQuantityAsk`` is the quantity the organisation BOUGHT and
22
- ``clearingQuantityBid`` the quantity it SOLD. The returned frame uses unambiguous names instead:
21
+ EPİAŞ returns this endpoint's columns swapped (``clearingQuantityAsk`` = bought, ``clearingQuantityBid`` = sold);
22
+ the ``idm-qty`` postprocessing corrects them. The returned frame uses unambiguous names instead:
23
23
 
24
- - ``idm_long``: GİP purchases (MWh), from ``clearingQuantityAsk``
25
- - ``idm_short``: GİP sales (MWh), from ``clearingQuantityBid``
24
+ - ``idm_long``: GİP purchases (MWh), from the corrected ``clearingQuantityBid``
25
+ - ``idm_short``: GİP sales (MWh), from the corrected ``clearingQuantityAsk``
26
26
 
27
27
  The day before ``start_date`` is fetched too, because the contracts of ``start_date`` start trading at 18:00 the
28
28
  previous day.
@@ -44,8 +44,7 @@ def process_idm_data(
44
44
  **retry_kwargs,
45
45
  )
46
46
 
47
- ### Due to naming confusion by EPIAS, ask is mapped to buy and bid is mapped to sell.
48
- ### (checked on behaviour too: solar-only organisations have "Ask" quantities at night, when they cannot sell)
47
+ ### idm-qty postprocessing already corrects EPİAŞ's swapped labels: Bid = bought, Ask = sold
49
48
 
50
49
  if df.empty:
51
50
  df = pd.DataFrame(columns=["contract", "idm_long", "idm_short"])
@@ -55,8 +54,8 @@ def process_idm_data(
55
54
  .rename(
56
55
  {
57
56
  "kontratAdi": "contract",
58
- "clearingQuantityAsk": "idm_long",
59
- "clearingQuantityBid": "idm_short",
57
+ "clearingQuantityBid": "idm_long",
58
+ "clearingQuantityAsk": "idm_short",
60
59
  },
61
60
  axis=1,
62
61
  )
@@ -87,8 +86,8 @@ def get_day_ahead_and_bilateral_matches(
87
86
 
88
87
  - ``da_long`` / ``da_short``: GÖP purchases / sales (``matchedBids`` / ``matchedOffers`` of ``dam-clearing``)
89
88
  - ``bi_long`` / ``bi_short``: bilateral purchases / sales (``bi-long`` / ``bi-short``)
90
- - ``idm_long`` / ``idm_short``: GİP purchases / sales (``idm-qty``; EPİAŞ's ask/bid names are swapped there, see
91
- :func:`process_idm_data`), only with ``include_idm_data=True``
89
+ - ``idm_long`` / ``idm_short``: GİP purchases / sales (``idm-qty``; EPİAŞ's ask/bid names are swapped there and
90
+ corrected by eptr2, see :func:`process_idm_data`), only with ``include_idm_data=True``
92
91
  - ``dabi_net`` = ``da_long - da_short + bi_long - bi_short``; ``idm_net`` = ``idm_long - idm_short``;
93
92
  ``dabi_idm_net`` = ``dabi_net + idm_net``. All nets are LONG minus SHORT, i.e. **net purchases**.
94
93
  - ``net_sales``: the opposite sign, **net sales** (positive = net seller), of ``dabi_idm_net`` when IDM data is
@@ -0,0 +1,278 @@
1
+ from eptr2.main import DEFAULT_COMPOSITE_TIMEOUT_LONG
2
+ from eptr2 import EPTR2
3
+ import pandas as pd
4
+ from datetime import datetime, timedelta
5
+ import logging
6
+ import time
7
+ import os
8
+ from typing import Any
9
+ from eptr2.util.time import get_hourly_contract_range_list, get_today_utc3
10
+
11
+
12
+ logger = logging.getLogger(__name__)
13
+
14
+ ## idm-log quantities are in lots. 1 lot = 0.1 MWh: for every hourly contract
15
+ ## sum(price * quantity) / 10 equals the idm-volume tradingVolume, and the
16
+ ## log-derived WAP equals the wap endpoint to the cent.
17
+ IDM_LOT_MWH = 0.1
18
+
19
+ IDM_CONTRACT_STATS_COLUMNS = [
20
+ "contract",
21
+ "idm_wap",
22
+ "idm_mad",
23
+ "idm_tad",
24
+ "idm_trade_count",
25
+ "idm_volume_mwh",
26
+ ]
27
+
28
+
29
+ def idm_log_longer(
30
+ start_date: str,
31
+ end_date: str,
32
+ eptr: EPTR2 | None = None,
33
+ contract_wise: bool = True,
34
+ verbose: bool = False,
35
+ trials: int = 3,
36
+ cooldown: int = 15,
37
+ days_interval: int = 6,
38
+ **kwargs,
39
+ ) -> pd.DataFrame:
40
+ """
41
+ This function gets the IDM log data for a longer period.
42
+
43
+ If contract_wise is True, start_date is taken from a day earlier to get the previous day's transactions of the start_date's contracts. For instance if start_date is 2025-05-15, trading for PH25051500 starts at 2025-05-14 18:00:00. Therefore, the start_date is set to 2025-05-14. The end_date is not changed as contract closing times are before the contract times.
44
+ """
45
+
46
+ if eptr is None:
47
+ eptr = EPTR2(dotenv_path=kwargs.get("dotenv_path", ".env"))
48
+
49
+ start_dt = datetime.strptime(start_date, "%Y-%m-%d")
50
+ if contract_wise:
51
+ ## Get conract range list
52
+ c_l = get_hourly_contract_range_list(start_date=start_date, end_date=end_date)
53
+ start_dt = start_dt - timedelta(days=1)
54
+ start_date = start_dt.strftime("%Y-%m-%d")
55
+
56
+ end_dt = datetime.strptime(end_date, "%Y-%m-%d")
57
+
58
+ ## Make a sanity check and show a friendly warning
59
+ whole_interval = (end_dt - start_dt).days
60
+ if whole_interval > 32:
61
+ logger.warning(
62
+ "Friendly warning: Your time interval might be a bit long. You might lose all data if the API fails. We recommmend monthly aggregate calls in order to have proper checkpoints."
63
+ )
64
+
65
+ period_start_dt = start_dt
66
+ period_end_dt = min(period_start_dt + timedelta(days=days_interval), end_dt)
67
+
68
+ main_df = pd.DataFrame()
69
+ while period_start_dt <= end_dt:
70
+ period_start_date = period_start_dt.strftime("%Y-%m-%d")
71
+ period_end_date = period_end_dt.strftime("%Y-%m-%d")
72
+ if verbose:
73
+ logger.info(
74
+ "Getting IDM log data for %s to %s",
75
+ period_start_date,
76
+ period_end_date,
77
+ )
78
+ chunk_start = time.time()
79
+
80
+ try:
81
+ df = eptr.call(
82
+ "idm-log",
83
+ start_date=period_start_date,
84
+ end_date=period_end_date,
85
+ ## The intraday log returns every order for the period, so it
86
+ ## needs a longer budget than an ordinary composite request.
87
+ request_kwargs={
88
+ "timeout": kwargs.get("timeout", DEFAULT_COMPOSITE_TIMEOUT_LONG)
89
+ },
90
+ retry_attempts=trials,
91
+ retry_backoff=cooldown,
92
+ retry_backoff_max=cooldown,
93
+ retry_jitter=0.0,
94
+ )
95
+ except Exception as e:
96
+ logger.warning(
97
+ f"Error getting IDM log data for {period_start_date} to {period_end_date}"
98
+ )
99
+ logger.warning("%s", e)
100
+ break
101
+
102
+ if verbose:
103
+ logger.info(
104
+ " %d trades in %.1f s", len(df), time.time() - chunk_start
105
+ )
106
+
107
+ main_df = pd.concat([main_df, df], ignore_index=True)
108
+
109
+ period_start_dt = period_end_dt + timedelta(days=1)
110
+ period_end_dt = min(period_start_dt + timedelta(days=days_interval), end_dt)
111
+
112
+ if contract_wise:
113
+ c_df = pd.DataFrame(data={"contractName": c_l})
114
+ main_df = main_df.merge(c_df, on="contractName", how="inner")
115
+
116
+ main_df = main_df.sort_values(by=["contractName", "date", "id"]).reset_index(
117
+ drop=True
118
+ )
119
+ return main_df
120
+
121
+
122
+ def idm_log_period(period: str, eptr: EPTR2 | None = None, **kwargs):
123
+ """
124
+ This function is a wrapper for the IDM log data for a specific monthly period (e.g. 2025-05-01).
125
+ """
126
+
127
+ if eptr is None:
128
+ eptr = EPTR2(dotenv_path=kwargs.get("dotenv_path", ".env"))
129
+
130
+ ## Check if the period is a valid date
131
+ try:
132
+ period_dt = datetime.strptime(period, "%Y-%m-%d")
133
+ except ValueError:
134
+ raise ValueError("Invalid date format. Please use YYYY-MM-DD.")
135
+
136
+ ## Start of month
137
+ start_dt = period_dt.replace(day=1)
138
+ ## End of month
139
+ end_dt = (start_dt + timedelta(days=31)).replace(day=1) - timedelta(days=1)
140
+ start_date = start_dt.strftime("%Y-%m-%d")
141
+ end_date = end_dt.strftime("%Y-%m-%d")
142
+ return idm_log_longer(
143
+ start_date=start_date,
144
+ end_date=end_date,
145
+ eptr=eptr,
146
+ **kwargs,
147
+ )
148
+
149
+
150
+ def calculate_idm_contract_stats(log_df: pd.DataFrame) -> pd.DataFrame:
151
+ """
152
+ Calculates per contract intraday statistics from the IDM trade log (idm-log or idm_log_longer output).
153
+
154
+ Returns a DataFrame with columns:
155
+ contract: Hourly contract name (PHyyMMddhh)
156
+ idm_wap: Weighted average price of all trades in the contract
157
+ idm_mad: MAD (mean absolute deviation, TL/MWh), a volatility metric. Quantity weighted average of |price - idm_wap| over all trades in the contract
158
+ idm_tad: TAD (total absolute deviation, TL) of the contract: sum of |price - idm_wap| * quantity over all trades, i.e. idm_mad * idm_volume_mwh
159
+ idm_trade_count: Number of trades
160
+ idm_volume_mwh: Total traded quantity in MWh (log quantities are lots of 0.1 MWh)
161
+
162
+ Only hourly (PH) contracts are taken into account.
163
+ """
164
+ cols = IDM_CONTRACT_STATS_COLUMNS
165
+ if log_df is None or log_df.empty:
166
+ return pd.DataFrame(columns=cols)
167
+
168
+ df = log_df.loc[
169
+ log_df["contractName"].str.startswith("PH"),
170
+ ["contractName", "price", "quantity"],
171
+ ].rename({"contractName": "contract"}, axis=1)
172
+
173
+ df["pq"] = df["price"] * df["quantity"]
174
+ wap_df = df.groupby("contract", as_index=False).agg(
175
+ pq=("pq", "sum"), q=("quantity", "sum"), idm_trade_count=("price", "size")
176
+ )
177
+ wap_df["idm_wap"] = wap_df["pq"] / wap_df["q"]
178
+
179
+ df = df.merge(wap_df[["contract", "idm_wap"]], on="contract", how="left")
180
+ df["abs_dev_q"] = (df["price"] - df["idm_wap"]).abs() * df["quantity"]
181
+ abs_dev_df = df.groupby("contract", as_index=False)["abs_dev_q"].sum()
182
+
183
+ stats_df = wap_df.merge(abs_dev_df, on="contract", how="left")
184
+ stats_df["idm_mad"] = stats_df["abs_dev_q"] / stats_df["q"]
185
+ stats_df["idm_tad"] = stats_df["abs_dev_q"] * IDM_LOT_MWH
186
+ stats_df["idm_volume_mwh"] = stats_df["q"] * IDM_LOT_MWH
187
+
188
+ return stats_df[cols].sort_values("contract").reset_index(drop=True)
189
+
190
+
191
+ def get_idm_contract_stats(
192
+ start_date: str,
193
+ end_date: str,
194
+ eptr: EPTR2 | None = None,
195
+ idm_log_df: pd.DataFrame | None = None,
196
+ export_to_csv: bool = True,
197
+ export_dir: str = "data",
198
+ check_existing: bool = True,
199
+ verbose: bool = False,
200
+ **kwargs: Any,
201
+ ) -> pd.DataFrame:
202
+ """
203
+ Market wide intraday (GİP) statistics per hourly contract for the given period (start_date and end_date inclusive), from the IDM trade log: idm_wap, idm_mad (MAD, mean absolute deviation, TL/MWh), idm_tad (TAD, total absolute deviation, TL), idm_trade_count and idm_volume_mwh. See calculate_idm_contract_stats.
204
+
205
+ The trade log is large (about 20k trades a day) and slow to fetch (roughly 30-70 s per week, depending on EPİAŞ), so by default the results are kept in files: idm_log_{start_date}_{end_date}.csv (the log, idm_log_longer output) and idm_contract_stats_{start_date}_{end_date}.csv in export_dir. With check_existing=True (default) the statistics file is read if it exists, otherwise the log file, and only then is the log fetched. get_org_estimated_activity uses the same files.
206
+
207
+ end_date must be before today (Europe/Istanbul): the log of the current day is not final, so neither are the statistics or the files.
208
+
209
+ Args:
210
+ start_date: Start date in 'YYYY-MM-DD' format
211
+ end_date: End date in 'YYYY-MM-DD' format (inclusive), before today
212
+ eptr: EPTR2 object. Created from .env if needed.
213
+ idm_log_df: Previously fetched trade log covering the period (idm_log_longer output). Used instead of the files and the API.
214
+ export_to_csv: Write the log and the statistics to export_dir (files that were read are not written again).
215
+ export_dir: Directory of the CSV files, created if missing.
216
+ check_existing: Read existing files of the same period before fetching.
217
+ verbose: Log each step.
218
+ **kwargs: Passed to idm_log_longer (e.g. days_interval, timeout).
219
+
220
+ Returns:
221
+ pd.DataFrame: One row per hourly contract with the columns above.
222
+ """
223
+ today = get_today_utc3()
224
+ if end_date >= today:
225
+ raise ValueError(
226
+ f"end_date must be before today ({today}, Europe/Istanbul): the trade log of the current day is not final. Got end_date={end_date}."
227
+ )
228
+
229
+ def csv_path(name):
230
+ return os.path.join(export_dir, f"{name}_{start_date}_{end_date}.csv")
231
+
232
+ stats_path, log_path = csv_path("idm_contract_stats"), csv_path("idm_log")
233
+
234
+ if idm_log_df is None and check_existing and os.path.exists(stats_path):
235
+ stats_df = pd.read_csv(stats_path, dtype={"contract": str})
236
+ if all(c in stats_df.columns for c in IDM_CONTRACT_STATS_COLUMNS):
237
+ if verbose:
238
+ logger.info("Read IDM contract statistics from %s", stats_path)
239
+ return stats_df[IDM_CONTRACT_STATS_COLUMNS]
240
+ ## e.g. files of eptr2 1.4.0, whose idm_tad column was the MAD
241
+ logger.warning(
242
+ "%s does not have the current columns, recalculating it.", stats_path
243
+ )
244
+
245
+ log_loaded = False
246
+ if idm_log_df is None and check_existing and os.path.exists(log_path):
247
+ if verbose:
248
+ logger.info("Reading the IDM trade log from %s", log_path)
249
+ idm_log_df = pd.read_csv(log_path, dtype={"contractName": str})
250
+ log_loaded = True
251
+
252
+ if idm_log_df is None:
253
+ if verbose:
254
+ logger.info(
255
+ "Getting the IDM trade log for %s to %s (market wide, about 20k trades a day)...",
256
+ start_date,
257
+ end_date,
258
+ )
259
+ idm_log_df = idm_log_longer(
260
+ start_date=start_date,
261
+ end_date=end_date,
262
+ eptr=eptr,
263
+ contract_wise=True,
264
+ verbose=verbose,
265
+ **kwargs,
266
+ )
267
+
268
+ stats_df = calculate_idm_contract_stats(idm_log_df)
269
+
270
+ if export_to_csv:
271
+ os.makedirs(export_dir, exist_ok=True)
272
+ if not log_loaded:
273
+ idm_log_df.to_csv(log_path, index=False)
274
+ stats_df.to_csv(stats_path, index=False)
275
+ if verbose:
276
+ logger.info("Wrote %s and %s", log_path, stats_path)
277
+
278
+ return stats_df