Help for package cvdprevent

Type:

Package

Title:

Access and Analyse Data from the 'CVD Prevent' API

Version:

0.2.3

Maintainer:

Craig Parylo <craig.parylo2@nhs.net>

Description:

Provides an R interface to the 'CVD Prevent' application programming interface (API), allowing users to retrieve and analyse cardiovascular disease prevention data from primary care records across England. The Cardiovascular Disease Prevention Audit (CVDPREVENT) automatically extracts routinely held GP health data to support national reporting and improvement initiatives. See the API documentation for details: https://bmchealthdocs.atlassian.net/wiki/spaces/CP/pages/317882369/CVDPREVENT+API+Documentation.

License:

MIT + file LICENSE

URL:

https://github.com/craig-parylo/cvdprevent https://craig-parylo.github.io/cvdprevent/

BugReports:

https://github.com/craig-parylo/cvdprevent/issues

Depends:

R (≥ 4.1.0)

Imports:

cachem, cli, dplyr, glue, httr2, memoise, purrr, rappdirs, tibble, tidyr

Suggests:

ggplot2, gt, knitr, mockery, rmarkdown, testthat (≥ 3.0.0)

VignetteBuilder:

knitr

Config/testthat/edition:

Encoding:

UTF-8

NeedsCompilation:

RoxygenNote:

7.3.3

Packaged:

2025-11-05 20:54:59 UTC; Craig.Parylo

Author:

Craig Parylo

[aut, cre, cph], Cardiovascular Disease Prevention Audit (CVDPREVENT) [ant] (Data provider and audit sponsor)

Repository:

CRAN

Date/Publication:

2025-11-05 23:30:18 UTC

Retrieve details for a specific NHS area and time period

Description

Returns detailed information about a single NHS area for a given reporting period, including its own details, as well as any parent and child areas. This allows you to understand the heirarchical context (e.g., parent ICB, child PCNs or Practices) for the specified area.

Usage

cvd_area_details(time_period_id, area_id)

Arguments

time_period_id

Integer (required). The reporting period for which area details should be returned. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID to return details for. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

This function is useful for navigating NHS area heirarchies, such as finding all practices within a PCN, or determining the parent ICB for a given area. The result is a list of tibbles, so you can extract and work with each component separately.

Value

A named list with up to three tibbles:

area_details: A tibble with details about the specified area.
area_parent_details: A tibble with details about the parent area(s), if available.
area_child_details: A tibble with details about child area(s), if available.

If no data is found, returns a tibble describing the error.

area_details, area_parent_details and area_child_details typically contain the following columns:

AreaCode: Character. ONS or internal code for the NHS area (e.g., "E54000015").
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Full name of the NHS area (e.g., "NHS Leicester, Leicestershire and Rutland Integrated Care Board").
AreaOdsCode: Character. ODS (Organisation Data Service) code for the area (e.g., "QK1").
SystemLevelID: Integer. Unique identifier for the system level (e.g., 7 = ICB).
SystemLevelName: Character. Name of the system level (e.g., "ICB").

API Documentation

See the CVDPREVENT API documentation: Area details

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve details for 'Leicester, Leicestershire and Rutland ICB' (area_id = 8037)
# in time period 17
returned_list <- cvd_area_details(time_period_id = 17, area_id = 8037)

# View details for the area
returned_list$area_details |> dplyr::select(AreaCode, AreaName)

# View details for the parent area(s)
returned_list$area_parent_details |> dplyr::select(AreaID, AreaName, SystemLevelID)

# View details for the child area(s)
returned_list$area_child_details |> dplyr::select(AreaID, AreaName, SystemLevelID)

Retieve flat sub-systems for an NHS area, grouped by system level

Description

Returns a "flat" list of the specified NHS area and all its immediate child areas from the CVDPREVENT API, with child areas grouped by their system level rather than by strict heirarchical nesting. This function provides a convenient overview when you want to see all sub-areas organised by level (e.g., all PCNs and all GP practices beneath an ICB) without traversing the full heirarchy.

The output is a tibble where each row represents an area or sub-area, and child areas are included as columns (with system level information).

Usage

cvd_area_flat_subsystems(area_id)

Arguments

area_id

Integer (required). The AreaID for which to retrieve flat sub-system data. use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

This function is useful for quickly listing all areas beneath a parent, grouped by system level, for reporting or selection purposes. For a fully nested view, see cvd_area_nested_subsystems().

Value

A tibble containing details for the specified area and its child areas and child area details (e.g., via ⁠SubSystems_*⁠ columns). Typical columns include:

AreaCode: Character. Code for the parent NHS area (e.g., "E54000038").
AreaID: Integer. Unique identifier for the parent NHS area.
AreaName: Character. Name of the parent NHS area (e.g., "Somerset").
AreaOdsCode: Character. ODS (Organisation Data Service) code for the parent area (e.g., "QSL").
ParentAreaID: Integer. Identifier for the higher-level parent area (e.g., regional or national grouping).
SubSystems_AreaCode: Character. Code for the subsystem NHS area (e.g., practice or PCN).
SubSystems_AreaID: Integer. Unique identifier for the subsystem NHS area.
SubSystems_AreaName: Character. Name of the subsystem NHS area (e.g., "Church Street Surgery, Martock").
SubSystems_AreaOdsCode: Character. ODS code for the subsystem area, if available. Often blank.
SubSystems_ParentAreaID: Integer. ID of the immediate parent area for the subsystem (e.g., PCN or ICB).
SubSystems_SystemLevelID: Integer. Identifier for the system level of the subsystem (e.g., 5 = Practice, 4 = PCN).
SubSystems_SystemLevelName: Character. Name of the system level for the subsystem (e.g., "Practice", "PCN").
SystemLevelID: Integer. Identifier for the system level of the parent area (e.g., 2 = STP).
SystemLevelName: Character. Name of the system level for the parent area (e.g., "STP").

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Area flat subsystems

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# View flat sub-systems for Somerset STP (area_id = 5)
cvd_area_flat_subsystems(area_id = 5) |> dplyr::glimpse()

# View flat sub-systems for Lincolnshire ICB (area_id = 8042)
cvd_area_flat_subsystems(area_id = 8042) |> dplyr::glimpse()

List NHS areas for a given time period and parent or system level

Description

Retrieves all NHS geographical areas (e.g., England, Region, ICB, PCN, Practice) that have data avialable for a specified reporting period and either a pareent area or system level. Only areas with data for the chosen time period are returned.

You must specify at least one of parent_area_id or system_level_id. If both are provided, parent_area_id takes precedence and system_level_id is ignored.

If parent_area_id is specified, returns all child areas of the specified parent area.
If system_level_id is specified, returns all areas within that system level.

Usage

cvd_area_list(time_period_id, parent_area_id = NULL, system_level_id = NULL)

Arguments

time_period_id

Integer (required). The reporting period ID for which to return areas. Use cvd_time_period_list() to find valid IDs.

parent_area_id

Integer (optional). The AreaID for which all children will be returned. If provided, this takes precedence over system_level_id.

system_level_id

Integer (optional). The system level ID for which to return all areas (e.g., Practice, PCN, ICB). Ignored if parent_area_id is specified. Use cvd_area_system_level() to find valid IDs for a given time period.

Details

At least one of parent_area_id or system_level_id must be supplied, otherwise an error is thrown.
This function is commonly used to list all practices within a given PCN, all PCNs within an ICB, or all areas at a specific system level for a chosen time period.

Value

A tibble containing area details for the specified criteria with the following columns:

AreaCode: Character. ONS code for the NHS area (e.g., "U91471").
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Inclusive Health PCN").
AreaOdsCode: Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
ParticipationRate: Numeric. Percentage of practices or organisations participating in the CVDPREVENT program within the area.
PopulationRate: Numeric. Percentage of the population covered by participating organisations in the area.
SystemLevelID: Integer. Unique identifier for the system level (e.g., 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "PCN").
Parents: Integer. ID of the parent organisation or grouping (e.g., ICB or region).

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Area lists

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List four PCNs (system level 4) with data available at time period 17
cvd_area_list(time_period_id = 17, system_level_id = 4) |>
  dplyr::select(SystemLevelName, AreaID, AreaCode, AreaName) |>
  dplyr::slice_head(n = 4)

# List all child areas of parent area 8037 (e.g., an ICB) in time period 17
cvd_area_list(time_period_id = 17, parent_area_id = 8037)

# Attempting to call without either optional argument will result in a
# tibble explaining the error.
# cvd_area_list(time_period_id = 17)

Retrieve nested sub-systems for an NHS area

Description

Returns a hierarchical (nested) structure of the specified NHS area and all of its descendent (child) areas from the CVDPREVENT API. This function is useful for exploring the parent-child relationships within NHS geographies, such as seeing a PCN and all of its practices, or an ICB with all subordinate structures.

The output is a list of tibbles, one for each "level" in the heirarchy, named as level_1, level_2, etc. Each tibble contains the details for the areas at that level.

Usage

cvd_area_nested_subsystems(area_id)

Arguments

area_id

Integer (required). The AreaID for which to retrieve nested sub-system data. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

This function is helpful for visualising or programmatically traversing the full nested structure beneath a given NHS area. For example, given an ICB, you can see all PCNs, then all practices beneath those PCNs, and so on.

Value

A named list of tibbles, where each element (level_1, level_2, etc.) contains details for the specified area and each subsequent child level. If no data is found, returns a tibble describing the error.

Each tibble contains the following columns:

AreaCode: Character. Unique code for the NHS area (e.g., "U11103").
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Yeovil PCN").
AreaOdsCode: Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
ParentAreaID: Integer. ID of the parent NHS area or organisation (e.g., ICB or region).
SystemLevelID: Integer. Identifier for the system level (e.g., 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "PCN").

API Documentation

See the CVDPREVENT API documentation: Area nested subsystems

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# View the nested structure for Somerset STP (area_id = 5)
returned_list <- cvd_area_nested_subsystems(area_id = 5)
returned_list |> summary()

# See details for the first five immediate children of Somerset STP
returned_list$level_2 |> dplyr::slice_head(n = 5)

# View the nested structure for Leicester Central PCN (area_id = 701)
returned_list <- cvd_area_nested_subsystems(area_id = 701)
returned_list |> summary()

# See the GP practice children of the PCN
returned_list$level_2

Search for NHS areas by partial name and time period

Description

Searches for NHS areas whose names match a given partial string, within a specified reporting time period. This function uses a case-insensitive "LIKE" search (i.e., matches any area containing the search term) and returns only areas for which data is available in the specified period.

Usage

cvd_area_search(partial_area_name, time_period_id)

Arguments

partial_area_name

String (required). The substring to search for within area names (case-insensitive). This may be any part of an area name, e.g., "practice", "PCN", or a specific place.

time_period_id

Integer (required). The reporting period (time period) to restrict the search to areas with data. use cvd_time_period_list() to obtain valid IDs.

Details

The search is case-insensitive and matches anywhere in the area name.
Only areas with available data in the chosen time period will be returned.
Use this function to quickly locate AreaIDs or codes for use in other cvdprevent API calls.

Value

A tibble containing details of areas matching the search term and having data for the specified time period. Typical columns include:

AreaCode: Character. Unique code for the NHS area (e.g., "P86619").
AreaID: Integer. Unique identifier for the NHS area
AreaName: Character. Name of the NHS area (e.g., "Dr Mb Ghafoor & Partners").
IsVisible: Logical or character. Indicates whether the area is visible in the API or dashboard ("Y" or "N").
NationalLevel: Logical or character. Indicates whether the area is included in national-level aggregations ("Y" or "N").
OdsCode: Character. ODS (Organisation Data Service) code for the area, if available. Often blank.
SystemLevelID: Integer. Identifier for the system level (5 = GP Practices).
SystemLevelName: Character. Name of the system level (e.g., "Practice").
SystemLevelOrder: Integer. Display order for the system level in dashboards or reports.

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Area search

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Search for areas containing "practice" in their name for time period 17
cvd_area_search(partial_area_name = "practice", time_period_id = 17) |>
  dplyr::select(AreaID, AreaName, AreaCode)

# Search for areas containing "PCN" for time period 17
cvd_area_search(partial_area_name = "PCN", time_period_id = 17) |>
  dplyr::select(AreaID, AreaName, AreaCode)

List system levels available for a specific time period

Description

Retrieves all available NHS system levels (e.g., National, Region, ICB, PCN, Practice) for a specified reporting time period from the CVDPREVENT API.

This function helps users determine which system levels are available for data extraction in a given reporting period.

Usage

cvd_area_system_level(time_period_id)

Arguments

time_period_id

Integer (required). The ID of the reporting time period for which system levels should be returned. Use cvd_time_period_list() to find valid IDs.

Details

This function is useful in workflows where you need to filter or subset NHS areas or data by both time period and system level. It is often used as a precursor to more detailed area or indicator queries.

Value

A tibble containing system level details for the specified time period, with the following columns:

IsVisible: Logical or character. Indicates whether the system level is visible in the API or dashboard ("Y" or "N").
NationalLevel: Logical or character. Indicates whether the system level represents national coverage ("Y" or "N").
SystemLevelID: Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "England", "Region", "ICB", "Practice").
SystemLevelOrder: Integer. Display order for the system level in dashboards or reports.

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: System levels per time period

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List all system levels available for time period 4 (activity to March 2022)
cvd_area_system_level(time_period_id = 4) |>
  dplyr::select(SystemLevelID, SystemLevelName)

# Find valid time period IDs, then get system levels for the latest one
latest_period <-
  cvd_time_period_list() |>
  dplyr::pull(TimePeriodID) |>
  max()

cvd_area_system_level(time_period_id = latest_period) |>
  dplyr::select(SystemLevelID, SystemLevelName)

List all system levels and their available time periods

Description

Retrieves all available NHS system levels from the CVDPREVENT API, along with the reporting periods (time periods) in which each system level has data available.

This function is the inverse of cvd_time_period_system_levels(), allowing you to see, for each system level (e.g., National, Region, ICB, PCN, Practice), the set of time periods for which data exists.

Usage

cvd_area_system_level_time_periods()

Details

Use this function to determine which reporting periods are available for each NHS system level. This is useful for dynamically generating data selections or validating user input in dashboards or scripts.

Value

A tibble with one row per system level and time period, with the following columns:

IsVisible: Logical or character. Indicates whether the time period is visible in the API or dashboard ("Y" or "N").
NationalLevel: Logical or character. Indicates whether the data is available at the national level ("Y" or "N").
SystemLevelID: Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "England", "ICB", "Sub-ICB", "STP").
EndDate: POSIXct. End date of the reporting period (e.g., "2023-06-30").
StartDate: POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
TimePeriodID: Integer. Unique identifier for the time period.
TimePeriodName: Character. Display label for the time period (e.g., "To June 2025", "Apr 2022 – Mar 2023").

If no data is found, returns a tibble describing the error.

API Documentation

CVDPREVENT API documentation: All system levels and time periods for details.

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List the latest four reporting periods at GP practice level
cvd_area_system_level_time_periods() |>
  dplyr::filter(SystemLevelName == "Practice") |>
  dplyr::slice_max(order_by = TimePeriodID, n = 4) |>
  dplyr::select(SystemLevelName, TimePeriodID, TimePeriodName)

# Explore all system levels and their available time periods
cvd_area_system_level_time_periods()

List NHS areas without parent assignments for a given time period

Description

Retrieves all NHS areas that have data in the specified reporting time period but do not have any parent areas assigned. These "unassigned" areas are unreachable via standard heirarchical navigation and may represent data issues or exceptional cases (e.g., England as the highest-level system).

Usage

cvd_area_unassigned(time_period_id, system_level_id = NULL)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to find unassigned areas. Use cvd_time_period_list() to obtain valid IDs.

system_level_id

Integer (optional). Restrict the search to areas at a specific system level (e.g., Practice, PCN, ICB). Use cvd_area_system_level() to find valid IDs for a given time period.

Details

Use this function to identify "orphaned" NHS areas or to understand top-level areas (e.g., England).
If system_level_id = 1 (England), expect the only result to be England, since it has no parent.
This can help with data quality checks or to ensure all areas are accessible via parent/child navigation.

Value

A tibble containing details for all areas without parent assignments in the selected time period (and system level, if specified). Typical columns include:

AreaCode: Character. Unique code for the NHS area (e.g., "L81117").
AreaID: Integer. Unique identifier for the NHS area
AreaName: Character. Name of the NHS area (e.g., "Pilning Surgery").
OdsCode: Character. ODS (Organisation Data Service) code for the practice, if available. Often blank.
SystemLevelID: Integer. Identifier for the system level (5 = GP practices).
SystemLevelName: Character. Name of the system level (e.g., "Practice").

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Areas unassigned

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Report four GP practices (system level ID = 5) without parent PCN details for time period 17:
cvd_area_unassigned(time_period_id = 17, system_level_id = 5) |>
  dplyr::slice_head(n = 4) |>
  dplyr::select(SystemLevelName, AreaID, AreaName)

# List unassigned top-level areas (system level ID = 1, England) for time period 17:
cvd_area_unassigned(time_period_id = 17, system_level_id = 1) |>
  dplyr::select(SystemLevelName, AreaID, AreaName)

Data availability

Description

Returns the data availability. Response: DataAvailabilityID - ID of the resource as found in the database DataAvailabilityName - explanation for the data availability IsAvailable - Y for data is available, N for data is unavailable, and NULL for unknown data

Usage

cvd_data_availability(
  time_period_id,
  system_level_id,
  indicator_id = NULL,
  metric_category_type_id = NULL
)

Arguments

time_period_id

integer - the time period to return data for (compulsory)

system_level_id

integer - the system level to return data for (compulsory)

indicator_id

integer - the indicator to return data for (optional)

metric_category_type_id

integer - the metric category to return data for (optional)

Details

CVD Prevent API documentation: Data availability

Value

Tibble of data availability

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


cvd_data_availability(time_period_id = 3, system_level_id = 5)

Retrieve metadata for external resources linked to CVDPREVENT

Description

Returns a tibble containing metadata for all external resources referenced by the CVDPREVENT programme. These resources may include clinical guidelines, research papers, policy documents, and third-party datasets used to support indicator definitions and reporting.

Usage

cvd_external_resource()

Details

Each resource is categorised and includes source information, title, and descriptive metadata. This function is useful for:

Auditing external references used in CVDPREVENT indicators
Linking indicators to supporting evidence or policy
Building documentation or dashboards that reference external sources

Value

A tibble where each row represents an external resource referenced by CVDPREVENT. Columns include:

ExternalResourceCategory

Character. Thematic category of the resource (e.g., "Toolkits", "Resources for patients").

ExternalResourceID

Integer. Unique identifier for the resource.

ExternalResourceOrder

Integer. Display order for the resource within its category.

ExternalResourceSource

Character. Organisation or publisher of the resource (e.g., "NHS England", "UCLPartners").

ExternalResourceTitle

Character. Title of the resource (e.g., "Cardiovascular Disease Prevention Data Packs").

ExternalResourceType

Character. Type of resource (e.g., "website", "document").

ExternalResourceURL

Character. Direct URL to the resource.

Tags

List-column of data frames. Each entry contains one or more indicator tags associated with the resource, including:

IndicatorTagID: Integer. Unique identifier for the tag.
IndicatorTagName: Character. Descriptive name of the tag (e.g., "prevention", "digital tools").

May be empty or contain NA if no tags are assigned.

If the request fails, a tibble describing the error is returned instead.

API Documentation

See the CVDPREVENT API documentation: External resources

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Show the first five external resources grouped by category
cvd_external_resource() |>
  dplyr::filter(ExternalResourceID < 10) |>
  dplyr::select(ExternalResourceCategory, ExternalResourceSource, ExternalResourceTitle) |>
  dplyr::group_by(ExternalResourceCategory)

Retrieve all indicators and their data for a given time period and area

Description

Returns all CVD indicators and related data for a specified reporting period (time_period_id) and NHS area (area_id) from the CVDPREVENT API. Also retrieves time series data for all available periods. Optionally, you can filter results by one or more indicator tags.

The returned object is a named list of tibbles, including details about indicators, metric categories, metric data and time series, making this function ideal for comprehensive data extraction and downstream analysis.

Usage

cvd_indicator(time_period_id, area_id, tag_id = NULL)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to return indicator data. Use the cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID for which to return indicator data. Use cvd_area_list() or cvd_area_search() to find valid IDs.

tag_id

Numeric vector (optional). One or more tag IDs to filter indicators by tag. Use cvd_indicator_tags() to find valid IDs.

Details

This function is useful for extracting all indicator data for a given area and period, including breakdowns by category and time series. The list output allows easy access to different data tables for further analysis or visualisation. Filtering by tag enables targeted queries for specific subsets of indicators.

Value

A named list containing up to four tibbles:

indicators: Tibble of indicators for the area and time period.
metric_categories: Tibble of metric categories related to the indicators.
metric_data: Tibble of metric values for the area and indicators.
timeseries_data: Tibble of time series data for metrics and indicators across time periods.

If no indicators are found, returns a tibble describing the error.

indicators contains the following columns:

AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
DataUpdateInterval: Character. Frequency or interval at which the indicator data is updated. Often blank.
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP009CHOL").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
IndicatorStatus: Character. Status of the indicator (e.g., active, discontinued). Often blank.
IndicatorTypeID: Integer. Unique identifier for the indicator type (e.g., 1 = Standard).
IndicatorTypeName: Character. Name of the indicator type (e.g., "Standard").
NotificationCount: Integer. Count of notifications associated with the indicator.

metric_categories contains the following columns:

IndicatorID: Integer. Unique identifier for the indicator. Links to the corresponding entry in the indicators table.
CategoryAttribute: Character. Grouping label used to define the population subset (e.g., "Male", "Persons").
MetricCategoryID: Integer. Unique identifier for the metric category.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "80+", "Mixed", "Female").
MetricCategoryOrder: Integer. Display order for the category within its type.
MetricCategoryTypeName: Character. Type of category used for breakdown (e.g., "Age group", "Sex", "Ethnicity").
MetricID: Integer. Unique identifier for the specific metric instance.

metric_data contains the following columns:

MetricID: Integer. Unique identifier for the metric instance. Links to the corresponding entry in the metric categories table.
AreaID: Integer. Unique identifier for the NHS area.
Count: Integer. Number of records included in the calculation.
DataID: Integer. Unique identifier for the data point.
Denominator: Numeric. Denominator used in the metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often blank.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval.
Max: Numeric. Maximum observed value for the metric.
Median: Numeric. Median value for the metric.
Min: Numeric. Minimum observed value for the metric.
Numerator: Numeric. Numerator used in the metric calculation.
Q20: Numeric. 20th percentile value.
Q40: Numeric. 40th percentile value.
Q60: Numeric. 60th percentile value.
Q80: Numeric. 80th percentile value.
TimePeriodID: Integer. Identifier for the time period associated with the metric.
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval.
Value: Numeric. Final calculated value for the metric.
ValueNote: Character. Notes or flags associated with the value (e.g., suppression warnings).

timeseries_data contains the following columns:

MetricID: Integer. Unique identifier for the metric instance. Links to the corresponding entry in the metric data table.
EndDate: POSIXct. End date of the reporting period (e.g., "2025-06-30").
Median: Numeric. Median value for the metric during the specified time period.
StartDate: POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
TimePeriodID: Integer. Unique identifier for the time period.
TimePeriodName: Character. Display label for the time period (e.g., "To June 2025").
Value: Numeric. Final calculated value for the metric in the given time period.

API Documentation

See the CVDPREVENT API documentation: Indicator

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Get all indicator data for area_id = 1103 in time period 17
return_list <- cvd_indicator(time_period_id = 17, area_id = 1103)

# See what data tables are available
summary(return_list)

# Extract and examine indicators
indicators <- return_list$indicators
indicators |>
  dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |>
  dplyr::arrange(IndicatorID) |>
  dplyr::slice_head(n = 4)

# Extract metric categories for a specific indicator and categories
categories <- return_list$metric_categories
categories |>
  dplyr::filter(IndicatorID == 7, MetricCategoryID %in% c(7, 8)) |>
  dplyr::select(
    IndicatorID,
    MetricCategoryTypeName,
    CategoryAttribute,
    MetricCategoryName,
    MetricID
  )

# Extract metric data for specific metrics
metric_data <- return_list$metric_data
metric_data |>
  dplyr::filter(MetricID %in% c(126, 132)) |>
  dplyr::select(MetricID, Value, Numerator, Denominator)

# Extract time series data for selected metrics
timeseries_data <- return_list$timeseries_data
timeseries_data |>
  dplyr::filter(MetricID %in% c(126, 132), !is.na(Value))

# Filter by tags: get indicators tagged with either tag 3 or 4 in area 3, time period 17
return_list <- cvd_indicator(time_period_id = 17, area_id = 3, tag_id = c(3, 4))

Retrieve child area data for a specific metric, time period and area

Description

Returns the value of a single metric for all child areas of a specified NHS area (and the specified area itself) for a chosen reporting period, using the CVDPREVENT API. This function enables direct comparison of a specific metric across all subordinate areas (e.g., all GP practices within a PCN, or all PCNs within an ICB).

Only the selected metric is returned for each child area.

Usage

cvd_indicator_child_data(time_period_id, area_id, metric_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to return child data. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID for which to find child areas. Use cvd_area_list() or cvd_area_search() to find valid IDs.

metric_id

Integer (required). The MetricID for which to retrieve values. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid MetricIDs.

Details

Use this function to compare a metric across all immediate child areas under a parent (for example, to benchmark all GP practices within a PCN for a specific indicator and reporting period).

Value

A tibble with the value of the specified metric for the given area and all its child areas, for the specified time period. Columns include:

CategoryAttribute: Character. Grouping label used to define the population subset (e.g., "Male").
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
MetricCategoryID: Integer. Unique identifier for the metric category.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "40–59").
MetricCategoryOrder: Integer. Display order for the category within its type.
MetricCategoryTypeName: Character. Type of category used for breakdown (e.g., "Age group").
AreaCode: Character. Code for the child NHS area (e.g., PCN).
AreaID: Integer. Unique identifier for the child NHS area.
AreaName: Character. Name of the child NHS area (e.g., "Teldoc PCN").
Count: Integer. Number of records included in the calculation.
DataID: Integer. Unique identifier for the data point.
Denominator: Numeric. Denominator used in the metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often blank.
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval.
Max: Numeric. Maximum observed value for the metric.
Median: Numeric. Median value for the metric.
Min: Numeric. Minimum observed value for the metric.
NotificationCount: Integer. Count of notifications associated with the indicator.
Numerator: Numeric. Numerator used in the metric calculation.
Q20: Numeric. 20th percentile value.
Q40: Numeric. 40th percentile value.
Q60: Numeric. 60th percentile value.
Q80: Numeric. 80th percentile value.
SystemLevelID: Integer. Identifier for the system level (e.g., 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "PCN").
TimePeriodID: Integer. Identifier for the time period associated with the metric.
TimePeriodName: Character. Display label for the time period (e.g., "To March 2024").
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval.
Value: Numeric. Final calculated value for the metric.
ValueNote: Character. Notes or flags associated with the value (e.g., suppression warnings).

If no child data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator child data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Compare the value of metric 126 for area 74 and all its child areas in time period 22
cvd_indicator_child_data(time_period_id = 22, area_id = 74, metric_id = 126) |>
  dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit)

# Find a valid metric ID for an indicator, then get child area data
metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5)
metric_id <- metrics$MetricID[1]
cvd_indicator_child_data(time_period_id = 17, area_id = 1103, metric_id = metric_id)

Retrieve CVD indicator data for a specific area and time period

Description

Fetches all available metric breakdowns for a single cardiovascular disease (CVD) indicator from the CVDPREVENT API, scoped to a specified NHS area and reporting period. This includes subgroup data such as age, sex, ethnicity, deprivation quintile, and more.

Usage

cvd_indicator_data(time_period_id, area_id, indicator_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) to retrieve data for. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID for which to retrieve indicator data. use cvd_area_list() or cvd_area_search() to find valid IDs.

indicator_id

Integer (required). The IndicatorID for which to retrieve data. use cvd_indicator_list() or cvd_indicator_metric_list() to find valid IDs.

Details

Use this function to obtain all metric values for a single indicator in a particular area and time period, such as for a local dashboard or a focussed report. For broader queries across multiple indicators, see cvd_indicator() or cvd_indicator_metric_list().

Value

A named list containing three tibbles:

indicator_metrics: Tibble. Metadata and definitions for the selected indicator and its associated metrics.
area_data: Tibble. Metric values for the specified NHS area (area_id) across all available breakdowns.
national_data: Tibble. Metric values for England, used for benchmarking and comparison.

If no indicator data is found, returns a tibble describing the error.

indicator_metrics contains the following items:

AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display.
NotificationCount: Integer. Count of notifications associated with the indicator. Often zero.
TimePeriodID: Integer. ID of the reporting time period.
TimePeriodName: Character. Label for the reporting time period (e.g., "To March 2024").
CategoryAttribute: Character. Subgroup label (e.g., "Male", "Female", "Persons").
MetricCategoryID: Integer. Unique ID for the metric category.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "18–39", "Sex").
MetricCategoryOrder: Integer. Display order for the metric category.
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Age group", "Sex").
MetricID: Integer. Unique ID for the specific metric being measured.

area_data and national_data contain the following items:

MetricID: Integer. Unique identifier for the metric being measured.
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Sex", "Age group").
MetricCategoryName: Character. Name of the subgroup (e.g., "Female", "18–39").
CategoryAttribute: Character. Label used to group individuals (e.g., "Male", "Persons").
AreaCode: Character. ONS code for the NHS area (e.g., "U60176").
AreaID: Integer. Internal ID for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "3 Centres PCN").
Count: Integer. Total number of individuals in the subgroup.
DataID: Integer. Unique identifier for the data record.
Denominator: Numeric. Population or count used as the denominator in metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often NA.
HighestPriorityNotificationType: Character. Notification priority level, if available. Often NA.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval for the metric value.
Max: Numeric. Maximum observed value for the metric across comparable areas.
Median: Numeric. Median value for the metric across comparable areas.
Min: Numeric. Minimum observed value for the metric across comparable areas.
NotificationCount: Integer. Count of notifications associated with the indicator. Often zero.
Numerator: Numeric. Count used as the numerator in metric calculation.
Q20: Numeric. 20th percentile value across comparable areas.
Q40: Numeric. 40th percentile value across comparable areas.
Q60: Numeric. 60th percentile value across comparable areas.
Q80: Numeric. 80th percentile value across comparable areas.
TimePeriodID: Integer. ID of the reporting time period.
TimePeriodName: Character. Label for the reporting time period (e.g., "To March 2024").
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval for the metric value.
Value: Numeric. Calculated metric value (e.g., percentage of patients treated).
ValueNote: Character. Additional notes or flags about the value. Often NA.

API Documentation

See the CVDPREVENT API documentation: Indicator data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve all metric breakdowns for indicator 7 in area 1103 for time period 17
returned_list <- cvd_indicator_data(time_period_id = 17, area_id = 1103, indicator_id = 7)

# See the structure of this data
returned_list |> dplyr::glimpse()

# See the definition for one metric
returned_list$indicator_metrics |>
  dplyr::slice_head(n = 1) |>
  dplyr::glimpse()

# Compare performance in the specified area (AreaID = 1103) with national results for
# women aged 40-59 years (MetricID = 132)
dplyr::bind_rows(
  returned_list$area_data,
  returned_list$national_data
) |>
dplyr::filter(MetricID == 132)

Retrieve details for a specific indicator

Description

Returns metadata and descriptive information for a single CVD indicator, identified by its IndicatorID, from the CVDPREVENT API. This function allows you to programmatically access the definitions, titles and metadata fields associated with specific indicators for use in reporting, dashboards or documentation.

Usage

cvd_indicator_details(indicator_id)

Arguments

indicator_id

Integer (required). The IndicatorID for which to return details. Use cvd_indicator_list() or cvd_indicator_metric_list() to find valid IDs.

Details

Use this function to retrieve indicator definitions, full names, and metadata fields for use in custom reports or to provide documentation / tooltips in analytical applications. Metadata fields are unnested for convenience.

Value

A tibble containing metadata and details for the specified indicator containing the following columns:

IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
NotificationCount: Integer. Count of notifications associated with the indicator.
AgeStandardised: Character. Indicates whether the indicator is age-standardised ("Y" or "N").
CategoryName: Character. Section heading or thematic grouping for the metadata (e.g., "Section 2: Data and Construction").
MetaData: Character. Detailed explanatory text or notes associated with the indicator. May include rationale, definitions, sources, or caveats.
MetaDataCategoryID: Integer. Unique identifier for the metadata category.
MetaDataTitle: Character. Title or label describing the metadata content (e.g., "Rationale", "Disclosure control").

If no indicator details are found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator details

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve details for indicator with ID 7
cvd_indicator_details(indicator_id = 7) |>
  dplyr::select(IndicatorID, MetaDataTitle, MetaData) |>
  dplyr::slice_head(n = 5)

# Find a valid indicator ID, then get its details
indicators <- cvd_indicator_list(time_period_id = 17, system_level_id = 5)
cvd_indicator_details(indicator_id = indicators$IndicatorID[1])

Retrieve indicators for a specified indicator group

Description

Returns a tibble of indicators belonging to a single indicator group, identified by its group ID. Indicator groups are thematic collections of indicators used throughout CVDPREVENT reporting, such as "Monitoring", "Diagnosis", or "Management". This function enables users to explore the structure and contents of these groups, including their type and display order.

Usage

cvd_indicator_group(indicator_group_id)

Arguments

indicator_group_id

Integer (required). The ID of the indicator group to retrieve.

Details

Indicator groups are defined in the CVDPREVENT IndicatorGroup table and include metadata such as:

IndicatorGroupName: the name of the group (e.g., "Monitoring")
IndicatorGroupTypeID: the type of group (e.g., Priority Group, Key Question Group)
IndicatorGroupTypeName: the readable label for the group type

Each group contains an array of indicators, which are returned with their associated metadata. This function is useful for:

Exploring which indicators belong to a specific clinical theme
Building dashboards or reports based on grouped indicators
Understanding how indicators are organised within the CVDPREVENT framework

To find valid indicator_group_id values, use cvd_indicator_priority_groups().

Value

A tibble where each row represents an indicator within the specified indicator group. Columns include:

IndicatorGroupID: Integer. Unique identifier for the indicator group (e.g., 1 for "ABC").
IndicatorGroupName: Character. Name of the indicator group (e.g., "Prevalence", "Smoking and BMI").
IndicatorGroupTypeID: Integer. Identifier for the type of indicator group (e.g., 1 = Priority Group).
IndicatorGroupTypeName: Character. Descriptive name of the group type (e.g., "Priority Group").
DisplayOrder: Integer. Display order of the indicator within the group.
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red", "Blue"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP004HYP").
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
MetricID: Integer. Unique identifier for the associated metric.
NotificationCount: Integer. Count of notifications associated with the indicator.

If the request fails or the ID is invalid, a tibble with error details is returned instead.

API Documentation

See the CVDPREVENT API documentation: indicator group

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


#  list the indicators under Indicator Group ID 13 (Monitoring) which lists
# 'Key Question' Indicator Group indicators:
cvd_indicator_group(indicator_group_id = 13) |>
  dplyr::select(IndicatorGroupID, IndicatorGroupName, IndicatorGroupTypeName,
  IndicatorID, IndicatorName)

List available indicators for a system level and time period

Description

Retrieves basic details for all CVD indicators available for a given system level and reportion period from the CVDPREVENT API. Only indicators with data for the selected time period and system level are returned. This function is commonly used to populate indicator pickers or to discover what data is available for further queries.

Usage

cvd_indicator_list(time_period_id, system_level_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to return indicators. Use cvd_time_period_list() to find valid IDs.

system_level_id

Integer (required). The system level (e.g., National, Region, ICB, PCN, Practice) for which to return indicators. Use cvd_area_system_level() to find valid IDs for a given time period.

Details

Use this function to discover which indicators are available for a specific combination of system level and time period. The results can be joined with other outputs for further analysis, or used as the basis for more detailed indicator, metric, or data queries.

Value

A tibble with one row per available indicator for the specified system level and time period. Typical columns include:

AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
DataUpdateInterval: Character. Frequency or interval at which the indicator data is updated. Often blank.
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP005CKD").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
IndicatorStatus: Character. Status of the indicator (e.g., active, retired). Often blank.
NotificationCount: Integer. Count of notifications associated with the indicator.

If no indicators are found, returns a tibble describing the error.

API Docuemtnation

See the CVDPREVENT API documentation: Indicator list

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List four indicators for time period 17 and GP practice level (system level 5)
cvd_indicator_list(time_period_id = 17, system_level_id = 5) |>
  dplyr::select(IndicatorID, IndicatorCode, IndicatorShortName) |>
  dplyr::slice_head(n = 4)

# Find valid time period and system level IDs, then list all available indicators
valid_periods <- cvd_time_period_list()
valid_levels <- cvd_area_system_level(time_period_id = 17)
cvd_indicator_list(time_period_id = 17, system_level_id = valid_levels$SystemLevelID[1])

Compare metric performance for an area against national and system-level peers

Description

Returns a tibble showing the performance of a specified metric for a given NHS area, alongside national-level data and other areas within the same system level (e.g., PCNs within an ICB). This function powers the Area Breakdown chart in CVDPREVENT reporting.

Usage

cvd_indicator_metric_area_breakdown(time_period_id, area_id, metric_id)

Arguments

time_period_id

Integer (required). The ID of the reporting period. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The ID of the NHS area to anchor the comparison. Use cvd_area_list() or cvd_area_search() to find valid IDs.

metric_id

Integer (required). The ID of the metric to retrieve. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid IDs.

Details

The output includes:

Metric values for the selected area
Comparison with national performance (AreaID = 1)
Peer areas within the same system level
Target thresholds (if defined)

This function is useful for:

Benchmarking local performance against national and peer averages
Identifying variation within a system level
Supporting targeted improvement and equity analysis

To find valid metric_id values, use cvd_indicator_metric_list() or cvd_indicator_data(). For valid area_id values, use cvd_area_list() or cvd_area_search(). For valid time_period_id values, use cvd_time_period_list().

Value

A tibble comparing metric performance for a specified NHS area and the national aggregate. Each row represents one area (local or national) and includes the following columns:

NationalLevel: Character. Indicates whether the row represents national-level data ("Y" for national, "N" for local).
SystemLevelID: Integer. Identifier for the system level (e.g., 1 = England, 4 = PCN).
SystemLevelMedian: Numeric. Median value for the metric across all areas in the system level.
SystemLevelName: Character. Name of the system level (e.g., "England", "PCN").
SystemLevelOrder: Integer. Display order for the system level.
TargetLabel: Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
TargetValue: Numeric. Target value to be achieved (e.g., 95).
AreaCode: Character. Code for the NHS area (e.g., "U60510" for a PCN, "E92000001" for England).
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Salford South East PCN").
Value: Numeric. Final calculated value for the metric in the area.

If no data is available for the given parameters, a tibble describing the error is returned.

API Documentation

See the CVDPREVENT API documentation: Indicator metric area breakdown

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Compare performance for metric ID 128 in time period 17 for
# Salford South East PCN (area ID 705)
cvd_indicator_metric_area_breakdown(
  metric_id = 128,
  time_period_id = 17,
  area_id = 705
) |>
  dplyr::select(SystemLevelName, AreaID, AreaName, Value)

Retrieve metric data for a specific metric, time period and area

Description

Returns detailed area data for a single CVD metric (metric_id) for a specified NHS area (area_id) and reporting period (time_period_id) from the CVDPREVENT API. This function provides all values and breakdowns available for the selected metric within the chosen context, allowing analysis and visualisation of precise, granular results (e.g., age groups, sexes, ethnicities).

Usage

cvd_indicator_metric_data(metric_id, time_period_id, area_id)

Arguments

metric_id

Integer (required). The MetricID for which to retrieve values. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid MetricIDs.

time_period_id

Integer (required). The reporting period (time period) for which to return metric data. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID for which to return metric data. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

Use this function to retrieve all available breakdowns for a metric in a specific area and period, such as for in-depth local reporting, dashboard figures, or subgroup analysis. It is best used when you know the exact metric required for your query.

Value

A named list containing three tibbles:

metrics: Tibble. Metadata and definitions for the selected metric.
area_data: Tibble. Metric values for the specified NHS area (area_id).
national_data: Tibble. Metric values for England, used for benchmarking and comparison.

If no indicator data is found, returns a tibble describing the error.

indicator_metrics contains the following items:

AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display.
NotificationCount: Integer. Count of notifications associated with the indicator. Often zero.
TimePeriodID: Integer. ID of the reporting time period.
TimePeriodName: Character. Label for the reporting time period (e.g., "To March 2024").
CategoryAttribute: Character. Subgroup label (e.g., "Male", "Female", "Persons").
MetricCategoryID: Integer. Unique ID for the metric category.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "18–39", "Sex").
MetricCategoryOrder: Integer. Display order for the metric category.
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Age group", "Sex").
MetricID: Integer. Unique ID for the specific metric being measured.

area_data and national_data contain the following items:

MetricID: Integer. Unique identifier for the metric being measured.
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Sex", "Age group").
MetricCategoryName: Character. Name of the subgroup (e.g., "Female", "18–39").
CategoryAttribute: Character. Label used to group individuals (e.g., "Male", "Persons").
AreaCode: Character. ONS code for the NHS area (e.g., "U60176").
AreaID: Integer. Internal ID for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "3 Centres PCN").
Count: Integer. Total number of individuals in the subgroup.
DataID: Integer. Unique identifier for the data record.
Denominator: Numeric. Population or count used as the denominator in metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often NA.
HighestPriorityNotificationType: Character. Notification priority level, if available. Often NA.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval for the metric value.
Max: Numeric. Maximum observed value for the metric across comparable areas.
Median: Numeric. Median value for the metric across comparable areas.
Min: Numeric. Minimum observed value for the metric across comparable areas.
NotificationCount: Integer. Count of notifications associated with the indicator. Often zero.
Numerator: Numeric. Count used as the numerator in metric calculation.
Q20: Numeric. 20th percentile value across comparable areas.
Q40: Numeric. 40th percentile value across comparable areas.
Q60: Numeric. 60th percentile value across comparable areas.
Q80: Numeric. 80th percentile value across comparable areas.
TimePeriodID: Integer. ID of the reporting time period.
TimePeriodName: Character. Label for the reporting time period (e.g., "To March 2024").
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval for the metric value.
Value: Numeric. Calculated metric value (e.g., percentage of patients treated).
ValueNote: Character. Additional notes or flags about the value. Often NA.

API Documentation

See the CVDPREVENT API documentation: Indicator metric data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve  a single metric breakdown showing how men aged 40-59 years
# are treated with anticoagulants (MetricID = 126) for 3 Centres PCN
# (AreaID = 1103) to March 2020 (TimePeriodID = 1)
returned_list <- cvd_indicator_metric_data(
  time_period_id = 1,
  area_id = 1103,
  metric_id = 126
)

# See the structure of this data
returned_list |> dplyr::glimpse()

# See the definition for this metric
returned_list$metrics |> dplyr::glimpse()

# Compare performance between our area and the national average
dplyr::bind_rows(
  returned_list$area_data,
  returned_list$national_data
) |>
dplyr::glimpse()

List indicators and associated metrics for a system level and time period

Description

Retrieves all CVD indicators available for a given reporting period and given system level from the CVDPREVENT API, with an expanded view that includes 'MetricList' array for each indicator. This allows you to see not only which indicators are available, but also the specific metrics (e.g., breakdowns by age, sex or other attributes) associated with each indicator in the selected context.

Only indicators with available data for the specified time period and system level are returned. This function is useful for determining what granular metric breakdowns are provided for each indicator.

Usage

cvd_indicator_metric_list(time_period_id, system_level_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to return indicators and metrics. use cvd_time_period_list() to find valid IDs.

system_level_id

Integer (required). The system level (e.g., National, Region, ICB, PCN, Practice) for which to return indicators and metrics. Use cvd_area_system_level() to find valid IDs for a given time period.

Details

Use this function to explore the detailed metric breakdowns available for each indicator before performing data extraction or analysis. The MetricList column is unnested for convenience, so each row represents a single metric linked to an indicator.

Value

A tibble containing one row for each indicator-metric pair avialable for the specified system level and time period. Columns typically include:

AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002SMOK").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
NotificationCount: Integer. Count of notifications associated with the indicator.
CategoryAttribute: Character. Label used to group individuals (e.g., "Male", "Persons").
MetricCategoryName: Character. Name of the subgroup or category (e.g., "40–59", "Mixed").
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Age group", "Sex", "Ethnicity").
MetricID: Integer. Unique identifier for the specific metric being measured.

If no indicators or metrics are found returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator metric list

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List metrics for the prevalence of atrial fibrillation (indicator ID 1),
# focusing on metrics for the 40-59 years age group at the national level:
cvd_indicator_metric_list(time_period_id = 17, system_level_id = 1) |>
  dplyr::filter(IndicatorID == 1, MetricCategoryName == "40-59") |>
  dplyr::count(IndicatorID, IndicatorShortName, MetricID, MetricCategoryName, CategoryAttribute) |>
  dplyr::select(-n)

# Get all indicator-metric pairs for GP practice level (system level 5) in a given period
cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5)

Compare metric performance across system-level areas

Description

Returns a tibble comparing the performance of a specified metric across all areas within the same system level (e.g., all PCNs within an ICB) for a given time period. This function powers the System Level Comparison chart in CVDPREVENT reporting.

Usage

cvd_indicator_metric_systemlevel_comparison(metric_id, time_period_id, area_id)

Arguments

metric_id

Integer (required). The ID of the metric to compare. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid IDs.

time_period_id

Integer (required). The ID of the reporting period. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The ID of the NHS area to anchor the comparison. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

The output includes:

Metric values for the selected area and its system-level peers
Target thresholds (if defined)
System-level metadata (e.g., "PCN", "ICB")

This function is useful for:

Benchmarking local performance against peer organisations
Identifying variation across system-level areas
Supporting equity and improvement initiatives at regional levels

Value

A tibble where each row represents an NHS area within the same system level, showing its performance for a specified metric. Columns include:

NationalLevel: Character. Indicates whether the row represents national-level data ("Y" or "N").
SystemLevelID: Integer. Identifier for the system level (e.g., 4 = PCN).
SystemLevelMedian: Numeric. Median value for the metric across all areas in the system level.
SystemLevelName: Character. Name of the system level (e.g., "PCN").
SystemLevelOrder: Integer. Display order for the system level.
AreaCode: Character. Code for the NHS area (e.g., "U55387").
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Barking & Dagenham North PCN").
Value: Numeric. Final calculated value for the metric in the area.

If no data is available for the given parameters, a tibble describing the error is returned.

API Documentation

See the CVDPREVENT API documentation: Indicator metric system level comparison

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Compare performance for metric ID 1270 in time period 17 for Salford South East PCN (area ID 705)
cvd_indicator_metric_systemlevel_comparison(
  metric_id = 1270,
  time_period_id = 17,
  area_id = 705
) |>
  dplyr::filter(AreaID %in% c(705:709), !is.na(Value)) |>
  dplyr::select(SystemLevelName, AreaID, AreaName, Value)

Retrieve time series data for a specific metric and area

Description

Returns a tibble containing time series data for a specified metric and NHS area. The output includes both national-level (England) and local-level values across reporting periods, enabling direct comparison and trend analysis.

Usage

cvd_indicator_metric_timeseries(metric_id, area_id)

Arguments

metric_id

Integer (required). The ID of the metric to retrieve. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid IDs.

area_id

Integer (required). The ID of the NHS area to retrieve data for. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

This function is designed to support longitudinal analysis of indicator performance. It returns:

Time series values for the selected metric in the specified area
Corresponding national values (AreaID = 1)
Target thresholds (if defined) for benchmarking

The result includes one row per time period per area, allowing users to:

Visualise trends over time
Compare local performance against national averages
Track progress toward clinical targets

To find valid metric_id values, use cvd_indicator_metric_list() or cvd_indicator_data(). For valid area_id values, use cvd_area_list() or cvd_area_search().

Value

A tibble where each row represents a time period for a specific NHS area, including the observed metric value and associated target threshold. Columns include:

AreaCode: Character. Code for the NHS area (e.g., "U60510" for a PCN, "E92000001" for England).
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Salford South East PCN").
Count: Integer. Number of records included in the calculation (e.g., eligible patients).
Denominator: Numeric. Denominator used in the metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often blank.
Numerator: Numeric. Numerator used in the metric calculation.
TimePeriodID: Integer. Identifier for the reporting period.
TimePeriodName: Character. Display label for the time period (e.g., "To June 2024").
Value: Numeric. Final calculated value for the metric in the given period.
TargetLabel: Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
TargetValue: Numeric. Target value to be achieved (e.g., 95).

If no data is available for the given parameters, a tibble describing the error is returned.

API Documentation

See the CVDPREVENT API documentation: Indicator time series metrics

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List data for Salford South East PCN (area ID 705) for 'AF: treatment with
# anticoagulants' for women people aged 60-79 years (metric ID 130):
cvd_indicator_metric_timeseries(metric_id = 130, area_id = 705) |>
  dplyr::select(AreaName, TimePeriodName, TimePeriodID, Value) |>
  tidyr::pivot_wider(
    names_from = AreaName,
    values_from = Value
  )

Retrieve metric data for a specific area and for national (England) comparison

Description

Returns a named list of tibbles containing: (1) metric data for the specified NHS area and the national (England, AreaID = 1) aggregate, and (2) details achieving the target value (if defined), including the target percentage and the additional number of patients needed to reach the target. This function supports benchmarking local performance vs. the national average, and helps quantify gaps to clinical targets.

If there is no data for either national or the chosen area for the given parameters, an error tibble is returned.

Usage

cvd_indicator_nationalarea_metric_data(time_period_id, area_id, metric_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to retrieve metric data. Use cvd_time_period_list() to find valid IDs.

area_id

Integer (required). The AreaID for which to retrieve data in addition to the national aggregate. use cvd_area_list() or cvd_area_search() to find valid IDs.

metric_id

Integer (required). The MetricID for which to retrieve values. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid MetricIDs.

Details

Use this function to benchmark a local area's metric value against the national figure and to understand the actual gap to a clinically meaningful target.

Value

A named list with up to two tibbles:

area: Tibble with one or more rows, summarising the metric for the specified area and the England aggregate (AreaID = 1).
target: Tibble (if available) with target-setting details for the area

If no data exists for both the area and the national aggregate for the given parameters, returns a tibble describing the error.

area contains the following columns:

AreaCode: Character. Code for the NHS area (e.g., "U68943" for Chester South PCN, "E92000001" for England).
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Chester South PCN", "England").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
NationalLevel: Character. Indicates whether the area represents national-level data ("Y" or "N").
NotificationCount: Integer. Count of notifications associated with the area for the given metric.
Value: Numeric. Final calculated value for the metric in the specified area.

target contains the following columns:

TargetLabel: Character. Descriptive label for the target (e.g., "Upper threshold for QOF").
TargetPatients: Integer. Number of additional patients needed to achieve the target threshold.
TargetValue: Numeric. Target value or threshold to be achieved (e.g., 95).

API Documentation

See the CVDPREVENT API documentation: Indicator national area metric data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Compare performance against metric 150  (AF: treatment with anticoagulants
# - all people) in 'Chester South PCN' (area ID 553) with national
# performance:
returned_list <- cvd_indicator_nationalarea_metric_data(
    metric_id = 150,
    time_period_id = 17,
    area_id = 553
)

# See what the list contains
returned_list |> summary()

# Extract the `area` details
area_data <- returned_list$area
area_data

# Extract `target` details
target_data <- returned_list$target
target_data

Retrieve indicators for a specified pathway group

Description

Returns a tibble of indicators associated with a single pathway group, identified by its ID. Pathway groups are thematic sub-groupings of priority groups and are visible in the Regional & ICS Insights page. This function enables users to retrieve all indicators linked to a specific pathway group (e.g., "Chronic Kidney Disease").

Usage

cvd_indicator_pathway_group(pathway_group_id)

Arguments

pathway_group_id

Integer (required). The ID of the pathway group to retrieve. Use cvd_indicator_priority_groups() to find valid IDs.

Value

A tibble containing indicators associated with the specified pathway group. Each row represents a single indicator and includes the following columns:

PathwayGroupID: Integer. Unique identifier for the pathway group (e.g., 9 for "Chronic Kidney Disease").
PathwayGroupName: Character. Name of the pathway group (e.g., "Chronic Kidney Disease").
AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP006CKD").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
MetricID: Integer. Unique identifier for the specific metric instance.
NotificationCount: Integer. Count of notifications associated with the indicator.
PathwayGroupDisplayOrder: Integer. Display order of the indicator within the pathway group.
QuestionGroupName: Character. Thematic label for the indicator's clinical focus (e.g., "Diagnosis", "Monitoring", "Management").

If the request fails or the ID is invalid, a tibble with error details is returned instead.

API Documentation

See the CVDPREVENT API documentation: indicator pathway group

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Return indicators for the 'Chronic Kidney Disease' Pathway Group (ID 9):
cvd_indicator_pathway_group(pathway_group_id = 9) |>
  dplyr::select(
    PathwayGroupName,
    PathwayGroupID,
    IndicatorCode,
    IndicatorID,
    IndicatorName
  )

Retrieve inequality time series data for a specific indicator and area

Description

Returns a tibble containing time series data for a specified indicator and NHS area, broken down by inequality markers such as age group, ethnicity, deprivation quintile, and sex. This function supports the Inequalities Markers Time Series chart used in CVDPREVENT reporting.

Usage

cvd_indicator_person_timeseries(indicator_id, area_id)

Arguments

indicator_id

Integer (required). The ID of the indicator to retrieve. Use cvd_indicator_list() or cvd_indicator_priority_groups() to find valid IDs.

area_id

Integer (required). The ID of the NHS area to retrieve data for. Use cvd_area_list() or cvd_area_search() to find valid IDs.

Details

The output includes:

Time series values for each subgroup within the selected indicator
Target thresholds (if defined) for benchmarking
Metric category metadata (e.g., "Age group", "Ethnicity")

This function is useful for:

Analysing disparities in indicator performance across population subgroups
Tracking progress toward clinical targets over time
Supporting equity-focused reporting and visualisation

To find valid indicator_id values, use cvd_indicator_list() or cvd_indicator_priority_groups(). For valid area_id values, use cvd_area_list() or cvd_area_search().

Value

A tibble where each row represents a time period for a specific NHS area and inequality subgroup. Columns include:

AreaCode: Character. Code for the NHS area (e.g., "U60510" for a PCN).
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Salford South East PCN").
MetricCategoryID: Integer. Unique identifier for the subgroup category (e.g., age band, ethnicity).
MetricCategoryName: Character. Label for the subgroup (e.g., "Female", "80+", "White").
TimePeriodID: Integer. Identifier for the reporting period.
TimePeriodName: Character. Display label for the time period (e.g., "To March 2025").
Value: Numeric. Final calculated value for the metric in the given subgroup and time period. May be blank if unavailable.
MetricCategoryTypeID: Integer. Identifier for the type of inequality marker (e.g., 1 = Age group, 3 = Ethnicity).
MetricCategoryTypeName: Character. Descriptive name of the inequality marker type (e.g., "Sex", "Age group", "Ethnicity").
TargetLabel: Character. Descriptive label for the target threshold (e.g., "Upper threshold for QOF").
TargetValue: Numeric. Target value to be achieved (e.g., 95).

If no data is available for the given parameters, a tibble describing the error is returned.

API Documentation

See the CVDPREVENT API documentation: Indicator person time series

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# View age group inequalities for indicator ID 7 in Salford South East PCN (area ID 705)
cvd_indicator_person_timeseries(indicator_id = 7, area_id = 705) |>
  dplyr::filter(
    MetricCategoryTypeName == "Age group",
    !is.na(Value)
  ) |>
  dplyr::select(MetricCategoryName, TimePeriodName, TimePeriodID, Value) |>
  tidyr::pivot_wider(
    names_from = MetricCategoryName,
    values_from = Value
  )

List all indicator priority groups

Description

Retrieves a tibble of indicator priority groups from the CVDPREVENT API. Priority groups reflect high-level clinical, operational or policy themes (such as "Inequalities" or "NHS Long Term Plan") and provide a way to cluster or filter multiple indicators for reporting and analytics.

Usage

cvd_indicator_priority_groups()

Details

Use this function to provide grouping / filtering options for dashboards or reports, or to explore which indicator themes are tracked in CVDPREVENT. Typically, you will select the priority group's name and ID for grouping or filtering tasks.

Value

A tibble with one row per indicator / priority group containing the following columns:

PriorityGroup: Character. High-level grouping label for the indicator (e.g., "CKD", "Prevalence", "ABC").
AxisCharacter: Character. Symbol used to represent the metric axis (e.g., "%").
FormatDisplayName: Character. Display format for the metric (e.g., "Proportion %", "Rate per 10,000 patients").
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Blue"). Often blank.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorFormatID: Integer. Internal ID for the indicator's format type.
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
MetricID: Integer. Unique identifier for the specific metric instance.
NotificationCount: Integer. Count of notifications associated with the indicator.
PathwayGroupID: Integer. Unique identifier for the clinical pathway group.
PathwayGroupName: Character. Name of the clinical pathway group (e.g., "Chronic Kidney Disease", "Hypertension").
PriorityGroupDisplayOrder: Integer. Display order for the priority group within its pathway.
PriorityGroupID: Integer. Unique identifier for the priority group.
QuestionGroupName: Character. Thematic label for the indicator's clinical focus (e.g., "Diagnosis", "Management", "Monitoring").

If no priority groups are found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator priority groups

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List all available priority group display names and their IDs
cvd_indicator_priority_groups() |>
  dplyr::select(PriorityGroupID, PriorityGroup)

# Preview group names for a sidebar filter in a dashboard
groups <- cvd_indicator_priority_groups()
unique(groups$PriorityGroup)

Retrieve raw metric values for multiple metrics, a specified area and time period

Description

Returns raw values for multiple metrics within an indicator (specified as indicator_id) for a single NHS system level and reporting period using the CVDPREVENT API. This function fetches unfiltered raw data at the metric level, allowing comprehensive extraction for all selected metrics and their available breakdowns (such as by age, sex or other category) within the chosen context.

Usage

cvd_indicator_raw_data(time_period_id, system_level_id, indicator_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to retrieve data. Use cvd_time_period_system_levels() to find valid IDs.

system_level_id

Integer (required). The SystemLevelID for which to retrieve data. Use cvd_time_period_system_levels() to find valid IDs.

indicator_id

Integer vector (required). One or more IndicatorIDs specifying which indicator and its associated metrics to return. Use cvd_indicator_list() to find valid IndicatorIDs.

Details

Use this function to retrieve a wide set of metric breakdowns for a given indicator in a single area and time period - useful for broad data extractions, dashboards or advanced analytics.

Value

A tibble with one row per metric breakdown for all requested metrics. The tibble has the following columns:

AreaCode: Character. ONS geographic code for the area (e.g., "E92000001" for England).
AreaName: Character. Name of the geographic area.
CategoryAttribute: Character. Subgroup label (e.g., "Male", "Female", "Persons").
Denominator: Numeric. Population or count used as the denominator in metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. May be NA.
HighestPriorityNotificationType: Character. Notification priority level, if available. Often NA.
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorShortName: Character. Abbreviated name of the indicator.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval for the metric value.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "40–59", "Female").
MetricCategoryTypeName: Character. Type of subgroup (e.g., "Age group", "Sex", "Ethnicity").
NotificationCount: Integer. Count of notifications associated with the indicator. Often zero.
Numerator: Numeric. Count used as the numerator in metric calculation.
TimePeriodName: Character. Label for the time period (e.g., "To December 2024").
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval for the metric value.
Value: Numeric. Calculated metric value (e.g., percentage of patients treated).
ValueNote: Character. Additional notes or flags about the value. Often NA.

API Documentation

See the CVDPREVENT API documentation: Indicator raw data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve metric data for 'CVD: All-cause mortality' (IndicatorID = 35) across
# NHS Regions (SystemLevelID = 6) in the period April 2024 to
# March 2025 (TimePeriodID = 27) and view a sample of 4 rows:
cvd_indicator_raw_data(
  time_period_id = 27,
  system_level_id = 6,
  indicator_id = 35
) |>
  dplyr::slice_sample(n = 4)

# Find a valid indicator IDs for a specified time period and system level,
# then retrieve raw data for one of these
indicators <- cvd_indicator_list(time_period_id = 22, system_level_id = 4)
cvd_indicator_raw_data(
  time_period_id = 22,
  system_level_id = 4,
  indicator_id = indicators$IndicatorID[1]
)

Indicator sibling data

Description

Returns data for all sibling areas (i.e., areas sharing the same parent) and the specified area itself, for a given metric and reporting period from the CVDPREVENT API. This endpoint is intended to provide a direct comparison of a single metric across related areas (e.g., all PCNs within an ICB, or all practices within a PCN).

Only the selected metric is returned for each sibling area.

Usage

cvd_indicator_sibling(time_period_id, area_id, metric_id)

Arguments

time_period_id

Integer (required). The reporting period (time period) for which to return sibling data. Use cvd_time_period_list() to obtain valid IDs.

area_id

Integer (required). The AreaID for which sibling data will be determined. Use cvd_area_list() or cvd_area_search() to find valid IDs.

metric_id

Integer (required). The MetricID for which to return data. Use cvd_indicator_metric_list() or cvd_indicator_data() to find valid MetricIDs.

Details

Use this function to compare a metric across all areas at the same hierarchical level (e.g., compare all practices in a PCN or all PCNs in an ICB) for benchmarking and visualisation purposes.

Value

A tibble containing the data for the specified metric in the selected area and all its siblings for the given reporting period. Columns include:

CategoryAttribute: Character. Grouping label used to define the population subset (e.g., "Male").
IndicatorCode: Character. Unique code for the indicator (e.g., "CVDP002AF").
IndicatorID: Integer. Unique identifier for the indicator.
IndicatorName: Character. Full descriptive name of the indicator.
IndicatorOrder: Integer. Display order for the indicator in dashboards or reports.
IndicatorShortName: Character. Abbreviated name of the indicator for display purposes.
MetricCategoryID: Integer. Unique identifier for the metric category.
MetricCategoryName: Character. Name of the subgroup or category (e.g., "40–59").
MetricCategoryOrder: Integer. Display order for the category within its type.
MetricCategoryTypeName: Character. Type of category used for breakdown (e.g., "Age group").
AreaCode: Character. Code for the NHS area (e.g., PCN).
AreaID: Integer. Unique identifier for the NHS area.
AreaName: Character. Name of the NHS area (e.g., "Greenwood PCN").
Count: Integer. Number of records included in the calculation.
DataID: Integer. Unique identifier for the data point.
Denominator: Numeric. Denominator used in the metric calculation.
Factor: Numeric. Scaling factor applied to the metric, if applicable. Often blank.
HighestPriorityNotificationType: Character. Notification priority level, if applicable (e.g., "Red"). Often blank.
LowerConfidenceLimit: Numeric. Lower bound of the confidence interval.
Max: Numeric. Maximum observed value for the metric.
Median: Numeric. Median value for the metric.
Min: Numeric. Minimum observed value for the metric.
NotificationCount: Integer. Count of notifications associated with the indicator.
Numerator: Numeric. Numerator used in the metric calculation.
Q20: Numeric. 20th percentile value.
Q40: Numeric. 40th percentile value.
Q60: Numeric. 60th percentile value.
Q80: Numeric. 80th percentile value.
SystemLevelID: Integer. Identifier for the system level (e.g., 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "PCN").
TimePeriodID: Integer. Identifier for the time period associated with the metric.
TimePeriodName: Character. Display label for the time period (e.g., "To March 2024").
UpperConfidenceLimit: Numeric. Upper bound of the confidence interval.
Value: Numeric. Final calculated value for the metric.
ValueNote: Character. Notes or flags associated with the value (e.g., suppression warnings).

If no sibling data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator sibling data

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Compare the value of metric 126 for area 1103 and all its siblings in time period 17
cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = 126) |>
  dplyr::select(AreaID, AreaName, Value, LowerConfidenceLimit, UpperConfidenceLimit)

# Find a valid metric ID for an indicator, then get sibling data
metrics <- cvd_indicator_metric_list(time_period_id = 17, system_level_id = 5)
metric_id <- metrics$MetricID[1]
cvd_indicator_sibling(time_period_id = 17, area_id = 1103, metric_id = metric_id)

List all available indicator tags

Description

Retrieves a list of all tags from the CVDPREVENT API that can be used to filter indicators. Tags provide a way to categorise and search for indicators by clinical or reporting groupings (such as "Priority Group", "Pathway Group" or other clinical categories).

Use this function to obtain valid tag IDs for use in functions that support filtering by tag, such as cvd_indicator().

Usage

cvd_indicator_tags()

Details

Tags are useful for grouping or filtering indicators in dashboards, reports or scripted analyses. Tag IDs returned by this function can be supplied to functions like cvd_indicator() via the tag_id argument for targeted queries.

Value

A tibble with one row per available indicator tag, containing the following colunns:

IndicatorTagID: Integer. Unique identifier for the tag associated with an indicator.
IndicatorTagName: Character. Descriptive label categorising the indicator (e.g., "monitoring", "prevention", "smoking").

If no tags are found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Indicator tags

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# List the first five indicator tags
cvd_indicator_tags() |>
  dplyr::arrange(IndicatorTagID) |>
  dplyr::slice_head(n = 5)

# Use a tag ID to filter indicators in another query
tags <- cvd_indicator_tags()
tag_id <- tags$IndicatorTagID[1]
cvd_indicator(time_period_id = 17, area_id = 3, tag_id = tag_id)

Retrieve available indicator types

Description

Returns a tibble of indicator type IDs and their corresponding names, used to categorise CVD indicators in the CVDPREVENT API. This function is primarily a helper for cvd_time_period_list(), which accepts indicator_type_id as an optional parameter.

Usage

cvd_indicator_types()

Value

A tibble of indicator types with the following columns:

IndicatorTypeID: Integer. Unique identifier for the indicator type.
IndicatorTypeName: Character. Name of the indicator type (e.g., "Standard", "Outcomes").

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples

# NB, the following example is not tested because it takes longer than
# expected to return the results

# List available indicator types
cvd_indicator_types()

List available time periods for CVD indicators

Description

Retrieves all available reporting periods from the CVDPREVENT API. Optionally, you can filter periods by a specific indicator type (e.g., standard, outcome) using the indicator_type_id parameter.

Usage

cvd_time_period_list(indicator_type_id = NULL)

Arguments

indicator_type_id

Optional integer. If provided, restricts the returned time periods to those containing data of the given indicator type.

Details

This function is often used to determine valid values for time period parameters in other API queries. It is a building block for most higher-level data retrieval functions in this package.

Value

A tibble containing details of available time periods with the following columns:

EndDate: POSIXct. End date of the reporting period (e.g., "2025-06-30").
IndicatorTypeID: Integer. Unique identifier for the indicator type (e.g., 1 = Standard, 2 = Outcomes).
IndicatorTypeName: Character. Descriptive name of the indicator type (e.g., "Standard", "Outcomes").
StartDate: POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
TimePeriodID: Integer. Unique identifier for the time period.
TimePeriodName: Character. Display label for the time period (e.g., "To June 2025", "Apr 2024 – Mar 2025").

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Time period for endpoint details.

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples

# NB, the following examples are not tested because they take longer than
# expected to return the results

# List all available time periods
cvd_time_period_list()

# List time periods with data for a specific indicator type (e.g., Standard)
cvd_time_period_list(indicator_type_id = 1)

List available time periods and associated system levels

Description

Retrieves all available reporting periods from the CVDPREVENT API, along with the NHS system levels included in each time period.

This function is useful to determine which system levels (e.g., national, region, ICB, PCN, practice) have data available for each reporting period.

Usage

cvd_time_period_system_levels()

Details

This function is helpful for understanding the data structure of each reporting period, especially if you need to filter or subset data by system level and time period in downstream API calls.

Value

A tibble containing time periods and the corresponding system levels with the following columns:

A tibble with the following columns:

EndDate: POSIXct. End date of the reporting period (e.g., "2023-12-31").
StartDate: POSIXct. Start date of the reporting period. Typically set to a default baseline (e.g., "1900-01-01").
TimePeriodID: Integer. Unique identifier for the time period.
TimePeriodName: Character. Display label for the time period (e.g., "To December 2023", "Apr 2022 – Mar 2023").
IsVisible: Logical or character. Indicates whether the time period is visible in the API or dashboard ("Y" or "N").
NationalLevel: Logical or character. Indicates whether the data is available at the national level ("Y" or "N").
SystemLevelID: Integer. Unique identifier for the system level (e.g., 1 = England, 4 = PCN).
SystemLevelName: Character. Name of the system level (e.g., "England", "Region", "Sub-ICB", "PCN").

If no data is found, returns a tibble describing the error.

API Documentation

See the CVDPREVENT API documentation: Time period system levels for technical details.

Note

This function may take longer than 5 seconds to complete due to API response time.

Examples


# Retrieve all time periods and associated system levels
periods_levels <- cvd_time_period_system_levels()

# Show available system levels for the latest time period
periods_levels |>
  dplyr::slice_max(order_by = TimePeriodID) |>
  dplyr::select(TimePeriodID, TimePeriodName, SystemLevelID, SystemLevelName)

Retrieve details for a specific NHS area and time period

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

Retieve flat sub-systems for an NHS area, grouped by system level

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

List NHS areas for a given time period and parent or system level

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

Retrieve nested sub-systems for an NHS area

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

Search for NHS areas by partial name and time period

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

List system levels available for a specific time period

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

List all system levels and their available time periods

Description

Usage

Details

Value

API Documentation

Note

See Also

Examples

List NHS areas without parent assignments for a given time period

Description

Usage

Arguments

Details

Value

API Documentation

Note

See Also

Examples

Data availability