eptr2 1.4.0__tar.gz → 1.4.1.dev1__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.
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/PKG-INFO +1 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/pyproject.toml +1 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/eptr2_api_schema.json +13 -8
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md +1 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md +2 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/SKILL.md +2 -2
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/SKILL.md +8 -3
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/idm.py +2 -2
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/dabi_idm.py +9 -10
- eptr2-1.4.1.dev1/src/eptr2/composite/idm_log.py +278 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/org_activity.py +55 -117
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/periodic_orgs.py +14 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/plant_costs.py +32 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/price_and_cost.py +13 -6
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/main.py +20 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/help.py +2 -2
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/processing.py +4 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/server.py +3 -1
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/items.py +12 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/util/costs.py +310 -104
- eptr2-1.4.0/src/eptr2/composite/idm_log.py +0 -131
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/LICENSE +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/docs/assets/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/examples/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/pyproject.toml +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/src/eptr2/mcp/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.claude/worktrees/wonderful-knuth-6c1f12/tutorials/pyproject.toml +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/.gitignore +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/LICENSE +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/docs/assets/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/examples/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/__main__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/discovery.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/schema.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/skills.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/agentic/validation.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/mcp.json +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/plugin.json +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/SKILL.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/scripts/list_endpoints.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/SKILL.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-consumption-data/examples.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/SKILL.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-generation-tracking/examples.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/examples.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-imbalance-costs/formulas.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-market-operations/examples.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/SKILL.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/api-reference.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-price-analysis/examples.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ancillary.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bilateral.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/bpm.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/consumption.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dam.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/dams.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/general.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/generation.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/imbalance.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/mms.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_general.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_sgp.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_transmission.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/ng_vgp.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/renewables.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/reporting.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/retroactive.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/transmission.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/vep.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/calls/yek_g.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/cli.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ancillary.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/bpm.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/consumption.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/ids.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/mms.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/composite/production.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/checks.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/parameters.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mapping/path.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/README.md +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/mcp/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/postprocess/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/calls.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/processing/preprocess/params.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/util/__init__.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/util/certificate.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/util/evaluation.py +0 -0
- {eptr2-1.4.0 → eptr2-1.4.1.dev1}/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.
|
|
3
|
+
Version: 1.4.1.dev1
|
|
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.
|
|
3
|
+
version = "1.4.1.dev1"
|
|
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.
|
|
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 =
|
|
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.
|
|
4788
|
+
"eptr2_version": "1.4.1.dev1",
|
|
4784
4789
|
"schema_format_version": "2.0",
|
|
4785
4790
|
"usage": {
|
|
4786
4791
|
"cli": "eptr2 call <key> --start-date ... --end-date ...",
|
{eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-api-discovery/endpoint-categories.md
RENAMED
|
@@ -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
|
|
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
|
{eptr2-1.4.0 → eptr2-1.4.1.dev1}/src/eptr2/assets/skills/eptr2-convenience-wrappers/SKILL.md
RENAMED
|
@@ -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.
|
|
@@ -5,7 +5,7 @@ description: Calculate Turkish electricity imbalance and KÜPST deviation costs
|
|
|
5
5
|
|
|
6
6
|
# Imbalance and KÜPST costs
|
|
7
7
|
|
|
8
|
-
Use contract-aware utilities for historical analysis. The library distinguishes regulation periods (`pre_2026`, `26_01` from 2026-01-01, `26_02` from 2026-11-01); do not apply a timeless 3% margin or one tolerance to a range crossing a rule boundary. Functions called without a contract use the newest parameters (`regulation_period="current"`); pass a contract or a period label to reproduce a specific period.
|
|
8
|
+
Use contract-aware utilities for historical analysis. The library distinguishes regulation periods (`pre_2026`, `26_01` from 2026-01-01, `26_02` from 2026-11-01, `27_01` from 2027-01-01); do not apply a timeless 3% margin or one tolerance to a range crossing a rule boundary. Functions called without a contract use the newest parameters (`regulation_period="current"`); pass a contract or a period label to reproduce a specific period.
|
|
9
9
|
|
|
10
10
|
```python
|
|
11
11
|
from eptr2.util.costs import calculate_unit_price_and_costs_by_contract
|
|
@@ -17,7 +17,7 @@ costs = calculate_unit_price_and_costs_by_contract(
|
|
|
17
17
|
print(costs)
|
|
18
18
|
```
|
|
19
19
|
|
|
20
|
-
For ranges or plant data, prefer the main functions: they resolve floor/ceiling, V, B, margins and KÜPST tolerance and multiplier (by category) for each hour, and fetch MCP, SMP and `systemStatus` when `prices` is not given. Where EPİAŞ's published imbalance prices are available (fetched rows, or `positiveImbalance` / `negativeImbalance` in `prices`) they are used, and `imb_price_source` says `published`; otherwise the prices are calculated. Hours without SMP (the rest of the current day, future hours) are skipped with a warning; pass `prices` with an SMP scenario to price them. KÜPST unit cost is always calculated. Pass `include_calculated=True` to also get the calculated prices for a check against the published ones.
|
|
20
|
+
For ranges or plant data, prefer the main functions: they resolve floor/ceiling, V, B, margins and KÜPST tolerance and multiplier (by category) for each hour, and fetch MCP, SMP and `systemStatus` when `prices` is not given. Where EPİAŞ's published imbalance prices are available (fetched rows, or `positiveImbalance` / `negativeImbalance` in `prices`) they are used, and `imb_price_source` says `published`; otherwise the prices are calculated. Hours without SMP (the rest of the current day, future hours) are skipped with a warning; pass `prices` with an SMP scenario to price them. KÜPST unit cost is always calculated. Storage categories differ: a plant with storage ("depolamalı üretim tesisi") is `plant_w_battery` (tolerance 0.05, multiplier 0.10), standalone storage is `battery`, and a plant with an integrated storage unit ("bütünleşik depolama ünitesi") uses its main source's tolerance, so pass its main source (e.g. `"Rüzgar"`); names like "RES+BESS" resolve to `plant_w_battery`. Hydro, geothermal and biomass are `other_renewable` (tolerance and multiplier of other sources, maintenance multiplier from 30 fault entries like wind and solar; other sources from 25). From 2027-01-01 consumption units pay KÜPST too: pass `is_producer=False` with category `consumption_art17` (tolerance 0.75) or `consumption_other` (0.30); before 2027 consumers have no KÜPST. Pass `include_calculated=True` to also get the calculated prices for a check against the published ones.
|
|
21
21
|
|
|
22
22
|
```python
|
|
23
23
|
from eptr2.util.costs import calculate_imbalance_costs
|
|
@@ -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
|
|
39
|
-
organization
|
|
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
|
|
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
|
|
22
|
-
``
|
|
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 ``
|
|
25
|
-
- ``idm_short``: GİP sales (MWh), from ``
|
|
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
|
-
###
|
|
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
|
-
"
|
|
59
|
-
"
|
|
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
|
|
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
|