ecotrack 0.1.0__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.
ecotrack-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 EcoTrack contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: ecotrack
3
+ Version: 0.1.0
4
+ Summary: A Python library for energy consumption analysis and cost estimation.
5
+ Author-email: Noa Aguayo <noa.aguayo@alumni.mondragon.edu>, Alejandro Diego <alejandro.diego@alumni.mondragon.edu>, Aroa Gutiérrez <aroa.gutierrez@alumni.mondragon.edu>
6
+ License: MIT
7
+ Keywords: energy,consumption,analysis,electricity,cost,solar panel,power
8
+ Classifier: Programming Language :: Python :: 3
9
+ Classifier: License :: OSI Approved :: MIT License
10
+ Classifier: Operating System :: OS Independent
11
+ Requires-Python: >=3.13
12
+ Description-Content-Type: text/markdown
13
+ License-File: LICENSE
14
+ Requires-Dist: pandas
15
+ Requires-Dist: numpy
16
+ Requires-Dist: matplotlib
17
+ Dynamic: license-file
18
+
19
+ # EcoTrack
20
+
21
+ **EcoTrack** is a Python library for analyzing electricity consumption, estimating electricity costs, and exploring potential savings through solar energy.
22
+
23
+ It allows users to load their own electricity consumption data from CSV files and perform energy and economic analyses.
24
+
25
+ ## Features
26
+
27
+ - Load and clean electricity consumption data from CSV files.
28
+ - Calculate total, average, maximum, and minimum consumption.
29
+ - Estimate electricity costs using fixed or time-of-use tariffs.
30
+ - Calculate daily and monthly electricity costs.
31
+ - Estimate potential savings.
32
+ - Detect consumption peaks and anomalies.
33
+ - Compare consumption between different periods.
34
+ - Generate solar energy production data.
35
+ - Simulate solar panel installations and estimate their economic benefits.
36
+ - Visualize consumption, costs, and solar energy results.
37
+ - Generate reports comparing different solar panel installations.
38
+
39
+ ## Installation
40
+
41
+ Install EcoTrack using pip:
42
+
43
+ ```bash
44
+ pip install ecotrack
45
+ ```
46
+
47
+ ## Quick start
48
+
49
+ Load a CSV file and analyze electricity consumption:
50
+
51
+ ```python
52
+ from ecotrack import EnergyAnalyzer
53
+
54
+ # Load your electricity consumption data
55
+ analyzer = EnergyAnalyzer("my_consumption.csv")
56
+
57
+ # Set your electricity price in EUR/kWh
58
+ analyzer.set_energy_price(0.21)
59
+
60
+ # Calculate total electricity cost
61
+ print(analyzer.calculate_cost())
62
+
63
+ # Detect consumption anomalies
64
+ print(analyzer.detect_anomalies())
65
+
66
+ # Plot electricity consumption
67
+ analyzer.plot_consumption()
68
+ ```
69
+
70
+ ## CSV file format
71
+
72
+ EcoTrack accepts CSV files containing timestamps and a supported electricity measurement column.
73
+
74
+ The default separator is a semicolon (`;`). You can specify another separator when loading the file.
75
+
76
+ Supported timestamp formats:
77
+
78
+ - A single `timestamp` column.
79
+ - Separate `Date` and `Time` columns, using the format `DD/MM/YYYY HH:MM:SS`.
80
+
81
+ Supported measurement columns:
82
+
83
+ | Column | Measurement | Unit |
84
+ |---|---|---|
85
+ | `consumption_kwh` | Energy | kWh |
86
+ | `consumo_kwh` | Energy | kWh |
87
+ | `consumption_wh` | Energy | Wh |
88
+ | `consumo_wh` | Energy | Wh |
89
+ | `global_active_power` | Power | kW |
90
+ | `power_kw` | Power | kW |
91
+ | `power_w` | Power | W |
92
+
93
+ For example:
94
+
95
+ ```csv
96
+ timestamp;consumption_kwh
97
+ 2026-01-01 00:00:00;0.35
98
+ 2026-01-01 01:00:00;0.42
99
+ 2026-01-01 02:00:00;0.31
100
+ ```
101
+
102
+ The file must contain at least two valid measurements with different timestamps.
103
+
104
+ ## Electricity tariffs
105
+
106
+ EcoTrack supports fixed electricity prices:
107
+
108
+ ```python
109
+ analyzer.set_energy_price(0.21)
110
+ ```
111
+
112
+ It also supports different prices depending on the time of day:
113
+
114
+ ```python
115
+ prices = {
116
+ "off_peak": 0.10,
117
+ "mid_peak": 0.16,
118
+ "peak": 0.25
119
+ }
120
+
121
+ hour_periods = {
122
+ "off_peak": [...],
123
+ "mid_peak": [...],
124
+ "peak": [...]
125
+ }
126
+
127
+ analyzer.set_energy_prices(prices, hour_periods)
128
+ ```
129
+
130
+ The hourly periods must assign a price to every hour of the day.
131
+
132
+ ## Solar energy simulation
133
+
134
+ EcoTrack can generate estimated solar production data and simulate the economic performance of solar panel installations.
135
+
136
+ ```python
137
+ # Generate estimated solar production data
138
+ analyzer.generate_solar_data(panel_power=300)
139
+
140
+ # Simulate an installation with 4 panels
141
+ results = analyzer.simulate_solar(panel_count=4)
142
+
143
+ print(results)
144
+
145
+ # Compare installations with different numbers of panels
146
+ scenarios = analyzer.compare_panel_counts(max_panels=7)
147
+
148
+ # Generate a report
149
+ analyzer.generate_report("solar_report.txt")
150
+ ```
151
+
152
+ A fixed electricity tariff must be configured before running the economic solar simulations.
153
+
154
+ **Note:** Solar production and financial results are estimates based on the available data and the assumptions of the simulation model. They should not be interpreted as guaranteed real-world performance.
155
+
156
+ ## Dependencies
157
+
158
+ EcoTrack uses:
159
+
160
+ - pandas
161
+ - NumPy
162
+ - Matplotlib
163
+
164
+ These dependencies are installed automatically when EcoTrack is installed using pip.
165
+
166
+ ## License
167
+
168
+ This project is licensed under the MIT License. See the `LICENSE` file for details.
@@ -0,0 +1,150 @@
1
+ # EcoTrack
2
+
3
+ **EcoTrack** is a Python library for analyzing electricity consumption, estimating electricity costs, and exploring potential savings through solar energy.
4
+
5
+ It allows users to load their own electricity consumption data from CSV files and perform energy and economic analyses.
6
+
7
+ ## Features
8
+
9
+ - Load and clean electricity consumption data from CSV files.
10
+ - Calculate total, average, maximum, and minimum consumption.
11
+ - Estimate electricity costs using fixed or time-of-use tariffs.
12
+ - Calculate daily and monthly electricity costs.
13
+ - Estimate potential savings.
14
+ - Detect consumption peaks and anomalies.
15
+ - Compare consumption between different periods.
16
+ - Generate solar energy production data.
17
+ - Simulate solar panel installations and estimate their economic benefits.
18
+ - Visualize consumption, costs, and solar energy results.
19
+ - Generate reports comparing different solar panel installations.
20
+
21
+ ## Installation
22
+
23
+ Install EcoTrack using pip:
24
+
25
+ ```bash
26
+ pip install ecotrack
27
+ ```
28
+
29
+ ## Quick start
30
+
31
+ Load a CSV file and analyze electricity consumption:
32
+
33
+ ```python
34
+ from ecotrack import EnergyAnalyzer
35
+
36
+ # Load your electricity consumption data
37
+ analyzer = EnergyAnalyzer("my_consumption.csv")
38
+
39
+ # Set your electricity price in EUR/kWh
40
+ analyzer.set_energy_price(0.21)
41
+
42
+ # Calculate total electricity cost
43
+ print(analyzer.calculate_cost())
44
+
45
+ # Detect consumption anomalies
46
+ print(analyzer.detect_anomalies())
47
+
48
+ # Plot electricity consumption
49
+ analyzer.plot_consumption()
50
+ ```
51
+
52
+ ## CSV file format
53
+
54
+ EcoTrack accepts CSV files containing timestamps and a supported electricity measurement column.
55
+
56
+ The default separator is a semicolon (`;`). You can specify another separator when loading the file.
57
+
58
+ Supported timestamp formats:
59
+
60
+ - A single `timestamp` column.
61
+ - Separate `Date` and `Time` columns, using the format `DD/MM/YYYY HH:MM:SS`.
62
+
63
+ Supported measurement columns:
64
+
65
+ | Column | Measurement | Unit |
66
+ |---|---|---|
67
+ | `consumption_kwh` | Energy | kWh |
68
+ | `consumo_kwh` | Energy | kWh |
69
+ | `consumption_wh` | Energy | Wh |
70
+ | `consumo_wh` | Energy | Wh |
71
+ | `global_active_power` | Power | kW |
72
+ | `power_kw` | Power | kW |
73
+ | `power_w` | Power | W |
74
+
75
+ For example:
76
+
77
+ ```csv
78
+ timestamp;consumption_kwh
79
+ 2026-01-01 00:00:00;0.35
80
+ 2026-01-01 01:00:00;0.42
81
+ 2026-01-01 02:00:00;0.31
82
+ ```
83
+
84
+ The file must contain at least two valid measurements with different timestamps.
85
+
86
+ ## Electricity tariffs
87
+
88
+ EcoTrack supports fixed electricity prices:
89
+
90
+ ```python
91
+ analyzer.set_energy_price(0.21)
92
+ ```
93
+
94
+ It also supports different prices depending on the time of day:
95
+
96
+ ```python
97
+ prices = {
98
+ "off_peak": 0.10,
99
+ "mid_peak": 0.16,
100
+ "peak": 0.25
101
+ }
102
+
103
+ hour_periods = {
104
+ "off_peak": [...],
105
+ "mid_peak": [...],
106
+ "peak": [...]
107
+ }
108
+
109
+ analyzer.set_energy_prices(prices, hour_periods)
110
+ ```
111
+
112
+ The hourly periods must assign a price to every hour of the day.
113
+
114
+ ## Solar energy simulation
115
+
116
+ EcoTrack can generate estimated solar production data and simulate the economic performance of solar panel installations.
117
+
118
+ ```python
119
+ # Generate estimated solar production data
120
+ analyzer.generate_solar_data(panel_power=300)
121
+
122
+ # Simulate an installation with 4 panels
123
+ results = analyzer.simulate_solar(panel_count=4)
124
+
125
+ print(results)
126
+
127
+ # Compare installations with different numbers of panels
128
+ scenarios = analyzer.compare_panel_counts(max_panels=7)
129
+
130
+ # Generate a report
131
+ analyzer.generate_report("solar_report.txt")
132
+ ```
133
+
134
+ A fixed electricity tariff must be configured before running the economic solar simulations.
135
+
136
+ **Note:** Solar production and financial results are estimates based on the available data and the assumptions of the simulation model. They should not be interpreted as guaranteed real-world performance.
137
+
138
+ ## Dependencies
139
+
140
+ EcoTrack uses:
141
+
142
+ - pandas
143
+ - NumPy
144
+ - Matplotlib
145
+
146
+ These dependencies are installed automatically when EcoTrack is installed using pip.
147
+
148
+ ## License
149
+
150
+ This project is licensed under the MIT License. See the `LICENSE` file for details.
@@ -0,0 +1,10 @@
1
+
2
+ """EcoTrack: Electricity consumption and solar energy analysis."""
3
+
4
+ from .analyzer import EnergyAnalyzer
5
+
6
+ __version__ = "0.1.0"
7
+
8
+ __all__ = [
9
+ "EnergyAnalyzer",
10
+ ]
@@ -0,0 +1,214 @@
1
+ import pandas as pd
2
+ import numpy as np
3
+
4
+ # 1. ECONOMIC ANALYSIS:
5
+
6
+ def calculate_cost(data, energy_price): # Calculate the total energy cost using a fixed price.
7
+
8
+ if energy_price < 0:
9
+ raise ValueError("Energy price cannot be negative.")
10
+
11
+ total_energy = data["consumption_kwh"].sum()
12
+ return total_energy * energy_price
13
+
14
+ def calculate_daily_cost(data, energy_price): # Calculate the daily energy cost using a fixed price.
15
+
16
+ if energy_price < 0:
17
+ raise ValueError("Energy price cannot be negative.")
18
+ daily_energy = data.groupby(data["timestamp"].dt.date)["consumption_kwh"].sum()
19
+ daily_cost = daily_energy * energy_price
20
+ return daily_cost
21
+
22
+
23
+ def calculate_monthly_cost(data, energy_price): # Calculate the monthly energy cost using a fixed price.
24
+
25
+ if energy_price < 0:
26
+ raise ValueError("Energy price cannot be negative.")
27
+ monthly_energy = data.groupby(data["timestamp"].dt.to_period("M"))["consumption_kwh"].sum()
28
+ monthly_cost = monthly_energy * energy_price
29
+ return monthly_cost
30
+
31
+
32
+ def estimate_savings(data, percentage): #Estimate the energy savings after reducing consumption by a given percentage.
33
+
34
+ if percentage < 0 or percentage > 100:
35
+ raise ValueError("Percentage must be between 0 and 100.")
36
+
37
+ original_energy = data["consumption_kwh"].sum()
38
+ saved_energy = original_energy * percentage / 100
39
+ new_energy = original_energy - saved_energy
40
+
41
+ return {"original_consumption_kwh": original_energy,"saved_energy_kwh": saved_energy,"new_consumption_kwh": new_energy}
42
+
43
+ # 2. TIME-OF-USE TARIFF ANALYSIS
44
+
45
+
46
+ def calculate_hourly_costs(data, prices, hour_periods):
47
+ # Calculate the cost of each consumption record using different
48
+ # electricity prices depending on the hour.
49
+
50
+ if not prices:
51
+ raise ValueError("At least one energy price is required.")
52
+
53
+ if not hour_periods:
54
+ raise ValueError("At least one tariff period is required.")
55
+
56
+ for price in prices.values():
57
+ if price < 0:
58
+ raise ValueError("Energy prices cannot be negative.")
59
+
60
+ hour_prices = {}
61
+
62
+ for period in hour_periods:
63
+
64
+ if period not in prices:
65
+ raise ValueError("A price is missing for a tariff period.")
66
+
67
+ for hour in hour_periods[period]:
68
+
69
+ if hour < 0 or hour > 23:
70
+ raise ValueError("Hours must be between 0 and 23.")
71
+
72
+ if hour in hour_prices:
73
+ raise ValueError("An hour cannot belong to two periods.")
74
+
75
+ hour_prices[hour] = prices[period]
76
+
77
+ # Check that all hours have an assigned price.
78
+ for hour in range(24):
79
+ if hour not in hour_prices:
80
+ raise ValueError("No energy price defined for hour " + str(hour))
81
+
82
+ costs = []
83
+
84
+ for i in range(len(data)):
85
+
86
+ hour = data["timestamp"].iloc[i].hour
87
+ consumption = data["consumption_kwh"].iloc[i]
88
+
89
+ cost = consumption * hour_prices[hour]
90
+
91
+ costs.append(cost)
92
+
93
+ return pd.Series(costs, index=data.index)
94
+
95
+
96
+ def calculate_cost_by_period(data, prices, hour_periods): # Calculate the total energy cost using a time-of-use tariff
97
+
98
+ hourly_costs = calculate_hourly_costs(data,prices,hour_periods)
99
+ return hourly_costs.sum()
100
+
101
+
102
+ def calculate_daily_cost_by_period(data, prices, hour_periods): # Calculate daily energy costs using a time-of-use tariff
103
+
104
+ hourly_costs = calculate_hourly_costs(data,prices,hour_periods)
105
+ daily_costs = data.copy()
106
+ daily_costs["cost_euros"] = hourly_costs
107
+
108
+ return daily_costs.groupby(daily_costs["timestamp"].dt.date)["cost_euros"].sum()
109
+
110
+
111
+ def calculate_monthly_cost_by_period(data, prices, hour_periods): # Calculate monthly energy costs using a time-of-use tariff
112
+
113
+ hourly_costs = calculate_hourly_costs(data,prices,hour_periods)
114
+
115
+ monthly_costs = data.copy()
116
+ monthly_costs["cost_euros"] = hourly_costs
117
+ return monthly_costs.groupby(monthly_costs["timestamp"].dt.to_period("M"))["cost_euros"].sum()
118
+
119
+
120
+ # 3. PEAKS AND ANOMALY DETECTION
121
+
122
+ def detect_peaks(data, percentile=90): # Detect periods with unusually high energy consumption
123
+
124
+ if percentile < 0 or percentile > 100:
125
+ raise ValueError("Percentile must be between 0 and 100.")
126
+
127
+ threshold = np.percentile(data["consumption_kwh"],percentile)
128
+
129
+ peaks = data[data["consumption_kwh"] >= threshold].copy()
130
+ return peaks
131
+
132
+
133
+ def detect_anomalies(data, threshold=2): # Detect anomalous consumption values using standard deviation
134
+
135
+ if threshold <= 0:
136
+ raise ValueError("Threshold must be positive.")
137
+
138
+ mean = data["consumption_kwh"].mean()
139
+
140
+ std = data["consumption_kwh"].std()
141
+
142
+ if pd.isna(std) or std == 0:
143
+ return data.iloc[0:0].copy()
144
+
145
+ lower_limit = mean - threshold * std
146
+ upper_limit = mean + threshold * std
147
+
148
+ anomalies = data[(data["consumption_kwh"] < lower_limit) |(data["consumption_kwh"] > upper_limit)].copy()
149
+
150
+ return anomalies
151
+
152
+
153
+ def get_highest_consumption_periods(data, n=5): # Return the n periods with the highest energy consumption
154
+
155
+ if n <= 0:
156
+ raise ValueError("n must be positive.")
157
+
158
+ highest_periods = data.nlargest(n,"consumption_kwh")
159
+
160
+ return highest_periods
161
+
162
+
163
+ # 4. PERIOD COMPARISON
164
+
165
+ def calculate_variation(initial_value, final_value): # Calculate the percentage variation between two values
166
+
167
+ if initial_value == 0:
168
+ raise ZeroDivisionError("Initial value cannot be zero.")
169
+
170
+ variation = ((final_value - initial_value) / initial_value) * 100
171
+
172
+ return variation
173
+
174
+
175
+
176
+ def compare_periods(data, start_1, end_1, start_2, end_2):
177
+ # Compare energy consumption between two time periods.
178
+
179
+ start_1 = pd.to_datetime(start_1)
180
+ end_1 = pd.to_datetime(end_1)
181
+
182
+ start_2 = pd.to_datetime(start_2)
183
+ end_2 = pd.to_datetime(end_2)
184
+
185
+ if start_1 > end_1 or start_2 > end_2:
186
+ raise ValueError("Start date must be before end date.")
187
+
188
+ # Include the complete final day.
189
+ end_1 = end_1 + pd.Timedelta(days=1)
190
+ end_2 = end_2 + pd.Timedelta(days=1)
191
+
192
+ period_1 = data[
193
+ (data["timestamp"] >= start_1) &
194
+ (data["timestamp"] < end_1)
195
+ ]
196
+
197
+ period_2 = data[
198
+ (data["timestamp"] >= start_2) &
199
+ (data["timestamp"] < end_2)
200
+ ]
201
+
202
+ energy_1 = period_1["consumption_kwh"].sum()
203
+ energy_2 = period_2["consumption_kwh"].sum()
204
+
205
+ if energy_1 == 0:
206
+ variation = None
207
+ else:
208
+ variation = calculate_variation(energy_1, energy_2)
209
+
210
+ return {
211
+ "period_1_consumption_kwh": energy_1,
212
+ "period_2_consumption_kwh": energy_2,
213
+ "variation_percentage": variation
214
+ }