hospitals

Portuguese NHS hospitals

https://github.com/nhs-pt/hospitals

Repository

Portuguese NHS hospitals

README.Rmd

---
output: github_document
---



```{r, include = FALSE}
knitr::opts_chunk$set(
  collapse = TRUE,
  comment = "#>",
  fig.path = "man/figures/README-",
  out.width = "100%"
)
library(hospitals)
```

# hospitals 


[![CRAN status](https://www.r-pkg.org/badges/version/hospitals)](https://CRAN.R-project.org/package=hospitals)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5729243.svg)](https://doi.org/10.5281/zenodo.5729243)


This R data package contains one single data set --- the eponymous `hospitals`
tibble --- comprising the current `r nrow(hospitals)` hospitals in the
Portuguese National Health Service.

For a description of each variable and data sources used to assemble this
data set browse the documentation with `?hospitals`.

## Installation

Install `{hospitals}` from CRAN:

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

You can instead install the development version of `{hospitals}` by setting
[nhs-pt's universe](https://nhs-pt.r-universe.dev/) repository:

``` r
options(repos = c(
    nhspt = 'https://nhs-pt.r-universe.dev',
    CRAN = 'https://cloud.r-project.org'))
    
install.packages('hospitals')
```

## Citing this work

To generate a citation for this publication from within R:

```{r}
citation('hospitals')
```

## The `hospitals` data set

### The Portuguese NHS hospitals

Here are the `r nrow(hospitals)` hospitals currently included in the Portuguese National Health Service:

```{r dataset}
library(hospitals)

# Hospital identifier and name
hospitals[c(1, 7)] %>% print(n = Inf)
```

### Variables

The `hospitals` data set contains the following variables:

| Variable       | Description |
|:------------------|:-------------|
| `hospital_id`     | A surrogate identifier created by us that ought to help researchers refer to hospitals in an unambiguous way. The idea is for these identifiers to never change. So if an hospital disappears, or is merged with another one, we will deprecate old identifiers and create new, accordingly. |
| `hospital_acronym`        | The acronym or initialism of the hospital name.         |
| `hospital_legal_status`      | Either an administrative public sector (`'SPA'`) entity, a corporate public entity (`'EPE'`) or a public-private partnership (`'PPP'`) entity.  |
| `hospital_integration`         | The integration level of the hospital institution: a single hospital unit (`'H'`); Centro Hospitalar (`'CH'`), comprising two or more individual Hospital units (a case of horizontal integration); and Unidade Local de Saúde (`'ULS'`), comprising both Hospital entities and primary care health centres (a case of vertical integration).         |
| `hospital_group`         | One of the groups defined by [Ordinance 82/2014](https://data.dre.pt/eli/port/82/2014/04/10/p/dre/pt/html): `'I'`, `'II'`, `'III'`, `'IV-a'`, `'IV-b'` or `'IV-c'`. This classification is based on the hospital catchment area and the scope of medical specialities provided. Broadly speaking, group I includes local hospitals, group II corresponds to regional hospitals, and group III to central hospitals. Group IV corresponds to specialised hospitals: IV-a, oncology institutes; IV-b, physical medicine and rehabilitation hospitals; and IV-c, psychiatry and mental health hospitals. |
| `hospital_short_name`         | An abbreviated version of the hospital name.         |
| `hospital_full_name`         | The name of the hospital.         |
| `hospital_region_full_name`         | The name of the Portuguese health region.         |
| `hospital_region_short_name`         | A shortened version of `hospital_region_full_name.`         |
| `hospital_vatin`         | VAT identification number (VATIN). In Portuguese, *Número de Identificação de Pessoa Colectiva* (NIPC).         |
| `hospital_latitude`         | Latitude of the location of the hospital entity expressed in decimal degrees.         |
| `hospital_longitude`         | Longitude of the location of the hospital entity expressed in decimal degrees.         |
| `hospital_region_colour`         | Colour associated with the region. These colours are assigned by this package and are provided as a convenience colour palette for plotting in R.         |
| `hospital_bh_group`         | One of the groups defined by the project Benchmarking of Hospitals. Source: [BH \| Grupos e Instituições](https://benchmarking-acss.min-saude.pt/BH_Enquadramento/GrupoInstituicoes).         |
| `hospital_bh_group_colour`         | Colour associated with the `hospital_bh_group`. These colours are assigned by this package and are provided as a convenience colour palette for plotting in R.         |
| `hospital_regex`         | A regular expression that can be used to identify hospitals from their names, even when the names are not exactly as in `hospital_full_name`. This is used by the function `normalise()`.        |

## Helper functions

### `normalise()`

The names of hospitals found in the wild can have subtle variations.
The `normalise()` function matches hospital names found elsewhere to the
hospitals included in the data set `hospitals`.

For example, with `normalise` you can convert hospital names found elsewhere to
the names found in `hospitals$hospital_short_name`:

```{r map_wild_names}
normalise(c('Hospital do Alto Minho'))
```

Also `normalise` is aware of old hospital names, and can map to the new ones:

```{r map_old_names}
normalise(c('Hospital do Alto Ave'))
```

The method behind `normalise` for matching hospital names to their names in
`hospital_short_name` is based on an heuristic that uses a minimal set of
keywords to identify the hospital. So it is pretty tolerant to variations in the
name as long as one of the critical keywords is found in the name, e.g., to
identify the Hospital of Algarve as such only the keyword *Algarve* needs to be
present in the name:

```{r keywords}
normalise(c('Algarve', 'H Algarve', 'Hospital do Algarve'))
```

Also `normalise` should be lenient with typos associated with accented characters:

```{r accented_chars}
normalise('Hospital de São João')

# Without the tildes the mapping still works fine
normalise('Hospital de Sao Joao')
```

Instead of the `hospital_short_name` you may ask for the `hospital_full_name` or the `hospital_id`:

```{r short_name}

# 'hospital_short_name' is the default 
normalise('Matosinhos', return = 'hospital_short_name')

normalise('Matosinhos', return = 'hospital_full_name')

normalise('Matosinhos', return = 'hospital_id')
```

### `get_hospital_attribute()`

`get_hospital_attribute()` is a thin wrapper function allowing you to easily
retrieve hospital attributes from the data set `hospitals`.

You specify the hospitals by indicating what type of key you are providing:
`"hospital_id"`, `"hospital_acronym"`, `"hospital_short_name"` or
`"hospital_full_name"`. Contrarily to the matching performed by `normalise()`,
`get_hospital_attribute()` matches exactly the key provided.

And specify the column variable in `hospitals` with the `value` argument
(default is `"hospital_short_name"`).

```{r}
# By default you get the hospital short name
get_hospital_attribute('h0001')

# Same as above
get_hospital_attribute('h0001', value = 'hospital_short_name')

# Or get instead the full name
get_hospital_attribute('h0001', value = 'hospital_full_name')

# Map the hospital short name to its full name
get_hospital_attribute('IPO de Lisboa', key = 'hospital_short_name', value = 'hospital_full_name')
```

## Code of Conduct
  
Please note that the hospitals project is released with a [Contributor Code of
Conduct](https://contributor-covenant.org/version/2/0/CODE_OF_CONDUCT.html). By
contributing to this project, you agree to abide by its terms.

GitHub Events

Committers

Last synced: almost 3 years ago

Issues and Pull Requests

Last synced: 12 months ago

Packages