phsopendata

https://public-health-scotland.github.io/phsopendata
Admin
phsopendata is an R package that provides functions to extract and query data from the Scottish...
Tokens:4,246
Snippets:33
Trust Score:8.3
Update:7 months ago
Show doc for...
Tokens:
Raw
### Install phsopendata from CRAN

Source: https://public-health-scotland.github.io/phsopendata/index

Installs the `phsopendata` package from the Comprehensive R Archive Network (CRAN). This is the recommended method for most users.

```r
install.packages("phsopendata")
```

--------------------------------

### Install phsopendata Development Version from GitHub

Source: https://public-health-scotland.github.io/phsopendata/index

Installs the development version of the `phsopendata` package directly from its GitHub repository. This is useful for accessing the latest features or bug fixes before they are released on CRAN. Ensure the `remotes` package is installed first.

```r
# install.packages("remotes")
remotes::install_github("Public-Health-Scotland/phsopendata")
```

--------------------------------

### Get Dataset by Name

Source: https://public-health-scotland.github.io/phsopendata/index

Extracts multiple resources from a dataset, identified by its dataset name. Allows limiting the number of resources and rows per resource.

```APIDOC
## GET /data/dataset

### Description
Retrieves all resources (or a specified number) from a given dataset by its name. This function allows for pagination of resources and rows within each resource.

### Method
GET

### Endpoint
/data/dataset

### Parameters
#### Query Parameters
- **dataset_name** (string) - Required - The name of the dataset from which to retrieve resources.
- **max_resources** (integer) - Optional - The maximum number of resources to retrieve from the dataset. Defaults to retrieving all resources.
- **rows** (integer) - Optional - The maximum number of rows to retrieve from each resource. If not specified, all rows are returned for each resource.

### Request Example
```json
{
  "dataset_name": "gp-practice-populations",
  "max_resources": 2,
  "rows": 10
}
```

### Response
#### Success Response (200)
- **resources** (array of objects) - An array where each object contains data for a resource within the dataset. Each resource object may contain a 'data' field which is an array of row objects.

#### Response Example
```json
{
  "resources": [
    {
      "resource_id": "resource-id-1",
      "data": [
        {"col1": "valA1", "col2": "valB1"},
        {"col1": "valA2", "col2": "valB2"}
      ]
    },
    {
      "resource_id": "resource-id-2",
      "data": [
        {"col1": "valC1", "col2": "valD1"}
      ]
    }
  ]
}
```
```

--------------------------------

### Get Latest Resource by Dataset Name

Source: https://public-health-scotland.github.io/phsopendata/index

Retrieves the most recent resource from a dataset, identified by its dataset name.

```APIDOC
## GET /data/resource/latest

### Description
Retrieves the most recent resource associated with a given dataset name. This is useful for accessing the latest available data for a specific dataset.

### Method
GET

### Endpoint
/data/resource/latest

### Parameters
#### Query Parameters
- **dataset_name** (string) - Required - The name of the dataset for which to retrieve the latest resource.
- **rows** (integer) - Optional - The maximum number of rows to return from the latest resource.

### Request Example
```json
{
  "dataset_name": "gp-practice-populations",
  "rows": 50
}
```

### Response
#### Success Response (200)
- **data** (array of objects) - An array of objects representing rows from the latest resource of the specified dataset.

#### Response Example
```json
{
  "data": [
    {
      "FieldName1": "Value1",
      "FieldName2": "Value2"
    }
  ]
}
```
```

--------------------------------

### Get Open Data Resources

Source: https://public-health-scotland.github.io/phsopendata/reference/get_dataset

Downloads multiple resources from a dataset on the NHS Open Data platform by dataset name, with optional row limits and context columns.

```APIDOC
## GET /datasets/{dataset_name}/resources

### Description
Downloads multiple resources from a dataset on the NHS Open Data platform by dataset name, with optional row limits and context columns.

### Method
GET

### Endpoint
/datasets/{dataset_name}/resources

### Parameters
#### Path Parameters
- **dataset_name** (string) - Required - Name of the dataset as found on the NHS Open Data platform.

#### Query Parameters
- **max_resources** (integer) - Optional - The maximum number of resources to return. If not set, all resources are returned.
- **rows** (integer) - Optional - Maximum number of rows to return.
- **row_filters** (list) - Optional - A named list or vector specifying values of columns/fields to keep (e.g., list(Date = 20220216, Sex = "Female")).
- **col_select** (string array) - Optional - A character vector containing the names of desired columns/fields (e.g., c("Date", "Sex")).
- **include_context** (boolean) - Optional - If TRUE, additional information about the resource will be added as columns to the data, including the resource ID, the resource name, the creation date, and the last modified/updated date.

### Request Example
```
GET /datasets/gp-practice-populations/resources?max_resources=2&rows=10
```

### Response
#### Success Response (200)
- **data** (tibble) - A tibble with the data from the requested resources.

#### Response Example
```json
{
  "data": [
    {
      "column1": "value1",
      "column2": "value2"
    },
    {
      "column1": "value3",
      "column2": "value4"
    }
  ]
}
```
```

--------------------------------

### List Datasets with R

Source: https://public-health-scotland.github.io/phsopendata/reference/list_datasets

The `list_datasets()` function retrieves a tibble containing the names of all datasets available on the PHS Open Data Platform. It has no input parameters. The output is a tibble, and examples show how to view the first few rows.

```r
list_datasets()

head(list_datasets())
```

--------------------------------

### Get Resource by ID

Source: https://public-health-scotland.github.io/phsopendata/index

Extracts a single resource from an open dataset using its unique resource ID. Supports filtering rows and selecting specific columns.

```APIDOC
## GET /data/resource

### Description
Retrieves a single resource from the CKAN API using its unique resource ID. This function allows for server-side filtering of rows and selection of specific columns to optimize data retrieval.

### Method
GET

### Endpoint
/data/resource

### Parameters
#### Query Parameters
- **res_id** (string) - Required - The unique identifier for the resource to be retrieved.
- **rows** (integer) - Optional - The maximum number of rows to return. If not specified, all rows are returned.
- **col_select** (array of strings) - Optional - An array of column names to select. Only these columns will be returned.
- **row_filters** (object) - Optional - A list of filters to apply to the rows. Keys are column names and values are the desired filter values.

### Request Example
```json
{
  "res_id": "a794d603-95ab-4309-8c92-b48970478c14",
  "rows": 100,
  "col_select": ["GPPracticeName", "TelephoneNumber"],
  "row_filters": {
    "HB": "S08000017",
    "Dispensing": "Y"
  }
}
```

### Response
#### Success Response (200)
- **data** (array of objects) - An array of objects, where each object represents a row of data with the selected columns.

#### Response Example
```json
{
  "data": [
    {
      "GPPracticeName": "Example Practice Name",
      "TelephoneNumber": "01234 567890"
    }
  ]
}
```
```

--------------------------------

### Get Dataset Additional Info (R)

Source: https://public-health-scotland.github.io/phsopendata/reference/get_dataset_additional_info

The `get_dataset_additional_info` function retrieves a tibble containing the dataset name, number of resources, and last updated date for a given dataset. It requires the dataset name as a character input. The last updated date reflects the most recent creation or modification of any resource within the dataset.

```r
get_dataset_additional_info <- function(dataset_name) {
  # Function body would go here
  # Example placeholder:
  data.frame(
    name = dataset_name,
    n_resources = sample(1:50, 1),
    last_updated = Sys.time() - sample(1:100, 1) * 86400
  )
}

# Example usage:
# get_dataset_additional_info("gp-practice-populations")
```

--------------------------------

### Get Latest Resource from Dataset (R)

Source: https://public-health-scotland.github.io/phsopendata/reference/get_latest_resource

Retrieves the latest resource from a specified dataset on the NHS Open Data platform. Supports optional row limits, column selection, and row filtering. Can also include additional context columns. Useful for datasets that manage historical resources.

```r
get_latest_resource(
  dataset_name,
  rows = NULL,
  row_filters = NULL,
  col_select = NULL,
  include_context = TRUE
)
```

```r
dataset_name <- "gp-practice-contact-details-and-list-sizes"

data <- get_latest_resource(dataset_name)

filters <- list("Postcode" = "DD11 1ES")
wanted_cols <- c("PracticeCode", "Postcode", "Dispensing")

filtered_data <- get_latest_resource(
  dataset_name = dataset_name,
  row_filters = filters,
  col_select = wanted_cols
)
```

--------------------------------

### Download Multiple Resources from NHS Open Data Dataset (R)

Source: https://public-health-scotland.github.io/phsopendata/reference/get_dataset

The `get_dataset` function in R downloads multiple resources from a specified dataset on the NHS Open Data platform. It accepts arguments for dataset name, maximum resources, row limits, row filters, column selection, and context inclusion. The function returns a tibble containing the requested data.

```r
get_dataset(
  dataset_name,
  max_resources = NULL,
  rows = NULL,
  row_filters = NULL,
  col_select = NULL,
  include_context = FALSE
)
```

```r
if (FALSE) { # \dontrun{
get_dataset("gp-practice-populations", max_resources = 2, rows = 10)
} # }
```

--------------------------------

### Download and Filter NHS Open Data Resource (R)

Source: https://public-health-scotland.github.io/phsopendata/reference/get_resource

Downloads a single resource from the NHS Open Data platform using its ID. Supports optional arguments for filtering rows based on column values and selecting specific columns. The function returns a tibble containing the requested data.

```R
get_resource(
  res_id,
  rows = NULL,
  row_filters = NULL,
  col_select = NULL,
  include_context = FALSE
)
```

```R
res_id <- "ca3f8e44-9a84-43d6-819c-a880b23bd278"

data <- get_resource(
  res_id
)

filters <- list("HB" = "S08000030", "Month" = "202109")
wanted_cols <- c("HB", "Month", "TotalPatientsSeen")

filtered_data <- get_resource(
  res_id = res_id,
  row_filters = filters,
  col_select = wanted_cols
)
```

--------------------------------

### List Datasets

Source: https://public-health-scotland.github.io/phsopendata/index

Returns the names of all available datasets on the open data platform.

```APIDOC
## GET /data/datasets

### Description
Retrieves a list of all available dataset names from the CKAN API.

### Method
GET

### Endpoint
/data/datasets

### Parameters
None

### Request Example
```json
{}
```

### Response
#### Success Response (200)
- **datasets** (array of strings) - An array containing the names of all available datasets.

#### Response Example
```json
{
  "datasets": [
    "dataset-name-1",
    "dataset-name-2",
    "gp-practice-populations"
  ]
}
```
```

--------------------------------

### Query Data with get_resource() - Server-Side Filtering

Source: https://public-health-scotland.github.io/phsopendata/index

Filters data on the server before downloading using `col_select` and `row_filters` arguments within `get_resource()`. This reduces the amount of data transferred and processed locally, improving efficiency for large datasets.

```r
# get first 100 rows
get_resource(
  res_id = "a794d603-95ab-4309-8c92-b48970478c14",
  col_select = c("GPPracticeName", "TelephoneNumber"),
  row_filters = list(
    HB = "S08000017",
    Dispensing = "Y"
  )
)
```

--------------------------------

### List Resources in Dataset

Source: https://public-health-scotland.github.io/phsopendata/index

Returns information on all resources within a specified open dataset, identified by its dataset name.

```APIDOC
## GET /data/dataset/resources

### Description
Retrieves a list of all resources within a specific dataset, including metadata for each resource.

### Method
GET

### Endpoint
/data/dataset/resources

### Parameters
#### Query Parameters
- **dataset_name** (string) - Required - The name of the dataset for which to list resources.

### Request Example
```json
{
  "dataset_name": "gp-practice-populations"
}
```

### Response
#### Success Response (200)
- **resources** (array of objects) - An array of objects, where each object contains metadata for a resource within the dataset, including its ID, name, and format.

#### Response Example
```json
{
  "resources": [
    {
      "id": "a794d603-95ab-4309-8c92-b48970478c14",
      "name": "GP Practice Population Demographics",
      "format": "CSV"
    },
    {
      "id": "another-resource-id",
      "name": "Another Resource Name",
      "format": "JSON"
    }
  ]
}
```
```

--------------------------------

### Query Data with get_resource() - Row Limit

Source: https://public-health-scotland.github.io/phsopendata/index

Downloads a specified number of rows from a data resource using the `rows` argument in `get_resource()`. This is useful for quickly inspecting the beginning of a dataset or for testing queries.

```r
# get first 100 rows
get_resource(
  res_id = "a794d603-95ab-4309-8c92-b48970478c14",
  rows = 100
)
```

--------------------------------

### Download Multiple Tables with get_dataset()

Source: https://public-health-scotland.github.io/phsopendata/index

Downloads all resources associated with a specific dataset using its dataset name. The `max_resources` argument limits the number of resources to download, and `rows` can limit the number of rows per resource. This function is useful for retrieving related data tables from a single dataset.

```r
# if max_resources is not set, all resources will be returned by default.
# Here we pull 10 rows from the first 2 resources only
get_dataset("gp-practice-populations", max_resources = 2, rows = 10)
```

--------------------------------

### List Dataset Resources in R

Source: https://public-health-scotland.github.io/phsopendata/reference/list_resources

The `list_resources()` function retrieves all resources for a specified dataset. It takes the dataset name as a character argument and returns a tibble containing resource details such as ID, name, creation date, and last modified date. This function is useful for exploring the available data components of a dataset.

```R
list_resources(dataset_name)

# Example:
list_resources("weekly-accident-and-emergency-activity-and-waiting-times")
```

--------------------------------

### Download a Specific Data Resource using get_resource()

Source: https://public-health-scotland.github.io/phsopendata/index

Downloads a single data resource from the CKAN API using its unique resource ID. The resource ID can be found in dataset metadata, resource URLs, or by using the `list_resources()` function. The downloaded data is stored in an R variable.

```r
library(phsopendata)

# define a resource ID
res_id <- "a794d603-95ab-4309-8c92-b48970478c14"

# download the data from the CKAN database
data <- get_resource(res_id = "a794d603-95ab-4309-8c92-b48970478c14")
```

--------------------------------

### Download PHS Open Data using SQL Query (R)

Source: https://public-health-scotland.github.io/phsopendata/reference/get_resource_sql

Downloads data from the NHS Open Data platform using a PostgreSQL SELECT query. This function is useful for server-side filtering and selection but has a maximum row limit of 32,000. It requires a character string containing a valid SQL query with a double-quoted resource ID.

```R
get_resource_sql(sql)
```

```R
sql <- "
   SELECT
     \"TotalCancelled\",\"TotalOperations\",\"Hospital\",\"Month\"
   FROM
     \"bcc860a4-49f4-4232-a76b-f559cf6eb885\"
   WHERE
     \"Hospital\" = 'D102H'
"
df <- get_resource_sql(sql)
```
Tokens:
Raw