bolster.data_sources.nisra.wellbeing ==================================== .. py:module:: bolster.data_sources.nisra.wellbeing .. autoapi-nested-parse:: NISRA Individual Wellbeing Module. This module provides access to Northern Ireland's individual wellbeing statistics, measuring subjective wellbeing across the population aged 16 and over. The report covers four main areas of individual wellbeing: - Personal Wellbeing (ONS4 measures): Life Satisfaction, Worthwhile, Happiness, Anxiety - Loneliness: Frequency of feeling lonely - Self-efficacy: Belief in one's capabilities - Locus of Control: Perceived control over life events Data Source: Northern Ireland Statistics and Research Agency provides individual wellbeing statistics through their Wellbeing section at https://www.nisra.gov.uk/statistics/wellbeing/individual-wellbeing-northern-ireland. The data measures subjective wellbeing using the ONS4 personal wellbeing questions alongside additional measures of loneliness, self-efficacy, and locus of control for adults in Northern Ireland. Update Frequency: Annual publications released in January each year, covering the financial year period from April to March. The wellbeing statistics provide the official measure of subjective wellbeing for Northern Ireland, with data updated once per year as part of NISRA's social statistics programme. Data Coverage: - Personal Wellbeing (ONS4): 2014/15 - Present (annual, mean scores 0-10) - Loneliness: 2017/18 - Present (annual, proportions) - Self-efficacy: 2014/15 - Present (annual, mean scores 5-25) - Locus of Control: Available in recent years Demographics available: - Sex, Age Group, Marital Status, Sexual Orientation - Religion, Dependant status, Health status, Employment status .. rubric:: Examples >>> from bolster.data_sources.nisra import wellbeing >>> df = wellbeing.get_latest_personal_wellbeing() >>> 'life_satisfaction' in df.columns True >>> df_lonely = wellbeing.get_latest_loneliness() >>> 'lonely_some_of_time' in df_lonely.columns True >>> summary = wellbeing.get_wellbeing_summary() >>> 'life_satisfaction' in summary.columns True Publication Details: - Frequency: Annual (January publication) - Reference period: Financial year (April - March) - Published by: NISRA / The Executive Office - Contact: pfganalytics@executiveoffice-ni.gov.uk - Population: Adults aged 16+ in Northern Ireland Attributes ---------- .. autoapisummary:: bolster.data_sources.nisra.wellbeing.logger bolster.data_sources.nisra.wellbeing.WELLBEING_BASE_URL bolster.data_sources.nisra.wellbeing.EXEC_OFFICE_TOPIC_URL bolster.data_sources.nisra.wellbeing.EXEC_OFFICE_BASE_URL Functions --------- .. autoapisummary:: bolster.data_sources.nisra.wellbeing.get_latest_wellbeing_publication_url bolster.data_sources.nisra.wellbeing.get_wellbeing_file_url bolster.data_sources.nisra.wellbeing.parse_personal_wellbeing bolster.data_sources.nisra.wellbeing.parse_loneliness bolster.data_sources.nisra.wellbeing.parse_self_efficacy bolster.data_sources.nisra.wellbeing.get_latest_personal_wellbeing bolster.data_sources.nisra.wellbeing.get_latest_loneliness bolster.data_sources.nisra.wellbeing.get_latest_self_efficacy bolster.data_sources.nisra.wellbeing.get_wellbeing_summary bolster.data_sources.nisra.wellbeing.get_personal_wellbeing_by_year bolster.data_sources.nisra.wellbeing.validate_personal_wellbeing Module Contents --------------- .. py:data:: logger .. py:data:: WELLBEING_BASE_URL :value: 'https://www.nisra.gov.uk/statistics/wellbeing/individual-wellbeing-northern-ireland' .. py:data:: EXEC_OFFICE_TOPIC_URL :value: 'https://www.executiveoffice-ni.gov.uk/topics/individual-wellbeing-northern-ireland' .. py:data:: EXEC_OFFICE_BASE_URL :value: 'https://www.executiveoffice-ni.gov.uk' .. py:function:: get_latest_wellbeing_publication_url() Get the URL of the latest Individual Wellbeing publication and its year. Scrapes the Executive Office topic page to find the most recent publication. :returns: //...", "2024/25") :rtype: Tuple of (publication_url, year_string) e.g. ("https :raises NISRADataNotFoundError: If unable to find the latest publication .. rubric:: Example >>> url, year = get_latest_wellbeing_publication_url() >>> url.startswith('https://') True .. py:function:: get_wellbeing_file_url(year_str) Construct URL for the wellbeing data tables Excel file. :param year_str: Financial year string (e.g., "2024/25") :returns: URL to the Excel data tables file .. rubric:: Example >>> url = get_wellbeing_file_url("2024/25") >>> url.startswith('https://') True .. py:function:: parse_personal_wellbeing(file_path) Parse personal wellbeing (ONS4) measures from the Excel file. Extracts Life Satisfaction, Worthwhile, Happiness, and Anxiety mean scores from the time series data. :param file_path: Path to the wellbeing data tables Excel file :returns: - year: str (financial year, e.g., "2024/25") - life_satisfaction: float (mean score 0-10) - worthwhile: float (mean score 0-10) - happiness: float (mean score 0-10) - anxiety: float (mean score 0-10, lower is better) :rtype: DataFrame with columns .. rubric:: Example >>> _, year = get_latest_wellbeing_publication_url() >>> path = download_file(get_wellbeing_file_url(year), cache_ttl_hours=90*24) >>> df = parse_personal_wellbeing(path) >>> 'life_satisfaction' in df.columns True .. py:function:: parse_loneliness(file_path) Parse loneliness data from the Excel file. Extracts the proportion of people who feel lonely at least some of the time. :param file_path: Path to the wellbeing data tables Excel file :returns: - year: str (financial year, e.g., "2024/25") - lonely_some_of_time: float (proportion, e.g., 0.179 = 17.9%) - confidence_interval: str (e.g., "+/- 1.1") :rtype: DataFrame with columns .. rubric:: Example >>> _, year = get_latest_wellbeing_publication_url() >>> path = download_file(get_wellbeing_file_url(year), cache_ttl_hours=90*24) >>> df = parse_loneliness(path) >>> 'lonely_some_of_time' in df.columns True .. py:function:: parse_self_efficacy(file_path) Parse self-efficacy data from the Excel file. Self-efficacy measures a person's belief in their capabilities to influence events in their lives. Scores range from 5 to 25. :param file_path: Path to the wellbeing data tables Excel file :returns: - year: str (financial year, e.g., "2024/25") - self_efficacy_mean: float (mean score 5-25) - confidence_interval: str (e.g., "+/- 0.1") :rtype: DataFrame with columns .. rubric:: Example >>> _, year = get_latest_wellbeing_publication_url() >>> path = download_file(get_wellbeing_file_url(year), cache_ttl_hours=90*24) >>> df = parse_self_efficacy(path) >>> 'self_efficacy_mean' in df.columns True .. py:function:: get_latest_personal_wellbeing(force_refresh = False) Get the latest personal wellbeing (ONS4) data. Downloads and parses the latest Individual Wellbeing publication to extract the four ONS personal wellbeing measures: Life Satisfaction, Worthwhile, Happiness, and Anxiety. :param force_refresh: Force re-download even if cached :returns: - year: str (financial year) - life_satisfaction: float (mean 0-10, higher is better) - worthwhile: float (mean 0-10, higher is better) - happiness: float (mean 0-10, higher is better) - anxiety: float (mean 0-10, lower is better) :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_personal_wellbeing() >>> 'life_satisfaction' in df.columns True .. py:function:: get_latest_loneliness(force_refresh = False) Get the latest loneliness data. Downloads and parses the latest Individual Wellbeing publication to extract loneliness statistics (proportion feeling lonely at least some of the time). :param force_refresh: Force re-download even if cached :returns: - year: str (financial year) - lonely_some_of_time: float (proportion) - confidence_interval: str :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_loneliness() >>> 'lonely_some_of_time' in df.columns True .. py:function:: get_latest_self_efficacy(force_refresh = False) Get the latest self-efficacy data. Downloads and parses the latest Individual Wellbeing publication to extract self-efficacy statistics (mean scores 5-25). :param force_refresh: Force re-download even if cached :returns: - year: str (financial year) - self_efficacy_mean: float (mean 5-25) - confidence_interval: str :rtype: DataFrame with columns .. rubric:: Example >>> df = get_latest_self_efficacy() >>> 'self_efficacy_mean' in df.columns True .. py:function:: get_wellbeing_summary(force_refresh = False) Get a summary of all wellbeing measures for the latest year. Combines personal wellbeing (ONS4), loneliness, and self-efficacy data into a single summary for the most recent year. :param force_refresh: Force re-download even if cached :returns: - year: str - life_satisfaction: float - worthwhile: float - happiness: float - anxiety: float - lonely_some_of_time: float - self_efficacy_mean: float :rtype: DataFrame with one row containing .. rubric:: Example >>> summary = get_wellbeing_summary() >>> 'life_satisfaction' in summary.columns True .. py:function:: get_personal_wellbeing_by_year(df, year) Filter personal wellbeing data for a specific year. :param df: DataFrame from get_latest_personal_wellbeing() :param year: Financial year string (e.g., "2024/25") :returns: DataFrame filtered to the specified year .. rubric:: Example >>> df = get_latest_personal_wellbeing() >>> df_2024 = get_personal_wellbeing_by_year(df, "2024/25") >>> 'life_satisfaction' in df_2024.columns True .. py:function:: validate_personal_wellbeing(df) Validate personal wellbeing data for consistency. Checks that: - All ONS4 measures are present - Scores are within expected ranges - No duplicate years :param df: DataFrame from get_latest_personal_wellbeing() :returns: True if validation passes :raises ValueError: If validation fails