docs fixes

bczernecki · Oct 17, 2024 · 921a78a · 921a78a
1 parent badc9fc
commit 921a78a
Show file tree

Hide file tree

Showing 41 changed files with 95 additions and 210 deletions.
diff --git a/R/clean_metadata_hydro.R b/R/clean_metadata_hydro.R
@@ -5,6 +5,7 @@
 #' @param interval temporal interval
 #' @importFrom utils read.fwf
 #' @keywords internal
+
 clean_metadata_hydro = function(address, interval) {
   temp = tempfile()
 

diff --git a/R/get_coord_from_string.R b/R/get_coord_from_string.R
@@ -7,7 +7,8 @@
 #' @format The returned object is the geographic coordinates using WGS84 (EPSG:4326) in decimal format.
 #' Negative values mean western or southern Hemisphere
 #' @keywords internal
-#'
+#' @noRd
+
 get_coord_from_string = function(txt, pattern = "Longitude") {
   tt = gregexpr(pattern, txt)
   start = tt[[1]][1] + attributes(tt[[1]])$match.length + 1

diff --git a/R/hydro_imgw_daily.R b/R/hydro_imgw_daily.R
@@ -96,17 +96,9 @@ hydro_imgw_daily_bp = function(year,
       }
       # extra exception for a current year according to information provided by IMGW-PIB:
       # i.e.:
-      # "Do czasu zakończenia kontroli przepływów z roku hydrologicznego 2020 (do około poczatku sierpnia 2021),
-      # rekordy z  danymi z roku 2020 mają format:
-      #Kod stacji
-      #Nazwa stacji
-      #Nazwa rzeki/jeziora
-      #Rok hydrologiczny
-      #Wskaźnik miesiąca w roku hydrologicznym
-      #Dzień
-      #Stan wody [cm]
-      #Temperatura wody [st. C]
-      #Miesiąc kalendarzowy
+      # "Do czasu zakonczenia kontroli przeplywow rekordy z danymi z roku 2020 maja format:
+      #Kod stacji  #Nazwa stacji  #Nazwa rzeki/jeziora  #Rok hydrologiczny  #Wskaznik miesiaca w roku hydrologicznym
+      #Dzien  #Stan wody [cm]  #Temperatura wody [st. C]    #Miesiac kalendarzowy
       if (ncol(data1) == 9) {
         data1$flow = NA
         data1 = data1[, c(1:7, 10, 8:9)]
@@ -131,9 +123,7 @@ hydro_imgw_daily_bp = function(year,
 
     colnames(data2) = meta[[2]][, 1]
     all_data[[i]] = merge(data, data2,
-                         by = c("Kod stacji", "Nazwa stacji",
-                               "Rok hydrologiczny", "Nazwa rzeki/jeziora",
-                               "Wskaźnik miesiąca w roku hydrologicznym", "Dzień"),
+                         by = intersect(colnames(data), colnames(data2)),
                          all.x = TRUE)
   }
 
@@ -166,11 +156,7 @@ hydro_imgw_daily_bp = function(year,
     }
   }
 
-  all_data = all_data[order(all_data$`Nazwa stacji`,
-                            all_data$`Rok hydrologiczny`,
-                            all_data$`Wskaźnik miesiąca w roku hydrologicznym`,
-                            all_data$`Dzień`), ]
-  # dodanie opcji  dla skracania kolumn i usuwania duplikatow:
+  all_data = all_data[do.call(order, all_data[grep(x = colnames(all_data), "Nazwa stacji|Rok hydro|w roku hydro|Dzie")]), ]
   all_data = hydro_shortening_imgw(all_data, col_names = col_names, ...)
 
   return(all_data)

diff --git a/R/hydro_imgw_monthly.R b/R/hydro_imgw_monthly.R
@@ -120,10 +120,7 @@ hydro_imgw_monthly_bp = function(year,
       stop("Selected station(s) are not in the proper format.", call. = FALSE)
     }
   }
-
-  all_data = all_data[order(all_data$`Nazwa stacji`,
-                            all_data$`Rok hydrologiczny`,
-                            all_data$`Wskaźnik miesiąca w roku hydrologicznym`), ]
+  all_data = all_data[do.call(order, all_data[grep(x = colnames(all_data), "Nazwa stacji|Rok hydrologiczny|w roku hydro")]), ]
   all_data = hydro_shortening_imgw(all_data, col_names = col_names, ...)
 
   return(all_data)

diff --git a/R/hydro_metadata_imgw.R b/R/hydro_metadata_imgw.R
@@ -6,6 +6,7 @@
 #' @param interval temporal resolution of the data ("daily" , "monthly", or "semiannual_and_annual")
 #' @param allow_failure logical - whether to proceed or stop on failure. By default set to TRUE (i.e. don't stop on error). For debugging purposes change to FALSE
 #' @keywords internal
+#' @noRd
 
 hydro_metadata_imgw = function(interval, allow_failure = TRUE) {
 

diff --git a/R/meteo_imgw.R b/R/meteo_imgw.R
@@ -1,7 +1,7 @@
-#' Meteorological data from IMGW
+#' Meteorological data from the IMGW-PIB official repository
 #'
 #' Downloading hourly, daily, and monthly meteorological data from the
-#' SYNOP / CLIMATE / PRECIP stations available in the danepubliczne.imgw.pl collection
+#' SYNOP / CLIMATE / PRECIP stations available in the danepubliczne.imgw.pl collection.
 #'
 #' @param interval temporal resolution of the data ("hourly", "daily", "monthly")
 #' @param rank rank of the stations: "synop" (default), "climate" or "precip"

diff --git a/R/meteo_imgw_daily.R b/R/meteo_imgw_daily.R
@@ -88,7 +88,7 @@ meteo_imgw_daily_bp = function(rank,
                                split = "_")
   years_in_catalogs = lapply(years_in_catalogs, function(x) x[1]:x[length(x)])
   ind = lapply(years_in_catalogs, function(x) sum(x %in% year) > 0)
-  catalogs = catalogs[unlist(ind)] # to sa nasze prawdziwe catalogs do przemielenia
+  catalogs = catalogs[unlist(ind)]
 
   all_data = NULL
 
@@ -163,9 +163,6 @@ meteo_imgw_daily_bp = function(rank,
       ind = grep(readHTMLTable(folder_contents)[[1]]$Name, pattern = "zip")
       files = as.character(readHTMLTable(folder_contents)[[1]]$Name[ind])
       addresses_to_download = paste0(address, files)
-      # w tym miejscu trzeba przemyslec fragment kodu
-      # do dodania dla pojedynczej stacji jesli tak sobie zazyczy uzytkownik:
-      # na podstawie zawartosci obiektu files
 
       for (j in seq_along(addresses_to_download)) {
         temp = tempfile()
@@ -199,11 +196,11 @@ meteo_imgw_daily_bp = function(rank,
                                                  data2,
                                                  by = c("Kod stacji", "Rok", "Miesiac", "Dzien"),
                                                  all.x = TRUE)
-      } # koniec petli po zipach do pobrania
-    } # koniec if'a dla klimatu
+      } # end of looping for zip files
+    } # end of if statement for climate stations
 
-    ######################
-    ######## OPAD: #######
+    ########################
+    ######## PRECIP: #######
     if (rank == "precip") {
       address = paste0(base_url, "dane_meteorologiczne/dobowe/opad",
                         "/", catalog, "/")
@@ -236,10 +233,9 @@ meteo_imgw_daily_bp = function(rank,
 
         unlink(c(temp, temp2))
         all_data[[length(all_data) + 1]] = data1
-      } # koniec petli po zipach do pobrania
-    } # koniec if'a dla klimatu
-
-  } # koniec petli po glownych catalogach danych dobowych
+      } # end of loop for zip files
+    } # end of if statement for climate stations
+  } # end of looping over catalogs
 
   all_data = do.call(rbind, all_data)
 
@@ -251,11 +247,11 @@ meteo_imgw_daily_bp = function(rank,
                      all.y = TRUE)
   }
 
-  # dodaje rank
+  # add station rank:
   rank_code = switch(rank, synop = "SYNOPTYCZNA", climate = "KLIMATYCZNA", precip = "OPADOWA")
   all_data = cbind(data.frame(rank_code = rank_code), all_data)
 
-  all_data = all_data[all_data$Rok %in% year, ] # przyciecie tylko do wybranych lat gdyby sie pobralo za duzo
+  all_data = all_data[all_data$Rok %in% year, ] # clip only to selected years
 
   #station selection
   if (!is.null(station)) {

diff --git a/R/meteo_imgw_datastore.R b/R/meteo_imgw_datastore.R
@@ -30,8 +30,8 @@
 #' @import data.table
 #' @export
 #'
-#' @examples \donttest{
-#' # download only air temperature for selected 2 stations in 2022-2023:
+#' @examples 
+#' \donttest{
 #' imgw_telemetry = meteo_imgw_datastore(year = 2022:2023,
 #'                                       parameters = "t2m",
 #'                                       stations = c("HALA GĄSIENICOWA",

diff --git a/R/meteo_imgw_monthly.R b/R/meteo_imgw_monthly.R
@@ -9,31 +9,30 @@
 #' (default status = FALSE - i.e. the status columns are deleted)
 #' @param coords add coordinates of the station (logical value TRUE or FALSE)
 #' @param station name or ID of meteorological station(s).
-#' It accepts names (characters in CAPITAL LETTERS) or stations' IDs (numeric)
+#' It accepts names (characters in CAPITAL LETTERS) or stations' IDs (numeric).
+#' Please note that station names may change over time and thus sometimes 2 names 
+#' are required in some cases, e.g. `c("POZNAŃ", "POZNAŃ-ŁAWICA")`.
 #' @param col_names three types of column names possible: "short" - default,
 #' values with shorten names, "full" - full English description,
 #' "polish" - original names in the dataset
-#' @param allow_failure logical - whether to proceed or stop on failure. By default set to TRUE (i.e. don't stop on error). For debugging purposes change to FALSE
+#' @param allow_failure logical - whether to proceed or stop on failure. 
+#' By default set to TRUE (i.e. don't stop on error). For debugging purposes change to FALSE
 #' @param ... other parameters that may be passed to the
 #' 'shortening' function that shortens column names
 #' @importFrom XML readHTMLTable
 #' @importFrom utils unzip read.csv
 #' @importFrom data.table fread
 #' @export
 #'
-#' @examples \donttest{
+#' @examples 
+#' \donttest{
 #'   monthly = meteo_imgw_monthly(rank = "climate", year = 1969)
 #'   head(monthly)
 #'
 #'   # a descriptive (long) column names:
 #'   monthly2 = meteo_imgw_monthly(rank = "synop", year = 2018,
 #'          col_names = "full")
 #'   head(monthly2)
-#'
-#'   # please note that station names may change over time
-#'   # and thus 2 names are required in some cases:
-#'   # df = meteo_imgw_monthly(rank = 'synop', year = 1991:2000,
-#'   #         coords = TRUE, station = c("POZNAŃ","POZNAŃ-ŁAWICA"))
 #' }
 #'
 meteo_imgw_monthly = function(rank = "synop",

diff --git a/R/meteo_metadata_imgw.R b/R/meteo_metadata_imgw.R
@@ -1,18 +1,13 @@
 #' Meteorological metadata
 #'
-#' Downloading the description (metadata) to the meteorological data available in the dane.imgw repository.imgw.pl.
+#' Downloading the description (metadata) to the meteorological data available in the 
+#' danepubliczne.imgw.pl collection.
 #' By default, the function returns a list or data frame for a selected subset
 #'
 #' @param interval temporal resolution of the data ("hourly", "daily", "monthly")
 #' @param rank rank of station ("synop", "climate", "precip")
 #' @keywords internal
-#'
-#' @examples
-#' \donttest{
-#'   #meta = climate:::meteo_metadata_imgw(interval = "hourly", rank = "synop")
-#'   #meta = climate:::meteo_metadata_imgw(interval = "daily", rank = "synop")
-#'   #meta = climate:::meteo_metadata_imgw(interval = "monthly", rank = "precip")
-#' }
+#' @noRd
 
 meteo_metadata_imgw = function(interval, rank) { # interval can be: monthly, hourly, hourly
 
@@ -64,7 +59,7 @@ meteo_metadata_imgw = function(interval, rank) { # interval can be: monthly, hou
                                rank = "precip", interval = "monthly")
     }
 
-  } # koniec MIESIECZNYCH
+  } # end of monthly interval
 
   ## hourly data section:
   if (interval == "hourly") {

diff --git a/R/meteo_noaa_co2.R b/R/meteo_noaa_co2.R
@@ -35,10 +35,15 @@
 #' @importFrom utils data
 #' @export
 #'
-#' @examples \donttest{
-#'   #co2 = meteo_noaa_co2()
-#'   #head(co2)
-#'   #plot(co2$yy_d, co2$co2_avg, type='l')
+#' @examples
+#' \donttest{
+#'   co2 = meteo_noaa_co2()
+#'   head(co2)
+#'   plot(x = co2$yy_d, y = co2$co2_avg, 
+#'        type='l', 
+#'        main = "CO2 concentration at Mauna Loa Observatory",
+#'        xlab = "years", 
+#'        ylab = "CO2 (ppm)")
 #' }
 #'
 

diff --git a/R/meteo_noaa_hourly.R b/R/meteo_noaa_hourly.R
@@ -17,8 +17,6 @@
 #' # London-Heathrow, United Kingdom
 #'   noaa = meteo_noaa_hourly(station = "037720-99999", year = 1949)
 #' }
-#'
-
 
 meteo_noaa_hourly = function(station = NULL,
                              year = 2019,

diff --git a/R/meteo_shortening_imgw.R b/R/meteo_shortening_imgw.R
@@ -10,7 +10,7 @@
 #' @examples 
 #' \donttest{
 #'   monthly = meteo_imgw("monthly", rank = "climate", year = 1969)
-#'   # colnames(monthly)
+#'   
 #'   abbr = meteo_shortening_imgw(data = monthly,
 #'       col_names = "full", 
 #'       remove_duplicates = TRUE)

diff --git a/R/nearest_stations_ogimet.R b/R/nearest_stations_ogimet.R
@@ -19,10 +19,10 @@
 #'  
 #' @examples 
 #' \donttest{
-#'   nearest_stations_ogimet(country = "Uniced Kingdom", 
+#'   nearest_stations_ogimet(country = "United Kingdom", 
 #'                           point = c(-2, 50),
 #'                           add_map = TRUE, 
-#'                           no_of_stations = 0, 
+#'                           no_of_stations = 50, 
 #'                           allow_failure = TRUE,
 #'                           main = "Meteo stations in UK")
 #' }

diff --git a/R/ogimet_daily.R b/R/ogimet_daily.R
@@ -12,10 +12,9 @@
 #' @importFrom utils setTxtProgressBar txtProgressBar
 #' 
 #' @export
-#' 
-#' @keywords internal
 #'
-#' @examples \donttest{
+#' @examples 
+#' \donttest{
 #'   # downloading daily summaries for last 30 days. station: New York - La Guardia
 #'   new_york = ogimet_daily(station = 72503, coords = TRUE)
 #' }

diff --git a/R/ogimet_hourly.R b/R/ogimet_hourly.R
@@ -183,7 +183,6 @@ ogimet_hourly_bp = function(date = date,
     suppressWarnings(data_station[, columns] <-
       as.data.frame(sapply(data_station[,columns], as.numeric)))
 
-    #  TODO:
     # changing order of columns and removing blank records:
     if (coords) {
       ord1 = c("station_ID", "Lon", "Lat", "Date", "TC")

diff --git a/R/onAttach.R b/R/onAttach.R
@@ -4,7 +4,7 @@
 #' @export
 
 .onAttach = function(libname, pkgname) {
-  if ((runif (1) < 0.25) & interactive()) { # activate occasionally and only if not run as Rscript
+  if ((runif(1) < 0.25) & interactive()) { # activate occasionally and only if not run as Rscript
     ver = as.character(packageVersion("climate"))
     packageStartupMessage(paste0(c("\n____________________________________________________________________\n",
                                  "  Welcome to climate ", ver, "!",

diff --git a/R/precip_split.R b/R/precip_split.R
@@ -5,8 +5,8 @@
 #' @param pattern 6h-12h-24h precipitation pattern to obtain written as: "/6h", "/12h" , "/24h" (see examples)
 #' 
 #' @keywords internal
-#'
-#'
+#' @noRd
+
 precip_split = function(precip,  pattern = "/12") {
   b = strsplit(precip, "h", fixed = TRUE)
   b = lapply(b, function(x) x[grepl(x, pattern = pattern, fixed = TRUE)])

diff --git a/R/profile_demo.R b/R/profile_demo.R
@@ -1,7 +1,7 @@
 #' @name profile_demo
 #' @title Exemplary sounding profile from University of Wyoming dataset
 #'
-#' @description The object contains pre-downloaded atmospheric (sounding) profile for Łeba, PL rawinsonde station.
+#' @description The object contains pre-downloaded atmospheric (sounding) profile for Leba, PL rawinsonde station.
 #' The measurement was taken 2000/03/23 at 00 UTC.
 #' 
 #' @importFrom utils data

diff --git a/R/sounding_wyoming.R b/R/sounding_wyoming.R
@@ -2,7 +2,7 @@
 #'
 #' Downloading the measurements of the vertical profile of atmosphere (also known as sounding data). Data can be retrieved using TEMP and BUFR sounding formatting.
 #'
-#' @param wmo_id international WMO station code (World Meteorological Organization ID); For Polish stations: Łeba - 12120, Legionowo - 12374, Wrocław- 12425
+#' @param wmo_id international WMO station code (World Meteorological Organization ID); For Polish stations: Leba - 12120, Legionowo - 12374, Wrocław- 12425
 #' @param yy year - single number
 #' @param mm month - single number denoting month
 #' @param dd day - single number denoting day
@@ -41,11 +41,11 @@
 #' ##############################################################################
 #'   TEMP = sounding_wyoming(wmo_id = 45004, yy = 2021, mm = 07, dd = 17, 
 #'                           hh = 12, min = 00)
-#'   #head(TEMP[[1]])
+#'   head(TEMP[[1]])
 #'   
 #'   BUFR = sounding_wyoming(wmo_id = 45004, yy = 2021, mm = 07, dd = 17, 
 #'                           hh = 12, min = 00, bufr = TRUE)
-#'   #head(BUFR[[1]])
+#'   head(BUFR[[1]])
 #' 
 #' 
 #' ##############################################################################
@@ -57,8 +57,7 @@
 #'                              mm = sample(1:12,1), 
 #'                              dd = sample(1:20,1), 
 #'                              hh = 0)
-#'   # head(profile)
-#'   # plot(profile[[1]]$HGHT, profile[[1]]$PRES, type = 'l')
+#'   plot(profile[[1]]$HGHT, profile[[1]]$PRES, type = 'l')
 #' }
 #'
 

diff --git a/R/spheroid_dist.R b/R/spheroid_dist.R
@@ -7,7 +7,7 @@
 #' @param p1 coordinates of the first point in decimal degrees (LON, LAT)
 #' @param p2 coordinates of the second point in decimal degrees (LON, LAT)
 #' 
-#' @return distance between two locations in kilometers
+#' @return distance between two locations (in kilometers)
 #' @export
 
 #' @examples 

diff --git a/R/stations_meteo_imgw_telemetry.R b/R/stations_meteo_imgw_telemetry.R
@@ -2,11 +2,13 @@
 #'
 #' Retrieving current metadata for stations used in the telemetric systems of the IMGW-PIB datastore (danepubliczne.imgw.pl/datastore)
 #' 
-#' @return data table with metadata for over 500 stations. Metadata contains: station ID, station name, river, latitude, longitude, altitude
+#' @return data table with metadata for over 500 stations. 
+#' Metadata contains: station ID, station name, river, latitude, longitude, altitude
 #' @importFrom data.table as.data.table
 #' @export
 #'
-#' @examples \donttest{
+#' @examples 
+#' \donttest{
 #'   telemetry_stations = stations_meteo_imgw_telemetry()
 #' }
 #'