bolster.data_sources.nisra.construction_output ============================================== .. py:module:: bolster.data_sources.nisra.construction_output .. autoapi-nested-parse:: NISRA Construction Output Statistics Module. This module provides access to Northern Ireland's quarterly construction output statistics: - All Work: Total construction output index - New Work: New construction projects - Repair and Maintenance: Repair and maintenance work Data is published quarterly by NISRA's Economic & Labour Market Statistics Branch. Data Source: Northern Ireland Statistics and Research Agency provides quarterly construction output statistics through their Economic Output section at https://www.nisra.gov.uk/statistics/economic-output/construction-output-statistics. The data tracks construction activity across all sectors using a chained volume measure approach to provide comparable time series data for construction output analysis. Update Frequency: Quarterly publications are released approximately 3 months after the end of each quarter. Construction output statistics are published as part of NISRA's Economic Output series, providing the official measure of construction sector performance in Northern Ireland with data updated four times per year. Data Coverage: - All Work: Q1 2000 - Present (quarterly, non-seasonally adjusted) - New Work: Q1 2000 - Present (quarterly, non-seasonally adjusted) - Repair and Maintenance: Q1 2000 - Present (quarterly, seasonally adjusted) - Base year: 2022 = 100 (chained volume measure) .. rubric:: Examples >>> from bolster.data_sources.nisra import construction_output >>> df = construction_output.get_latest_construction_output() >>> 'all_work_index' in df.columns True >>> df_2024 = construction_output.get_construction_by_year(df, 2024) >>> len(df_2024) <= 4 True >>> df_growth = construction_output.calculate_growth_rates(df) >>> 'all_work_yoy_growth' in df_growth.columns True Publication Details: - Frequency: Quarterly - Published by: NISRA Economic & Labour Market Statistics Branch - Contact: economicstats@nisra.gov.uk - Next release: Approximately 3 months after quarter end - Base year: 2022 (index = 100) Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.construction_output.logger bolster.data_sources.nisra.construction_output.CONSTRUCTION_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.construction_output.get_latest_construction_publication_url bolster.data_sources.nisra.construction_output.parse_construction_file bolster.data_sources.nisra.construction_output.get_latest_construction_output bolster.data_sources.nisra.construction_output.get_construction_by_year bolster.data_sources.nisra.construction_output.get_construction_by_quarter bolster.data_sources.nisra.construction_output.calculate_growth_rates bolster.data_sources.nisra.construction_output.get_summary_statistics bolster.data_sources.nisra.construction_output.validate_construction_data Module Contents --------------- .. py:data:: logger .. py:data:: CONSTRUCTION_BASE_URL :value: 'https://www.nisra.gov.uk/statistics/economic-output/construction-output-statistics' .. py:function:: get_latest_construction_publication_url() Get the URL of the latest Construction Output publication. Scrapes the NISRA Construction Output page to find the most recent publication. :returns: Tuple of (excel_url, publication_date) :raises NISRADataNotFoundError: If unable to find the latest publication .. rubric:: Example >>> url, pub_date = get_latest_construction_publication_url() >>> url.startswith('https://') True .. py:function:: parse_construction_file(file_path) Parse NISRA Construction Output Excel file. Extracts the main construction output time series (Table 1.1) from the Excel file. :param file_path: Path to the Construction Output Excel file :returns: - date: datetime (first day of quarter) - quarter: str (e.g., 'Q1', 'Q2', 'Q3', 'Q4') - year: int - all_work_index: float (total construction output, NSA) - new_work_index: float (new construction work, NSA) - repair_maintenance_index: float (repair and maintenance, SA) :rtype: DataFrame with columns .. rubric:: Example >>> url, _ = get_latest_construction_publication_url() >>> path = download_file(url, cache_ttl_hours=168) >>> df = parse_construction_file(path) >>> 'all_work_index' in df.columns True .. py:function:: get_latest_construction_output(force_refresh = False) Get the latest Construction Output data. Downloads and parses the most recent NISRA Construction Output publication. Results are cached for 7 days unless force_refresh=True. :param force_refresh: If True, bypass cache and download fresh data :returns: DataFrame with quarterly Construction Output data .. rubric:: Example >>> df = get_latest_construction_output() >>> 'all_work_index' in df.columns True .. py:function:: get_construction_by_year(df, year) Filter Construction Output data for a specific year. :param df: Construction Output DataFrame :param year: Year to filter for :returns: DataFrame with only the specified year's data .. rubric:: Example >>> df = get_latest_construction_output() >>> df_2024 = get_construction_by_year(df, 2024) >>> len(df_2024) <= 4 True .. py:function:: get_construction_by_quarter(df, quarter, year) Get Construction Output data for a specific quarter. :param df: Construction Output DataFrame :param quarter: Quarter code (e.g., 'Q1', 'Q2', 'Q3', 'Q4') :param year: Year :returns: DataFrame with single row for the specified quarter .. rubric:: Example >>> df = get_latest_construction_output() >>> q2_2025 = get_construction_by_quarter(df, 'Q2', 2025) >>> len(q2_2025) <= 1 True .. py:function:: calculate_growth_rates(df, periods = 4) Calculate year-on-year growth rates for Construction Output indices. :param df: Construction Output DataFrame :param periods: Number of quarters for comparison (default: 4 for YoY) :returns: - all_work_yoy_growth: All Work percentage change vs same quarter previous year - new_work_yoy_growth: New Work percentage change vs same quarter previous year - repair_maintenance_yoy_growth: R&M percentage change vs same quarter previous year :rtype: DataFrame with additional columns .. rubric:: Example >>> df = get_latest_construction_output() >>> df_growth = calculate_growth_rates(df) >>> 'all_work_yoy_growth' in df_growth.columns True .. py:function:: get_summary_statistics(df, start_year = None, end_year = None) Calculate summary statistics for Construction Output. :param df: Construction Output DataFrame :param start_year: Optional start year for summary :param end_year: Optional end year for summary :returns: - period: Time period covered - all_work_mean: Mean All Work index value - all_work_min: Minimum All Work index value - all_work_max: Maximum All Work index value - new_work_mean: Mean New Work index value - repair_maintenance_mean: Mean Repair & Maintenance index value - quarters_count: Number of quarters included :rtype: Dictionary with summary statistics .. rubric:: Example >>> df = get_latest_construction_output() >>> stats = get_summary_statistics(df, start_year=2020) >>> 'all_work_mean' in stats True .. py:function:: validate_construction_data(df) Validate construction output data integrity. :param df: DataFrame from construction output functions :returns: True if validation passes, False otherwise