Regional Trade Balance Calculator¶
RegionalTradeBalanceCalculator
¶
Aggregates bidirectional power flows between regions based on node-level flow data.
Takes line-level flow data with bidirectional flows (up/down) and losses, and aggregates them to a higher regional level (e.g., countries, market areas) or keeps them at node level. Uses networkx for identifying region/node connections and handles multiple lines between the same region/node pairs.
Loss modes (argument losses of get_trade_balance):
'at_own_end'(default): each region counts the flow at its own end of the lines. It exports the sent flow and imports the received flow, so the losses are inside the trade balance.net_exp(A, B) + net_exp(B, A)equals the losses on the border.'excluded': both regions use the sent flows, so the losses are not in the trade balance.net_exp(A, B) = -net_exp(B, A).
When agg_region_column is None, each node is treated as its own region, allowing for node-to-node trade balance analysis without aggregation.
Raises:
| Type | Description |
|---|---|
KeyError
|
A line end node ( |
Examples:
>>> from mesqual.energy_data_handling import NetworkLineFlowsData
>>> flows = NetworkLineFlowsData.from_net_flow_without_losses(dataset.fetch('Line.Results.flow_sent_net'))
>>> calculator = RegionalTradeBalanceCalculator(dataset.fetch('Line.Model'), dataset.fetch('Node.Model'), 'country')
>>> calculator.get_trade_balance(flows).xs('net_exp', axis=1, level=-1).sort_index(axis=1).iloc[:2].round(1)
primary_country C1 C2
partner_country C2 C1
time
2024-03-28 00:00:00+01:00 -345.7 345.7
2024-03-28 01:00:00+01:00 -547.8 547.8
Source code in src/mesqual/energy_data_handling/variable_utils/regional_trade_balance_calculator.py
18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 | |
get_trade_balance
¶
get_trade_balance(flow_data: NetworkLineFlowsData, losses: LossMode = 'at_own_end') -> DataFrame
Computes the trade balance of each region with each neighbouring region.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
flow_data
|
NetworkLineFlowsData
|
Line flows with sent and received values per direction. |
required |
losses
|
LossMode
|
How line losses enter the trade balance: |
'at_own_end'
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
DataFrame with three column levels: primary region, partner region and variable
( |
Raises:
| Type | Description |
|---|---|
ValueError
|
If |
Source code in src/mesqual/energy_data_handling/variable_utils/regional_trade_balance_calculator.py
158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 | |
aggregate_trade_balance_to_primary_level
¶
aggregate_trade_balance_to_primary_level(trade_balance_df: DataFrame) -> DataFrame
Reduces three-level trade balance DataFrame to primary region and variable only.
Source code in src/mesqual/energy_data_handling/variable_utils/regional_trade_balance_calculator.py
197 198 199 200 201 202 203 204 | |
trade_balance_frame
¶
trade_balance_frame(net_exports: Mapping[tuple, Series], primary_name: str, partner_name: str, index: Index | None = None) -> DataFrame
Build the trade balance frame from the net export of each area to each partner.
For each (primary, partner) pair, the frame has the variables
net_exp, exp = max(net_exp, 0), imp = max(-net_exp, 0) and
total = exp + imp. exp and imp come from the net value of each
time step, not from gross flows.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
net_exports
|
Mapping[tuple, Series]
|
Net export per |
required |
primary_name
|
str
|
Name of the first column level. |
required |
partner_name
|
str
|
Name of the second column level. |
required |
index
|
Index | None
|
Index of the result if |
None
|
Returns:
| Type | Description |
|---|---|
DataFrame
|
A frame with the column levels |
Examples:
>>> net = pd.Series([100.0, -40.0])
>>> trade_balance_frame({('C1', 'C2'): net, ('C2', 'C1'): -net}, 'country', 'partner_country')
country C1 C2
partner_country C2 C1
variable net_exp exp imp total net_exp exp imp total
0 100.0 100.0 0.0 100.0 -100.0 0.0 100.0 100.0
1 -40.0 0.0 40.0 40.0 40.0 40.0 0.0 40.0
Source code in src/mesqual/energy_data_handling/variable_utils/trade_balance_frame.py
14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 | |