detquantlib 2.1.1__tar.gz → 3.0.0__tar.gz

{detquantlib-2.1.1 → detquantlib-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: detquantlib
-Version: 2.1.1
+Version: 3.0.0
 Summary: An internal library containing functions and classes that can be used across Quant models.
 Author: DET
 Requires-Python: >=3.10,<4.0

{detquantlib-2.1.1 → detquantlib-3.0.0}/detquantlib/data/databases/detdatabase.py

@@ -1,4 +1,5 @@
 # Python built-in packages
+import os
 import warnings
 from datetime import datetime
 from zoneinfo import ZoneInfo
@@ -16,42 +17,55 @@ class DetDatabase:
 
     def __init__(
         self,
-        username: str,
-        password: str,
-        server: str,
-        database: str,
         connection: pyodbc.Connection = None,
+        driver: str = "{ODBC Driver 18 for SQL Server}",
     ):
         """
         Constructor method.
 
         Args:
-            username: Database username
-            password: Database password
-            server: Database server name
-            database: Database name
             connection: Database connection object. This argument does not have to be passed
                 when creating the object. It can be set after the object has been created, using
                 the open_connection() method.
+            driver: ODBC driver
+
+        Raises:
+            EnvironmentError: Raises an error if environment variables are not defined
         """
-        self.username = username
-        self.password = password
-        self.server = server
-        self.database = database
         self.connection = connection
-
-        # Define the ODBC driver
-        self.driver = "{ODBC Driver 18 for SQL Server}"
+        self.driver = driver
+
+        # Check if environment variables needed by the class are defined
+        required_env_vars = [
+            dict(name="DET_DB_NAME", value=None, description="DET database name"),
+            dict(name="DET_DB_SERVER", value=None, description="DET database server name"),
+            dict(
+                name="DET_DB_USERNAME", value=None, description="Username to connect to database"
+            ),
+            dict(
+                name="DET_DB_PASSWORD", value=None, description="Password to connect to database"
+            ),
+        ]
+        available_env_vars = os.environ
+        for d in required_env_vars:
+            if d["name"] not in available_env_vars:
+                required_env_vars_names = [x["name"] for x in required_env_vars]
+                required_env_vars_str = ", ".join(f"'{x}'" for x in required_env_vars_names)
+                raise EnvironmentError(
+                    f"The DetDatabase class requires the following environment variables: "
+                    f"{required_env_vars_str}. Environment variable '{d['name']}' "
+                    f"(description: '{d['description']}') not found."
+                )
 
     def open_connection(self):
         """Opens a connection to the database."""
         # Create the connection string
         connection_str = (
             f"DRIVER={self.driver};"
-            f"SERVER={self.server};"
-            f"DATABASE={self.database};"
-            f"UID={self.username};"
-            f"PWD={self.password}"
+            f"SERVER={os.getenv('DET_DB_SERVER')};"
+            f"DATABASE={os.getenv('DET_DB_NAME')};"
+            f"UID={os.getenv('DET_DB_USERNAME')};"
+            f"PWD={os.getenv('DET_DB_PASSWORD')}"
         )
         self.connection = pyodbc.connect(connection_str)
 
@@ -88,8 +102,7 @@ class DetDatabase:
 
     def load_entsoe_day_ahead_spot_prices(
         self,
-        map_code: str,
-        timezone: str,
+        commodity_name: str,
         start_trading_date: datetime = None,
         end_trading_date: datetime = None,
         start_delivery_date: datetime = None,
@@ -101,7 +114,7 @@ class DetDatabase:
         Loads entsoe day-ahead spot prices from the database.
 
         Args:
-            map_code: Map code of the power country/region
+            commodity_name: Commodity name (as defined in the [META].[Commodity] database table)
             start_trading_date: Start trading date
             end_trading_date: End trading date
                 Note: The user should provide either 'start_trading_date' and 'end_trading_date',
@@ -112,9 +125,6 @@ class DetDatabase:
                 (i.e. delivery dates < end_date).
                 Note: The user should provide either 'start_trading_date' and 'end_trading_date',
                 or 'start_delivery_date' and 'end_delivery_date'.
-            timezone: Timezone of the power country/region. This argument is important because
-                ENTSOE provides all prices in the UTC timezone. We first convert the dates from
-                UTC to the local timezone, and then filter for the requested delivery period.
             columns: Requested database table columns. Set columns=["*"] (i.e. as list) to get
                 all columns.
             process_data: Indicates if data should be processed convert to standardized format
@@ -123,10 +133,13 @@ class DetDatabase:
             Dataframe containing day-ahead spot prices
 
         Raises:
-            ValueError: Raises an error when input arguments 'columns' and 'process_data' are
-                not compatible
-            ValueError: Raises an error when the combination of trading dates and delivery dates
+            ValueError: Raises an error if input arguments 'columns' and 'process_data' are not
+                compatible
+            ValueError: Raises an error if the combination of trading dates and delivery dates
                 is not valid.
+            ValueError: Raises an error if match with input commodity name is not unique
+            ValueError: Raises an error if input commodity is not supported
+            ValueError: Raises an error if no price data is found for user inputs
         """
         # Input validation
         if process_data and columns is not None:
@@ -164,6 +177,26 @@ class DetDatabase:
         else:
             columns_str = f"[{'], ['.join(columns)}]"
 
+        # Get commodity information (map code and local timezone)
+        # Note: The local timezone is important because ENTSOE provides all prices in the UTC
+        # timezone. We first convert the dates from UTC to the local timezone, and then filter
+        # for the requested delivery period.
+        commodity_info = self.load_commodities(
+            columns=["Timezone", "EntsoeMapCode"], conditions=f"WHERE Name='{commodity_name}'"
+        )
+        if commodity_info.shape[0] > 1:
+            raise ValueError(f"More than one match found with commodity '{commodity_name}'.")
+        elif commodity_info.shape[0] == 0:
+            supported_commodities = self.load_commodities(columns=["Name"])
+            supported_commodities_str = ", ".join(f"'{x}'" for x in supported_commodities["Name"])
+            raise ValueError(
+                f"Commodity '{commodity_name}' is not supported. Supported commodities: "
+                f"{supported_commodities_str}."
+            )
+        else:
+            map_code = commodity_info.loc[0, "EntsoeMapCode"]
+            timezone = commodity_info.loc[0, "Timezone"]
+
         # Convert start trading date to start delivery date
         if start_trading_date is not None:
             start_trading_date = pd.Timestamp(start_trading_date).floor("D")
@@ -198,6 +231,9 @@ class DetDatabase:
         df = self.query_db(query)
         self.close_connection()
 
+        if df.empty:
+            raise ValueError("No price data found for user-defined inputs.")
+
         # Sort data by delivery date
         df.sort_values(
             by=["DateTime(UTC)"], axis=0, ascending=True, inplace=True, ignore_index=True
@@ -211,40 +247,30 @@ class DetDatabase:
 
         # Process raw data and convert it to standardized format
         if process_data:
-            df = DetDatabase.process_day_ahead_spot_prices(df, timezone)
+            df = DetDatabase.process_day_ahead_spot_prices(df, commodity_name, timezone)
 
         return df
 
     @staticmethod
-    def process_day_ahead_spot_prices(df_in: pd.DataFrame, timezone: str) -> pd.DataFrame:
+    def process_day_ahead_spot_prices(
+        df_in: pd.DataFrame, commodity_name: str, timezone: str
+    ) -> pd.DataFrame:
         """
         Processes day-ahead spot prices and converts from ENTSOE format to standardized format.
 
         Args:
             df_in: Dataframe containing day-ahead spot prices
+            commodity_name: Commodity name (as defined in the [META].[Commodity] database table)
             timezone: Timezone of the power country/region
 
         Returns:
             Processed dataframe containing day-ahead spot prices
         """
-        map_code_to_commodity_mapper = dict(
-            NL={"commodity_name": "DutchPower", "product_code": "Q0B"}
-        )
-
         # Initialize output dataframe
         df_out = pd.DataFrame()
 
         # Set commodity name
-        commodity_name = [
-            map_code_to_commodity_mapper[mc]["commodity_name"] for mc in df_in["MapCode"]
-        ]
-        df_out["CommodityName"] = commodity_name
-
-        # Set product code
-        product_code = [
-            map_code_to_commodity_mapper[mc]["product_code"] for mc in df_in["MapCode"]
-        ]
-        df_out["ProductCode"] = product_code
+        df_out["CommodityName"] = [commodity_name] * df_in.shape[0]
 
         # Set trading date
         trading_date = [d - relativedelta(days=1, hour=0) for d in df_in[f"DateTime({timezone})"]]
@@ -267,8 +293,7 @@ class DetDatabase:
 
     def load_entsoe_imbalance_prices(
         self,
-        map_code: str,
-        timezone: str,
+        commodity_name: str,
         start_trading_date: datetime = None,
         end_trading_date: datetime = None,
         start_delivery_date: datetime = None,
@@ -280,10 +305,7 @@ class DetDatabase:
         Loads entsoe imbalance prices from the database.
 
         Args:
-            map_code: Map code of the power country/region
-            timezone: Timezone of the power country/region. This argument is important because
-                ENTSOE provides all prices in the UTC timezone. We first convert the dates from
-                UTC to the local timezone, and then filter for the requested delivery period.
+            commodity_name: Commodity name (as defined in the [META].[Commodity] database table)
             start_trading_date: Start trading date
             end_trading_date: End trading date
                 Note: The user should provide either 'start_trading_date' and 'end_trading_date',
@@ -302,10 +324,13 @@ class DetDatabase:
             Dataframe containing imbalance prices
 
         Raises:
-            ValueError: Raises an error when input arguments 'columns' and 'process_data' are
-                not compatible
-            ValueError: Raises an error when the combination of trading dates and delivery dates
+            ValueError: Raises an error if input arguments 'columns' and 'process_data' are not
+                compatible
+            ValueError: Raises an error if the combination of trading dates and delivery dates
                 is not valid.
+            ValueError: Raises an error if match with input commodity name is not unique
+            ValueError: Raises an error if input commodity is not supported
+            ValueError: Raises an error if no price data is found for user inputs
         """
         # Input validation
         if process_data and columns is not None:
@@ -349,6 +374,26 @@ class DetDatabase:
         else:
             columns_str = f"[{'], ['.join(columns)}]"
 
+        # Get commodity information (map code and local timezone)
+        # Note: The local timezone is important because ENTSOE provides all prices in the UTC
+        # timezone. We first convert the dates from UTC to the local timezone, and then filter
+        # for the requested delivery period.
+        commodity_info = self.load_commodities(
+            columns=["Timezone", "EntsoeMapCode"], conditions=f"WHERE Name='{commodity_name}'"
+        )
+        if commodity_info.shape[0] > 1:
+            raise ValueError(f"More than one match found with commodity '{commodity_name}'.")
+        elif commodity_info.shape[0] == 0:
+            supported_commodities = self.load_commodities(columns=["Name"])
+            supported_commodities_str = ", ".join(f"'{x}'" for x in supported_commodities["Name"])
+            raise ValueError(
+                f"Commodity '{commodity_name}' is not supported. Supported commodities: "
+                f"{supported_commodities_str}."
+            )
+        else:
+            map_code = commodity_info.loc[0, "EntsoeMapCode"]
+            timezone = commodity_info.loc[0, "Timezone"]
+
         # Convert start trading date to start delivery date
         if start_trading_date is not None:
             start_delivery_date = pd.Timestamp(start_trading_date).floor("D")
@@ -382,6 +427,9 @@ class DetDatabase:
         df = self.query_db(query)
         self.close_connection()
 
+        if df.empty:
+            raise ValueError("No price data found for user-defined inputs.")
+
         # Sort data by delivery date
         df.sort_values(
             by=["DateTime(UTC)"], axis=0, ascending=True, inplace=True, ignore_index=True
@@ -395,40 +443,30 @@ class DetDatabase:
 
         # Process raw data and convert it to standardized format
         if process_data:
-            df = DetDatabase.process_imbalance_prices(df, timezone)
+            df = DetDatabase.process_imbalance_prices(df, commodity_name, timezone)
 
         return df
 
     @staticmethod
-    def process_imbalance_prices(df_in: pd.DataFrame, timezone: str) -> pd.DataFrame:
+    def process_imbalance_prices(
+        df_in: pd.DataFrame, commodity_name: str, timezone: str
+    ) -> pd.DataFrame:
         """
         Processes imbalance prices and converts from ENTSOE format to standardized format.
 
         Args:
             df_in: Dataframe containing imbalance prices
+            commodity_name: Commodity name (as defined in the [META].[Commodity] database table)
             timezone: Timezone of the power country/region
 
         Returns:
             Processed dataframe containing imbalance prices
         """
-        map_code_to_commodity_mapper = dict(
-            NL={"commodity_name": "DutchPower", "product_code": "Q0B"}
-        )
-
         # Initialize output dataframe
         df_out = pd.DataFrame()
 
         # Set commodity name
-        commodity_name = [
-            map_code_to_commodity_mapper[mc]["commodity_name"] for mc in df_in["MapCode"]
-        ]
-        df_out["CommodityName"] = commodity_name
-
-        # Set product code
-        product_code = [
-            map_code_to_commodity_mapper[mc]["product_code"] for mc in df_in["MapCode"]
-        ]
-        df_out["ProductCode"] = product_code
+        df_out["CommodityName"] = [commodity_name] * df_in.shape[0]
 
         # Set trading date
         df_out["TradingDate"] = df_in[f"DateTime({timezone})"].dt.floor("D").values
@@ -463,16 +501,19 @@ class DetDatabase:
         of trading dates.
 
         Args:
-            commodity_name: Commodity name
+            commodity_name: Commodity name (as defined in the [META].[Commodity] database table)
             start_trading_date: Start trading date
             end_trading_date: End trading date
             tenors: Product tenors (e.g. "Month", "Quarter", "Year")
-            delivery_type: Delivery type
+            delivery_type: Delivery type ("Base", "Peak", "Offpeak")
             columns: Requested database table columns. Set columns=["*"] (i.e. as list) to get
                 all columns.
 
         Returns:
             Dataframe containing futures end-of-day settlement prices
+
+        Raises:
+            ValueError: Raises an error if no price data is found for user inputs
         """
         # Set default column values
         if columns is None:
@@ -507,6 +548,9 @@ class DetDatabase:
         df = self.query_db(query)
         self.close_connection()
 
+        if df.empty:
+            raise ValueError("No price data found for user-defined inputs.")
+
         # Sort data
         df.sort_values(
             by=["TradingDate", "DeliveryStart", "DeliveryEnd"],
@@ -523,12 +567,84 @@ class DetDatabase:
 
         return df
 
+    def load_commodities(self, columns: list = None, conditions: str = None) -> pd.DataFrame:
+        """
+        General method to load data from the database's commodity table.
+
+        Args:
+            columns: Requested database table columns. Set columns=["*"] (i.e. as list) to get
+                all columns.
+            conditions: Optional conditions to add to SQL query. E.g. "WHERE Name='DutchPower'".
+
+        Returns:
+            Table data
+        """
+        # Set default column values
+        if columns is None:
+            columns = ["*"]
+
+        # Convert columns from list to string
+        if len(columns) == 1:
+            columns_str = str(columns[0])
+        else:
+            columns_str = f"[{'], ['.join(columns)}]"
+
+        # Create query
+        table = DetDatabaseDefinitions.DEFINITIONS["table_name_commodity"]
+        query = f"SELECT {columns_str} FROM {table} {conditions}"
+
+        # Query db
+        self.open_connection()
+        df = self.query_db(query)
+        self.close_connection()
+
+        return df
+
+    def get_commodity_info(
+        self, filter_column: str, filter_value: str, info_columns: list
+    ) -> dict:
+        """
+        Finds information related to a specific, user-defined commodity.
+
+        Args:
+            filter_column: Column used to filter data for one specific commodity
+            filter_value: Value used to filter data for one specific commodity
+            info_columns: Columns containing the requested information
+
+        Returns:
+            A dictionary containing the requested information
+
+        Raises:
+            ValueError: Raises an error if match with input filter value is not unique
+            ValueError: Raises an error if the input filter value is not found
+        """
+        # Get commodity information for user-defined filtering criteria
+        condition = f"WHERE {filter_column}='{filter_value}'"
+        commodity_info = self.load_commodities(columns=info_columns, conditions=condition)
+
+        # Validate response
+        if commodity_info.shape[0] > 1:
+            raise ValueError(f"More than one match found for {filter_column}={filter_value}.")
+
+        elif commodity_info.shape[0] == 0:
+            available_values = self.load_commodities(columns=[filter_column])
+            available_values_str = ", ".join(f"'{x}'" for x in available_values[filter_column])
+            raise ValueError(
+                f"Value {filter_value} not found in column '{filter_column}'. Available values: "
+                f"{available_values_str}."
+            )
+
+        # Convert dataframe row to dict
+        commodity_info = commodity_info.loc[0, :].to_dict()
+
+        return commodity_info
+
 
 class DetDatabaseDefinitions:
     """A class containing some hard-coded definitions related to the DET database."""
 
     DEFINITIONS = dict(
-        driver="{ODBC Driver 18 for SQL Server}",
+        table_name_commodity="[META].[Commodity]",
         table_name_entsoe_day_ahead_spot_price="[ENTSOE].[DayAheadSpotPrice]",
         table_name_entsoe_imbalance_price="[ENTSOE].[ImbalancePrice]",
         table_name_futures_eod_settlement_price="[VW].[EODSettlementPrice]",

{detquantlib-2.1.1 → detquantlib-3.0.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "detquantlib"
-version = "2.1.1"
+version = "3.0.0"
 description = "An internal library containing functions and classes that can be used across Quant models."
 authors = ["DET"]
 readme = "README.md"