bolster.data_sources.nisra.tourism ================================== .. py:module:: bolster.data_sources.nisra.tourism .. autoapi-nested-parse:: NISRA Tourism Statistics Data Sources. This module provides access to Northern Ireland tourism data including: - **Occupancy Surveys**: Hotel and SSA (B&B/guest house) occupancy rates - **Visitor Statistics**: Quarterly trips, nights spent, and expenditure by market - **Air Passenger Flow**: Airport throughput data (coming soon) All data is sourced from NISRA (Northern Ireland Statistics and Research Agency) and published under the Open Government Licence. .. rubric:: Example >>> from bolster.data_sources.nisra.tourism import occupancy >>> df = occupancy.get_latest_hotel_occupancy() >>> 'room_occupancy' in df.columns True >>> df_combined = occupancy.get_combined_occupancy() >>> comparison = occupancy.compare_accommodation_types(df_combined) >>> 'difference' in comparison.columns True >>> from bolster.data_sources.nisra.tourism import visitor_statistics >>> vs = visitor_statistics.get_latest_visitor_statistics() >>> 'market' in vs.columns True See individual module docstrings for detailed documentation. Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/bolster/data_sources/nisra/tourism/occupancy/index /autoapi/bolster/data_sources/nisra/tourism/visitor_statistics/index Functions --------- .. autoapisummary:: bolster.data_sources.nisra.tourism.compare_accommodation_types bolster.data_sources.nisra.tourism.get_combined_occupancy bolster.data_sources.nisra.tourism.get_latest_hotel_occupancy bolster.data_sources.nisra.tourism.get_latest_hotel_occupancy_publication_url bolster.data_sources.nisra.tourism.get_latest_rooms_beds_sold bolster.data_sources.nisra.tourism.get_latest_ssa_occupancy bolster.data_sources.nisra.tourism.get_latest_ssa_occupancy_publication_url bolster.data_sources.nisra.tourism.get_latest_ssa_rooms_beds_sold bolster.data_sources.nisra.tourism.get_occupancy_by_year bolster.data_sources.nisra.tourism.get_occupancy_summary_by_year bolster.data_sources.nisra.tourism.get_seasonal_patterns Package Contents ---------------- .. py:function:: compare_accommodation_types(df, metric = 'room_occupancy') Compare occupancy between hotel and SSA by year. :param df: DataFrame from get_combined_occupancy() :param metric: Which occupancy metric to compare :returns: - year: int - hotel_{metric}: float - ssa_{metric}: float - difference: float (hotel - ssa) - ratio: float (hotel / ssa) :rtype: DataFrame with columns .. rubric:: Example >>> df = get_combined_occupancy() >>> comparison = compare_accommodation_types(df) >>> 'difference' in comparison.columns True .. py:function:: get_combined_occupancy(force_refresh = False) Get combined hotel and SSA occupancy data with accommodation type column. This function fetches both hotel and SSA occupancy data and combines them into a single DataFrame with an 'accommodation_type' column to distinguish between the two accommodation types. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int - month: str (month name) - room_occupancy: float (room occupancy rate, 0-1) - bed_occupancy: float (bed occupancy rate, 0-1) - accommodation_type: str ('hotel' or 'ssa') :rtype: DataFrame with columns .. rubric:: Example >>> df = get_combined_occupancy() >>> 'accommodation_type' in df.columns True .. py:function:: get_latest_hotel_occupancy(force_refresh = False) Get the latest monthly hotel occupancy rates data. Automatically discovers and downloads the most recent hotel occupancy data from the NISRA website. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int - month: str (month name) - room_occupancy: float (room occupancy rate, 0-1) - bed_occupancy: float (bed occupancy rate, 0-1) :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_hotel_occupancy() >>> 'room_occupancy' in df.columns True .. py:function:: get_latest_hotel_occupancy_publication_url() Scrape NISRA occupancy surveys page to find the latest hotel occupancy file. Navigates the publication structure: 1. Scrapes mother page for latest hotel occupancy publication 2. Follows link to publication detail page 3. Finds hotel occupancy Excel file :returns: Tuple of (excel_file_url, publication_date) :raises NISRADataNotFoundError: If publication or file not found .. py:function:: get_latest_rooms_beds_sold(force_refresh = False) Get the latest monthly rooms and beds sold data. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int - month: str (month name) - rooms_sold: float (number of rooms sold) - beds_sold: float (number of beds sold) :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_rooms_beds_sold() >>> 'rooms_sold' in df.columns True .. py:function:: get_latest_ssa_occupancy(force_refresh = False) Get the latest monthly SSA occupancy rates data. SSA = Small Service Accommodation (B&Bs, guest houses, etc.) Automatically discovers and downloads the most recent SSA occupancy data from the NISRA website. :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int - month: str (month name) - room_occupancy: float (room occupancy rate, 0-1) - bed_occupancy: float (bed occupancy rate, 0-1) :rtype: DataFrame with columns :raises NISRADataNotFoundError: If latest publication cannot be found :raises NISRAValidationError: If file structure is unexpected .. rubric:: Example >>> df = get_latest_ssa_occupancy() >>> 'room_occupancy' in df.columns True .. py:function:: get_latest_ssa_occupancy_publication_url() Scrape NISRA occupancy surveys page to find the latest SSA file. SSA = Small Service Accommodation (B&Bs, guest houses, etc.) Navigates the publication structure: 1. Scrapes mother page for latest SSA occupancy publication 2. Follows link to publication detail page 3. Finds SSA occupancy Excel file :returns: Tuple of (excel_file_url, publication_date) :raises NISRADataNotFoundError: If publication or file not found .. py:function:: get_latest_ssa_rooms_beds_sold(force_refresh = False) Get the latest monthly SSA rooms and beds sold data. SSA = Small Service Accommodation (B&Bs, guest houses, etc.) :param force_refresh: If True, bypass cache and download fresh data :returns: - date: datetime (first day of month) - year: int - month: str (month name) - rooms_sold: float (number of rooms sold) - beds_sold: float (number of beds sold) :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_ssa_rooms_beds_sold() >>> 'rooms_sold' in df.columns True .. py:function:: get_occupancy_by_year(df, year) Filter occupancy data for a specific year. :param df: DataFrame from get_latest_hotel_occupancy() :param year: Year to filter :returns: Filtered DataFrame .. py:function:: get_occupancy_summary_by_year(df) Calculate annual occupancy averages and statistics. :param df: DataFrame from get_latest_hotel_occupancy() :returns: - year: int - avg_room_occupancy: float - avg_bed_occupancy: float - months_reported: int :rtype: DataFrame with columns .. py:function:: get_seasonal_patterns(df) Calculate average occupancy by month across all years. :param df: DataFrame from get_latest_hotel_occupancy() :returns: - month: str (month name) - avg_room_occupancy: float - avg_bed_occupancy: float :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_hotel_occupancy() >>> seasonal = get_seasonal_patterns(df) >>> 'avg_room_occupancy' in seasonal.columns True