Skip to contents

Read point observations from OBSTABLE files

Source: R/read_point_obs.R
read_point_obs.Rd

Data are read directly from OBSTABLE files with no modification except in the case of precipitation accumulations. Where possible, observations that are not available for the given accumulation time, they are derived from observations for other accumulation times, either by subtraction or addition.

Usage

read_point_obs(
  dttm,
  parameter,
  obs_path = ".",
  obsfile_template = "obstable",
  gross_error_check = TRUE,
  min_allowed = NULL,
  max_allowed = NULL,
  stations = NULL,
  vertical_coordinate = c(NA_character_, "pressure", "model", "height"),
  start_date = NULL,
  end_date = NULL,
  by = "1h"
)

Arguments

dttm

A vector of date time strings to read. Can be in YYYYMMDD, YYYYMMDDhh, YYYYMMDDhhmm, or YYYYMMDDhhmmss format. Can be numeric or character. seq_dttm can be used to generate a vector of equally spaced date-time strings. Alternatively valid date-times can be extracted from a forecast data frame or harp_list of forecast data frames using unique_valid_dttm.

parameter

Which parameter to read. This will normally be a harp parameter name.

obs_path

The path to the OBSTABLE files

obsfile_template

The template for the OBSTABLE file name.

gross_error_check

Logical of whether to perform a gross error check.

min_allowed

The minimum value of observation to allow in the gross error check. If set to NULL the default value for the parameter is used.

max_allowed

The maximum value of observation to allow in the gross error check. If set to NULL the default value for the parameter is used.

stations

The stations to retrieve observations for. This should be a vector of station ID numbers. Set to NULL to retrieve all stations.

vertical_coordinate

If upper air for multiple levels are to be read, the vertical coordinate of the data is given here. The default is "pressure", but can also be "model" for model levels, or "height" for height above ground /sea level.

start_date, end_date, by

[Deprecated] The use of start_date, end_date and by is no longer supported. dttm together with seq_dttm should be used to generate equally spaced date-times.

Value

A tibble with columns for valid_dttm, SID and the parameter.

Examples

if (requireNamespace("harpData", quietly = TRUE)) {
  read_point_obs(
    seq_dttm(2019021700, 2019022023),
    "T2m",
    obs_path = system.file("OBSTABLE", package = "harpData")
  )

  # stations can be specified using a vector of station ID numbers
  read_point_obs(
    seq_dttm(2019021700, 2019022023),
    "T2m",
    obs_path = system.file("OBSTABLE", package = "harpData"),
    stations = c(1001, 1010)
  )

  # Gross error checks are done automatically but the allowable values
  # can be changed with min_allowed and max_allowed.
  obs <- read_point_obs(
    seq_dttm(2019021700, 2019022023),
    "T2m",
    obs_path = system.file("OBSTABLE", package = "harpData"),
    min_allowed = 260,
    max_allowed = 280
  )

  # The removed observations are stored in the attribute "bad_obs"
  attr(obs, "bad_obs")

  # For vertical profiles, the vertical coordinate must be specified
  read_point_obs(
    seq_dttm(2019021700, 2019022023),
    "Z",
    obs_path            = system.file("OBSTABLE", package = "harpData"),
    vertical_coordinate = "pressure"
  )
}
#> Getting T2m.
#> 
#> Reading: /home/andrewts/R/x86_64-pc-linux-gnu-library/4.3/harpData/OBSTABLE/OBSTABLE_2019.sqlite
#> Warning: 142 observations removed due to gross error check.
#> Getting T2m.
#> 
#> Reading: /home/andrewts/R/x86_64-pc-linux-gnu-library/4.3/harpData/OBSTABLE/OBSTABLE_2019.sqlite
#> Getting T2m.
#> 
#> Reading: /home/andrewts/R/x86_64-pc-linux-gnu-library/4.3/harpData/OBSTABLE/OBSTABLE_2019.sqlite
#> Warning: 147549 observations removed due to gross error check.
#> Getting Z.
#> 
#> Reading: /home/andrewts/R/x86_64-pc-linux-gnu-library/4.3/harpData/OBSTABLE/OBSTABLE_2019.sqlite
#> # A tibble: 96,710 × 8
#>    valid_dttm            SID   lon   lat  elev     p     Z units
#>    <dttm>              <int> <dbl> <dbl> <dbl> <dbl> <dbl> <chr>
#>  1 2019-02-17 00:00:00  1001 -8.67  70.9     9    50 19846 m    
#>  2 2019-02-17 00:00:00  1001 -8.67  70.9     9   100 15597 m    
#>  3 2019-02-17 00:00:00  1001 -8.67  70.9     9   150 13048 m    
#>  4 2019-02-17 00:00:00  1001 -8.67  70.9     9   200 11220 m    
#>  5 2019-02-17 00:00:00  1001 -8.67  70.9     9   300  8656 m    
#>  6 2019-02-17 00:00:00  1001 -8.67  70.9     9   400  6762 m    
#>  7 2019-02-17 00:00:00  1001 -8.67  70.9     9   500  5224 m    
#>  8 2019-02-17 00:00:00  1001 -8.67  70.9     9   700  2792 m    
#>  9 2019-02-17 00:00:00  1001 -8.67  70.9     9   850  1322 m    
#> 10 2019-02-17 00:00:00  1001 -8.67  70.9     9   925   672 m    
#> # ℹ 96,700 more rows