Title: Estimate Ambient UV Dose from Location and Date Info
Version: 0.1.1
Description: Estimate ambient vitamin D-effective or erythemal dose using ultraviolet radiation (UV) data from the 'TEMIS' database, based on date and geographical location.
License: GPL-3
Encoding: UTF-8
RoxygenNote: 7.3.2
Suggests: knitr, rmarkdown, testthat (≥ 3.0.0)
Config/testthat/edition: 3
Imports: dplyr, ncdf4, tidyr, reshape2, lubridate, magrittr, purrr, rlang
Depends: R (≥ 3.5)
VignetteBuilder: knitr
NeedsCompilation: no
Packaged: 2025-09-30 14:53:19 UTC; rasha
Author: Rasha Shraim ORCID iD [aut, cre], Lina Zgaga ORCID iD [aut]
Maintainer: Rasha Shraim <rshraim@tcd.ie>
Repository: CRAN
Date/Publication: 2025-10-06 08:40:09 UTC

Annual UVB

Description

This function extracts vitamin D-effective UVB dose (i.e. UVB wavelenghts that can induce vitamin D synthesis in human skin) on a particular date and geographical location (longitude and latitude), over one year prior to the index date.

Usage

annual_uvb(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  type = "cumulative",
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

date vector, usually date of assessment or recruitment.

longitude

numeric vector of longitude values.

latitude

numeric vector of latitude values.

temis_path

path to TEMIS UV files downloaded using temis_uvdvc. Default is current directory.

type

Type of annual dose to be calculated, cumulative (default) or mean.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of mean or cumulative annual vitamin D UVB dose estimates.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uvb_example <- system.file("extdata", "uvb_example", package="UVdose")
annual_uvb(mysample, date, longitude, latitude, temis_path=uvb_example)

Annual erythemal UV

Description

This function extracts mean or cumulative erythemal UV dose at a given date and geographical location (longitude and latitude), over one year prior to the index date.

Usage

annual_uve(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  type = "cumulative",
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdec. Default is current directory.

type

Type of annual dose to be calculated, cumulative (default) or mean.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of mean or cumulative annual erythemal UV dose estimates.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uve_example <- system.file("extdata", "uve_example", package="UVdose")
annual_uve(mysample, date, longitude, latitude, temis_path=uve_example)

Calculate CW-D-UVB dose

Description

This function calculates cumulative and weighted vitamin D UVB (CW-D-UVB) dose based on a given index date, longitude, and latitude. Vitamin D accumulates during the summer months, and is used up in the winter - this estimate correlates to measured vitamin D levels. The dose is calculated over 135 days prior to the date of assessment provided and weighted to that days closer to the date contribute more to the final estimate. See O'Sullivan et al., 2017 DOI: 10.3945/jn.116.244079 for more details.

Usage

cw_uvb(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  h = 35,
  days = 135,
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdvc. Default is current directory.

h

Half-life of vitamin D UV in the body in days, default is 35 days.

days

Number of days prior to sampling over which to calculate the CW-D-UVB dose, default is 135 days.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of CW-D-UVB dose estimates.

References

O'Sullivan et al., 2017. Ambient UVB Dose and Sun Enjoyment Are Important Predictors of Vitamin D Status in an Older Population. J Nutr. doi: 10.3945/jn.116.244079. PMID: 28331054.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uvb_example <- system.file("extdata", "uvb_example", package="UVdose")
cw_uvb(mysample, date, longitude, latitude, temis_path = uvb_example)

Daily UVB

Description

This function extracts total daily vitamin D-effective UVB dose on a given date and geographical location (longitude and latitude).

Usage

daily_uvb(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdvc. Default is current directory.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of daily ambient UVB dose measurements.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("1000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uvb_example <- system.file("extdata", "uvb_example", package="UVdose")
daily_uvb(mysample, date, longitude, latitude, temis_path = uvb_example)

Daily erythemal UV

Description

This function extracts total daily ambient erythemal UV dose on a particular date, at a given geographical location (longitude and latitude).

Usage

daily_uve(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdec. Default is current directory.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of ambient daily erythemal UV measurements.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uve_example <- system.file("extdata", "uve_example", package="UVdose")
daily_uve(mysample, date, longitude, latitude, temis_path = uve_example)

Un-project Transverse Mercator Eastings and Northings back to latitude and longitude.

Description

These functions convert OSGB (Ordnance Survey of Great Britain) coordinates, i.e. Transverse Mercator easting and northing coordinates, for example, as provided by the UK Biobank. latitude returns latitude values and longitude returns longitude values.

Usage

latitude(data, easting, northing)

longitude(data, easting, northing)

Arguments

data

a data frame containing OSGB coordinates

easting

a numeric vector of easting coordinates

northing

a numeric vector of northing coordinates

Value

A numeric vector of latitude or longitude values.

Examples

osgb <- data.frame(east = c(393000, 461000, 438000), north = c(287000, 223000, 565000))
latitude(osgb, east, north)
longitude(osgb, east, north)

Seasonal UVB

Description

This function estimates mean or cumulative vitamin D-effective UVB dose over a period of months (<1 year) prior to the index date, at a given geographical location (longitude and latitude).

Usage

season_uvb(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  season = "summer",
  type = "cumulative",
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdvc. Default is current directory.

season

The duration over which erythemal UV dose is to be estimated. One of "summer" covering April to September (default), "winter" covering October to March, or a numeric vector corresponding to month range.

type

Type of annual dose to be calculated, cumulative (default) or mean.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of mean or cumulative seasonal UVB dose estimates.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uvb_example <- system.file("extdata", "uvb_example", package="UVdose")
season_uvb(mysample, date, longitude, latitude, temis_path=uvb_example,  season = "winter")

season_uvb(mysample, date, longitude, latitude, temis_path=uvb_example, season = c(6:8))

Seasonal erythemal UV

Description

This function estimates mean or cumulative erythemal UV dose over a period of months (<1 year) prior to an index date, at a given geographical location (longitude and latitude).

Usage

season_uve(
  data,
  date,
  longitude,
  latitude,
  temis_path = getwd(),
  season = "summer",
  type = "cumulative",
  region = "europe"
)

Arguments

data

data frame containing sample IDs, date, longitude, and latitude

date

A date vector, usually date of assessment or recruitment.

longitude

A numeric vector of longitude values.

latitude

A numeric vector of latitude values.

temis_path

Path to TEMIS UV files downloaded using temis_uvdec. Default is current directory.

season

The duration over which erythemal UV dose is to be estimated. One of "summer" covering April to September (default), "winter" covering October to March, or a numeric vector corresponding to month range.

type

Type of annual dose to be calculated, cumulative (default) or mean.

region

Region of TEMIS data required, options are "europe" (default) or "world".

Value

A numeric vector of mean or cumulative seasonal erythemal UV dose estimates.

Examples

#uses sample TEMIS file
mysample <- data.frame(id = c("id000016"),
        date = as.Date(c("2010-08-04")),
        longitude = c(-2.10),
        latitude = c(50.5))
uve_example <- system.file("extdata", "uve_example", package="UVdose")
season_uve(mysample, date, longitude, latitude, temis_path=uve_example, season = c(1:3,11:12))

season_uve(mysample, date, longitude, latitude, temis_path=uve_example, season = "summer")

Download TEMIS file

Description

These functions download UV files from TEMIS for a given range of years present. temis_uvdvc returns vitamin D UV data and temis_uvdec returns erythemal UV data. temis_clim returns only a climatology file. For various technical reasons, some days are missing UV observations. TEMIS provides a climatology file, which is a UV file with values averaged across 2004-2020 and is used in the other functions to fill in these missing observations. In the first two functions, the climatology file is downloaded by default and used downstream to fill in missing observations. It contains UV (erythemal or UVB) values for each day averaged over 17 years: 2004 - 2020 (leap day 29 Feb. is skipped). Yearly UV files are downloaded from TEMIS for Europe by default. The UV doses, in kJ/m2, are calculated based on cloud-adjusted data. See maps below for area coverage for each of the "europe" and "world" regions (as of 21 March 2025). See https://www.temis.nl/uvradiation/product/uvncinfo.html for more info. Cloud-adjusted TEMIS data is available from 19-Jan-2004 onwards.

Usage

temis_uvdvc(years, path, climatology = TRUE, region = "europe")

temis_uvdec(years, path, climatology = TRUE, region = "europe")

temis_clim(path, uv_type, region = "europe")

Arguments

years

The range of years for which UV files will be downloaded, either an integer range or a date vector such as a date column in a dataframe. The data file for an additional year to the provided range is downloaded for non-daily UV dose calculations to account for earlier dates. For example, for the CW-D-UVB dose in cw_uvb a sample dated 01-02-2007 requires UV data up to 18-09-2006.

path

Directory where files will be downloaded to ("path/to/dir").

climatology

If TRUE (default) the climatology file will be downloaded. If FALSE, only year files will be downloaded. The same climatology file is used regardless of the specified year range.

region

As illustrated in the maps below, if "europe" (default), files covering Europe region will be downloaded, if "world", world files will be downloaded. March2025_vitD_cloudy_europe.png March2025_vitD_cloudy_world.png

uv_type

For temis_clim, "uve" or "uvb" for erythemal UV or vitamin D UVB, respectively.

Value

Files downloaded to specified directory.

Data check for UV dose calculation

Description

UV dose calculation requires date, latitude, and longitude inputs.

Usage

uv_data_check(data)

Arguments

data

Input dataframe to be used for UV dose calculation

Value

A message checking validity of input data

None, returns a message about input data validity.

Examples

mysample <- data.frame(id = c("id000016", "id000021"),
      date = as.Date(c("2009-05-15", "2008-08-04")),
      easting = c(519000, 365000),
      northing = c(176000, 172000))
uv_data_check(mysample)