bolster.data_sources.nisra.public_confidence ============================================ .. py:module:: bolster.data_sources.nisra.public_confidence .. autoapi-nested-parse:: NISRA Public Confidence in Official Statistics Module. This module provides access to Northern Ireland's Public Awareness of and Trust (Confidence) in Official Statistics (PCOS) data published annually by NISRA. The report covers public awareness of and trust in official statistics, measuring public confidence across multiple dimensions: - Awareness of NISRA - Trust in NISRA, Civil Service, NI Assembly, Media, and NISRA Statistics - Value placed on NISRA statistics - Belief in freedom from political interference - Belief in confidentiality of personal information Data Source: Northern Ireland Statistics and Research Agency (NISRA) publishes annual Public Awareness of and Trust in Official Statistics (PCOS) reports. The data is drawn from the Northern Ireland Continuous Household Survey (CHS, 2018 to present) and the Northern Ireland Omnibus Survey (2009 to 2016). Update Frequency: Annual publications, typically in the first half of the following calendar year (e.g., 2025 data published May 2026). Data Coverage: - Awareness of NISRA: 2009 to present (back-filled in latest file) - Trust measures: 2014 to present (back-filled in latest file) - Value/Political Interference/Confidentiality: 2014/2016 to present .. rubric:: Examples >>> from bolster.data_sources.nisra import public_confidence >>> df = public_confidence.get_latest_public_confidence(breakdown="awareness") >>> "year" in df.columns True >>> df_trust = public_confidence.get_latest_public_confidence(breakdown="trust_nisra") >>> "topic" in df_trust.columns True Publication Details: - Frequency: Annual - Published by: NISRA - Survey: Northern Ireland Continuous Household Survey (CHS) - Topic page: https://www.nisra.gov.uk/statistics/people-and-communities/public-awareness-and-trust-confidence-official-statistics-pcos Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.public_confidence.logger bolster.data_sources.nisra.public_confidence.TOPIC_URL bolster.data_sources.nisra.public_confidence.NISRA_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.public_confidence.get_latest_publication_url bolster.data_sources.nisra.public_confidence.parse_awareness bolster.data_sources.nisra.public_confidence.parse_trust bolster.data_sources.nisra.public_confidence.get_latest_public_confidence bolster.data_sources.nisra.public_confidence.validate_public_confidence Module Contents --------------- .. py:data:: logger .. py:data:: TOPIC_URL :value: 'https://www.nisra.gov.uk/statistics/people-and-communities/public-awareness-and-trust-confidence... .. py:data:: NISRA_BASE_URL :value: 'https://www.nisra.gov.uk' .. py:function:: get_latest_publication_url() Scrape the PCOS topic page to find the latest ODS data file URL. Navigates the NISRA topic page to find the most recent publication, then fetches that publication's page to locate the ODS download link. :returns: URL string for the latest ODS data tables file. :raises NISRADataNotFoundError: If unable to find the publication or ODS file. .. rubric:: Example >>> url = get_latest_publication_url() >>> url.startswith("https://") True .. py:function:: parse_awareness(file_path) Parse NISRA awareness time-series data from the ODS file. Extracts the ``Awareness_of_NISRA`` sheet (Table 1a: time series 2009–present), converting the wide-format table to a tidy long-format DataFrame. :param file_path: Path to the downloaded ODS data tables file. :returns: - year: int (survey year, e.g. 2025) - response: str (e.g. ``"Yes"``, ``"No"``, ``"Don't Know"``) - percentage: float (rounded to 4 decimal places) :rtype: DataFrame with columns .. rubric:: Example >>> url = get_latest_publication_url() >>> path = download_file(url, cache_ttl_hours=24 * 365) >>> df = parse_awareness(path) >>> set(df.columns) == {"year", "response", "percentage"} True .. py:function:: parse_trust(file_path, topic) Parse trust time-series data for a specific institution from the ODS file. :param file_path: Path to the downloaded ODS data tables file. :param topic: Institution to parse. One of: ``"nisra"``, ``"civil_service"``, ``"ni_assembly"``, ``"media"``, ``"nisra_statistics"``. :returns: - year: int (survey year) - response: str (e.g. ``"Tend to trust/trust a great deal"``) - percentage: float - topic: str (the ``topic`` argument) :rtype: DataFrame with columns :raises ValueError: If ``topic`` is not a valid key. :raises NISRADataNotFoundError: If the sheet cannot be parsed. .. rubric:: Example >>> url = get_latest_publication_url() >>> path = download_file(url, cache_ttl_hours=24 * 365) >>> df = parse_trust(path, "nisra") >>> "topic" in df.columns True .. py:function:: get_latest_public_confidence(breakdown = 'awareness', force_refresh = False) Download and parse the latest PCOS data for a given breakdown. Downloads the latest ODS file (cached for one year — annual data) and returns a tidy DataFrame for the requested breakdown. :param breakdown: Which breakdown to return. One of: ``"awareness"`` — awareness of NISRA (2009–present), ``"trust_nisra"`` — trust in NISRA (2014–present), ``"trust_civil_service"`` — trust in the Civil Service, ``"trust_ni_assembly"`` — trust in the NI Assembly, ``"trust_media"`` — trust in the Media, ``"trust_nisra_statistics"`` — trust in NISRA statistics, ``"all_trust"`` — all five trust topics combined (adds ``topic`` column). :param force_refresh: If ``True``, bypass cache and re-download the file. :returns: columns ``year``, ``response``, ``percentage``. For trust breakdowns: ``year``, ``response``, ``percentage``, ``topic``. :rtype: Tidy long-format DataFrame. For ``"awareness"`` :raises ValueError: If ``breakdown`` is not a valid option. :raises NISRADataNotFoundError: If the data cannot be downloaded or parsed. .. rubric:: Example >>> df = get_latest_public_confidence(breakdown="awareness") >>> sorted(df.columns.tolist()) ['percentage', 'response', 'year'] >>> df_trust = get_latest_public_confidence(breakdown="all_trust") >>> "topic" in df_trust.columns True .. py:function:: validate_public_confidence(df) Validate a public confidence DataFrame for required structure and value ranges. Checks that: - DataFrame is not empty. - Required columns are present (``year``, ``response``, ``percentage``). - All ``percentage`` values are in the range [0, 100]. - The ``year`` column contains only integers. :param df: DataFrame from :func:`get_latest_public_confidence` or the individual parse functions. :returns: ``True`` if all checks pass. :raises ValueError: If any check fails, with a descriptive message. .. rubric:: Example >>> import pandas as pd >>> df = pd.DataFrame({"year": [2025], "response": ["Yes"], "percentage": [48.1]}) >>> validate_public_confidence(df) True