sgfixedincome_pkg.consolidate ============================= .. py:module:: sgfixedincome_pkg.consolidate Functions --------- .. autoapisummary:: sgfixedincome_pkg.consolidate.merge_dataframes sgfixedincome_pkg.consolidate.create_banks_df sgfixedincome_pkg.consolidate.add_ssb_details sgfixedincome_pkg.consolidate.create_ssb_df sgfixedincome_pkg.consolidate.create_tbill_df sgfixedincome_pkg.consolidate.create_combined_df Module Contents --------------- .. py:function:: merge_dataframes(df_list) Merges a list of DataFrames by appending rows, with validation of input. :param df_list: A list of pandas DataFrames to be merged. Each DataFrame must either be empty, or contain exactly the following columns: 'Tenure', 'Rate', 'Deposit lower bound', 'Deposit upper bound', 'Required multiples', 'Product provider', 'Product'. :type df_list: list of pd.DataFrame :returns: A single DataFrame with all rows from the input DataFrames. Returns an empty DataFrame with the required columns if all input DataFrames are empty. :rtype: pd.DataFrame :raises TypeError: If the input is not a list or does not contain pandas DataFrames. :raises ValueError: If any DataFrame in the list does not have exactly the required columns. .. py:function:: create_banks_df(scrape_inputs) Scrapes deposit rates from multiple bank websites and combines them into a single DataFrame. Even if scraping fails for some websites, a DataFrame containing data from successfully scraped sites is still returned. The function also provides a list of dictionaries with information on websites it failed to scrape from. The function also validates the input before running its main task. If we fail to scrape from all websites, the function returns an empty dataframe. :param scrape_inputs: Each tuple contains: - URL (str): The webpage to scrape. - Table class (str): The class of the table to locate. - Provider (str): The name of the bank/provider. - Required multiples (float or None, optional): Value to populate the "Required multiples" column. Defaults to None if omitted. :type scrape_inputs: list of tuples :returns: A tuple containing: - pd.DataFrame: Combined DataFrame with all successfully scraped deposit rates. - list of dict: Each dict contains details of failed scrapes with: - product (str): Name of the provider and product that failed (e.g. DBS bank fixed deposit) - error (str): Error message describing the failure. :rtype: tuple :raises ValueError: If the input is not a list of tuples with the expected structure. .. py:function:: add_ssb_details(df, current_ssb_holdings, issue_code) Add additional details to the DataFrame with SSB tenure and rate data. :param df: DataFrame with SSB tenure month and rates. :type df: pd.DataFrame :param current_ssb_holdings: Current SSB holdings in Singapore dollars. :type current_ssb_holdings: float :param issue_code: The SSB's issue code. :type issue_code: str :returns: Updated DataFrame with additional SSB information. :rtype: pd.DataFrame .. py:function:: create_ssb_df(client, current_ssb_holdings=0.0) Create a dataframe containing the details and rates for the latest Singapore Savings Bond (SSB). :param client: An initialized instance of the MAS_bondsandbills_APIClient. :param current_ssb_holdings: The amount of SSBs you currently hold in Singapore dollars. Defaults to 0.0. :type current_ssb_holdings: float, optional :returns: A dataframe with SSB tenure rates and additional details. :rtype: pandas.DataFrame .. py:function:: create_tbill_df(tbill_details) Create a pandas DataFrame with details about a T-bill. :param tbill_details: A dictionary containing details about a T-bill. Expected keys include: - cutoff_yield (float): in percentage. - issue_code (str): identifies the T-bill. - auction_tenor (float): specifies if it is a 6-month (0.5) or 12-month (1.0) T-bill. :type tbill_details: dict :returns: A DataFrame with the following columns: - Tenure (int): The tenure of the T-bill in months. - Rate (float): The cutoff yield of the T-bill. - Deposit lower bound (int): The minimum investment amount (fixed at 1000). - Deposit upper bound (int): The maximum investment amount (fixed at 99999999). - Required multiples (int): The required investment increments (fixed at 1000). - Product provider (str): The provider of the product (fixed as "MAS"). - Product (str): A description of the T-bill, including its issue code. :rtype: pd.DataFrame .. rubric:: Example >>> tbill_details = {"cutoff_yield": 3.08, "issue_code": "BS24123F", "auction_tenor": 0.5} >>> df = create_tbill_df(tbill_details) >>> df Tenure Rate Deposit lower bound Deposit upper bound Required multiples Product provider Product 0 6 3.08 1000 99999999 1000 MAS T-bill BS24123F .. py:function:: create_combined_df(scrape_inputs=[('https://www.dbs.com.sg/personal/rates-online/fixed-deposit-rate-singapore-dollar.page', 'tbl-primary mBot-24', 'DBS'), ('https://www.uob.com.sg/personal/online-rates/singapore-dollar-time-fixed-deposit-rates.page', 'table__carousel-table', 'UOB'), ('https://www.ocbc.com/personal-banking/deposits/fixed-deposit-sgd-interest-rates.page', 'table__comparison-table', 'OCBC')], current_ssb_holdings=0.0, tbill_threshold=10) Creates a combined DataFrame by aggregating data from banks, MAS Singapore Savings Bonds (SSBs), and Treasury Bills (T-bills), and providing information on cases where data fetching failed. :param scrape_inputs: Input parameters for scraping bank data. Each tuple contains: - URL (str): The webpage to scrape. - Table class (str): The class of the table to locate. - Provider (str): The name of the bank/provider. - Required multiples (float or None, optional): Value to populate the "Required multiples" column. Defaults to None if omitted. Default value includes DBS, UOB, and OCBC bank details. :type scrape_inputs: list of tuples, optional :param current_ssb_holdings: The amount of SSBs you currently hold in Singapore dollars. Defaults to 0.0. :type current_ssb_holdings: float, optional :param tbill_threshold: The threshold for the yield difference in basis points for the T-bill warning. Default is 10. :type tbill_threshold: int, optional :returns: A tuple containing: - pd.DataFrame: Combined DataFrame containing data from banks, SSBs, and T-bills. - list of dict: List of fetch failures, where each entry is a dictionary with two keys: - product: the product-provider pair (e.g., 'MAS SSB', 'MAS T-bill') - error: the error message. - list of str: List of warning messages generated during the process. :rtype: tuple