Package 'lakeRS'

Description

Adds a human-readable lake name and a stable lake identifier to a list created by seasonal_index_per_lake(). If no identifier is supplied, an identifier is generated from the mean x and y coordinates of the lake grid.

Usage

add_lakeID(lakeIndex, lakeName = NULL, lakeID = NULL)

Arguments

Value

The input list with two additional elements: Name and ID.

Description

Calculates the north, east, south, and west limits of a square-like bounding box around a point in WGS 84 coordinates. The limits are computed by moving a fixed geodesic distance from the point in the four cardinal directions.

Usage

bbox_from_point(lat, lon, meters = 20)

Arguments

Value

A named numeric vector with elements north, east, south, and west, suitable for start_openEO_job() or display_geometry().

Description

Expands a latitude-longitude rectangle by a geodesic buffer distance and returns the resulting north, east, south, and west limits.

Usage

bbox_from_rectangle(top_lat, bottom_lat, left_lon, right_lon, meters = 20)

Arguments

Value

A named numeric vector with elements north, east, south, and west.

Description

Runs k-means clustering for increasing numbers of clusters and recommends the largest number that still satisfies a minimum cluster-size criterion. The decision is based on the proportion of variance explained by the clustering.

Usage

best_nk(
  pixelDynamic,
  kMax = 10,
  minimum_clusterSize = 0.01,
  correlate_first = FALSE
)

Arguments

Details

At most 10,000 pixels are sampled before testing cluster counts. If correlate_first = TRUE, the selected pixels are correlated with at most 1,000 reference pixels. See prepare_for_clustering() for details on NA handling and optional correlation pre-processing.

Value

Integer giving the recommended number of clusters. The function also draws a diagnostic plot of explained variance by number of clusters.

Description

Combines multiple annual outputs from dynamic_per_pixel() into summary curves across years. For each day of year, the function averages the annual median lake dynamics and calculates the standard deviation across those annual medians.

Usage

combine_years_dynamic(indexDynamicList, years = NULL)

Arguments

Details

All selected dynamics must have been computed with the same days_around_ma; otherwise the function stops because the smoothing windows are not comparable.

Value

A list with mean_of_median and sd_over_median, each a numeric vector with one value per day of year.

Description

Converts a list of annual lake index objects into a wide table with one row per lake and one index column per year.

Usage

combine_years_lakeData(lakeIndexList, aggregationType = "modus")

Arguments

Details

The function warns if lake names or IDs are not unique in the output.

Value

A data.frame with lake identifiers (name, id) and one wide ⁠year_<year>⁠ column per available year.

Description

This function merges multiple annual lake index maps (each produced by seasonal_index_per_lake()) into a unified per-pixel dataset. It ensures that all years are represented on a common spatial grid. If differences in CRS or grid alignment between years exist, the rasters are resampled to match the most recent year's configuration.

Usage

combine_years_pixelData(lakeIndexList)

Arguments

Details

The function performs the following steps:

1. Validates input to ensure lakeIndexList is a list of lists.

2. Extracts available years and their corresponding CRS values.

3. Selects the most recent year to define the target grid.

4. For each year, checks grid compatibility; if needed, resamples to the target resolution and CRS using bilinear interpolation.

5. Merges all years’ pixel tables into a single data frame by coordinates.

Value

A list with the following elements:

yearsIndex

A data.frame where each row corresponds to a pixel position (x, y, i_row, i_col) and each yYYYY column stores the pixel values of that year.

crs

A character string giving the CRS of the final combined grid.

See Also

seasonal_index_per_lake(), terra::resample(), terra::rast()

Description

Calculate adjusted linear trends over recent years

Usage

determine_trend(yearly_spread = yearly_spread, tyears = 3, ttype = "short")

Arguments

Details

In order to rule out systematic errors based on weather conditions in a year, different hardware or algorithms, the difference between the overall median value of all lakes (or all pixels) and years and the yearly median value of all lakes(or all pixels) is added to the Index of a lake (or pixel) before the trends are calculated. Median values are based on lakes or pixels for which data is available in all considered years. Subsequantly, the trend is calculated as linear regression between previous years and adjusted NDTrI values. For a reliable trend assessment the number of lakes needs to be large enough (n>10). Only rows with complete data in all year columns are used to estimate the global and yearly medians for the bias correction. Individual row trends are returned as NA if any value in the selected trend window is missing.

Value

A list with trends, periodYear, overallMedian, and yearlyMedians. trends contains the slope and the standard error of the slope for each row.

Description

Assigns each yearly index value to one of nClass classes. Break points are computed separately for each year using the observed minimum and maximum as outer bounds and equally spaced inner breaks between lower and upper quantiles.

Usage

discreteClassAssessment(yearly_spread, nClass = 10, proportionExtreme = 0.05)

Arguments

Details

If the requested extreme proportion would create class sizes smaller than one class share, it is reduced to 1 / nClass. #' Breaks are constructed using actual data min/max for outer bounds and creates nClass - 2 equally spaced classes between the proportionExtreme quantiles (1 - proportionExtreme and 0 + proportionExtreme).

Value

A list with assessment, breaks, nClass, and proportionExtreme. assessment is the input data frame with additional ⁠<year>_class⁠ columns. breaks contains the class boundaries for each year.

Description

Creates an interactive leaflet map for quickly checking the spatial extent that will be used for an openEO request.

Usage

display_geometry(geom, zoom = 15)

Arguments

Details

Polygon coordinates are expected as latitude-longitude pairs, matching common copy/paste formats from map tools. They are internally switched to longitude-latitude order for leaflet. Bounding Box as a named vector or c("north" = lat1, "east" = lon1, "south" = lat2, "west" = lon2) or a list of pairs list(c(lat1, lng2), c(lat2, lon2), c(lat3, lon3))

Value

A leaflet map object with either a rectangle or polygon overlay.

Description

Searches for a finished openEO job by title or ID and downloads its results to a local folder. The function assumes that the user is already connected and authenticated with openEO.

Usage

download_openEO_job(
  title,
  path,
  recentJob = TRUE,
  ID = NULL,
  overwrite = FALSE
)

Arguments

Value

Invisibly returns NULL. On success, job assets are written to file.path(path, title). If the job is not finished, a message is printed and no files are downloaded.

Description

Converts image-wise remote-sensing index matrices into pixel-wise time series and calculates smoothed 365-day dynamics. The output includes lake-level summary statistics and, optionally, the individual pixel dynamics.

Usage

dynamic_per_pixel(
  imageIndex,
  nc,
  water_scenes_only = TRUE,
  days_around_ma = 20,
  maxPixels = 1000,
  pixelFilter = NULL,
  pixelQualityThreshold = 0.8,
  maxDataPoints = 5e+06,
  returnSinglePixels = TRUE
)

Arguments

Details

For each day of year, all images within days_around_ma days before and after the target day are averaged. A moving average is only calculated if more than one image falls into the window. Long periods without image availability are set to NA to avoid excessive temporal extrapolation.

Value

A list with lakeDynamic, crs, year, days_around_ma, and dataAvailabilityThreshold. If returnSinglePixels = TRUE, the list also contains x, y, and pixelDynamics.

Description

Orders lakes or rows from a numericAssessment() result according to the selected trend column.

Usage

find_trends(
  numericAssessment,
  trendType,
  bestTrendFirst = FALSE,
  outputVector = "lakeID"
)

Arguments

Value

An ordered vector of lake IDs, lake names, or row numbers. Rows with missing trend values are removed from the ranking.

Description

Create a matrix of clusters in the same dimension as Datacube nc

Usage

get_clusterLayer(clusterVector, nc)

Arguments

Description

Extracts all time layers of a selected Sentinel-2 band from an open_netcdf() object, optionally restricted to selected months and years.

Usage

load_BandLayer(nc, band, monthFilter = NULL, yearFilter = NULL)

Arguments

Details

Negative band values are set to zero before matrices are returned. This is intended for reflectance bands and follows the Sentinel-2 pre-processing convention to harmonize data (https://docs.sentinel-hub.com/api/latest/data/sentinel-2-l2a/)

Value

A list containing coordinates, time metadata, CRS, and band, a list of matrices with one matrix per retained time step.

Description

Reprojects a matrix aligned with an open_netcdf() object to WGS 84 and adds it as a raster overlay on an interactive leaflet map.

Usage

map_layer(
  ncLayer,
  nc,
  lowerLimits = NULL,
  highestValue = NULL,
  classColors = NULL,
  valueRange = NULL,
  legendTitle = NULL,
  plotLegend = TRUE
)

Arguments

Details

The function supports a hex-color mode when all values of ncLayer are character strings beginning with ⁠#⁠.

Value

A leaflet map object.

Description

Calculates the proportion of pixels belonging to a selected Sentinel-2 SCL scene group for each image in a netCDF data cube.

Usage

nc_scene_per_image(nc, scene = "clouds")

Arguments

Details

Scene groups are mapped to SCL codes as follows: clouds = 8, 9, 10; water = 6; snow = 11; shadows = 2, 3.

Value

A data.frame with columns date and coverage. coverage is the proportion of pixels in the selected scene group for each image.

Description

Loads two bands from a netCDF data cube and calculates an pixel-wise normalized difference index for each retained time step.

Usage

ndi_per_image(nc, year, bandNames = c("B05", "B02"), monthFilter = NULL)

Arguments

Details

Band values are loaded through load_BandLayer(), which sets negative values to zero before index calculation.

Value

A list containing x, y, t, t_date, crs, and RSindex. The RSindex element is a list of matrices, one per image.

Description

Colors for the Index

Usage

NDTrIColors

Format

A dataframe of two columns. "ndtri" listing the values of the noramlized diference trophic index and "color" specifying the corresponding colors

Description

Adds moving-average status and relative short- and long-term trend estimates to a wide table of yearly index values.

Usage

numericAssessment(
  yearly_spread,
  statusYears = 3,
  shortTermYears = 3,
  longTermYears = 10
)

Arguments

Details

In order to rule out systematic errors based on weather conditions in a year, different hardware or algorithms, the difference between the overall median value of all lakes (or pixels) and years and the yearly median value of all lakes (or pixels) is added to each index per year before the trends are calculated. Thus, the trends of one lake (or pixel) are relative compared to the other lakes (or pixels) of the table. The trend is calculated as linear regression between previous years and adjusted NDI values. For a reliable trend assessment the number of lakes (or pixels) needs to be large enough (n>10).

Value

A list with assessment and periods. assessment is the input data frame extended by status and trend columns where possible. periods records the three period lengths used.

Description

Combines a list of annual seasonal_index_per_lake() outputs for one lake into a long-format summary table.

Usage

oneLake_df(lakeIndexList)

Arguments

Value

A data.frame with lake name, lake ID, year, median index, standard deviation, selected modal index, number of valid pixels, and quality threshold.

Description

Reads a netCDF file into a terra SpatRaster and extracts spatial, temporal, band, and CRS metadata used by the lakeRS processing workflow.

Usage

open_netcdf(filePath, fileName = "openEO.nc")

Arguments

Details

The function stops if subdatasets in the netCDF file have different row, column, or layer dimensions.

Value

A list with bands, x, y, t, t_date, crs, and SpRast. x and y are pixel-center coordinates, t contains numeric time steps, and t_date converts these time steps to dates using origin 1990-01-01.

Description

Performs k-means clustering on pixel-level moving-average dynamics and returns cluster assignments, cluster centers, and selected k-means diagnostics.

Usage

pixel_clusters(
  pixelDynamic,
  k,
  iter.max = 20,
  nstart = 10,
  correlate_first = FALSE,
  whole_dynamic = FALSE
)

Arguments

Value

A list with clusterVector, clusterCenter, kmeansOut, and days_included.

Description

Draws a class-by-year heatmap for selected lakes from a discreteClassAssessment() result.

Usage

plot_class_assessment(
  class_assessment,
  lakeNames = NULL,
  lakeIDs = NULL,
  rowNumbers = NULL
)

Arguments

Details

At least one of lakeNames, lakeIDs, or rowNumbers must identify rows. Colors are generated by rescale_classColors().

Value

No explicit return value. The function draws a base R plot.

Description

Draws one or more 365-day time series and optionally overlays 50% and 95% interval polygons. The function is designed for lake-level or cluster-level dynamics derived from dynamic_per_pixel() or combine_years_dynamic().

Usage

plot_dynamic(
  v_averageList,
  v_sdList = NULL,
  df_q50List = NULL,
  df_q95List = NULL,
  TScolors = lakeRS::tenClusterColors$color,
  TSnames = NULL,
  df_reference = NULL,
  RefName = NULL,
  lakeName = "",
  ylab = "Index",
  ylim = NULL
)

Arguments

Details

Month separators and labels are drawn for a non-leap 365-day year. Missing interval values are removed with rm_na_for_polygon() before polygons are drawn.

Value

No explicit return value. The function draws a base R plot.

Description

Draws a histogram and density curve of all valid pixel-level index values for a lake in one year. The selected modal value and median are highlighted.

Usage

plot_lake_index_histogram(lakeIndex, lakeName = "", indexName = "")

Arguments

Details

The current implementation reads lakeIndex$nValidePixel, matching the current spelling in seasonal_index_per_lake().

Value

NULL if no valid pixels are available; otherwise no explicit return value. The function draws a base R plot.

Description

Reprojects a matrix aligned with a netCDF grid to WGS 84 and plots it with a distance scale and optional legend using base graphics.

Usage

plot_layer(
  ncLayer,
  nc,
  lowerLimits = NULL,
  classColors = NULL,
  highestValue = NULL,
  valueRange = NULL,
  legendTitle = NULL,
  plotLegend = TRUE
)

Arguments

Details

The plot is scaled according to geodesic width and height estimated with geosphere::distGeo(). The helper plot_scale() adjusts the plot region to preserve the map's aspect ratio.

Value

No explicit return value. The function draws a base R plot.

Description

Creates a multi-panel base R plot showing one selected lake's yearly index values, moving-average status, and long- and short-term trend estimates.

Usage

plot_numeric_assessment(
  numericData,
  lakeName = NULL,
  lakeID = NULL,
  rowNumber = NULL,
  ylab = "Index"
)

Arguments

Details

Exactly one lake should be selected, either by row number, lake name, or lake ID. The first panel shows the distribution of all lakes as quantile bands and overlays the selected lake's annual values and status line. The two trend panels show point estimates with approximate 95% intervals.

Value

No explicit return value. The function opens a graphics device and draws the assessment plot.

Description

Visualizes image dates over the day of year, grouped by year, and colors each image according to a scene-coverage proportion.

Usage

plot_scene_coverage(
  vDate,
  vCoverage = NULL,
  upperLimits = c(0.05, 0.1, 0.3, 0.5, 0.75, 1)
)

Arguments

Details

Duplicate images on the same day of year are vertically offset within the year row. The right axis shows the number of images per year.

Value

No explicit return value. The function draws a base R plot.

Description

Cleans and optionally transforms a pixel-by-day moving-average matrix before k-means clustering.

Usage

prepare_for_clustering(
  moving_averages_matrix,
  correlate_first = FALSE,
  maxPixels = NULL
)

Arguments

Details

Values are rounded with signif() before clustering. Depending on the NA pattern, the function removes either rows with missing values or pixels with missing values and reports removals via warnings. If correlation pre-processing is requested, at most 1,000 reference pixels are sampled.

Value

A numeric matrix used as input for clustering. Columns represent pixels when correlate_first = FALSE; otherwise the matrix contains rounded correlation profiles.

Description

Reprojects a terra input raster to a specified target coordinate reference system (CRS), preserving the original number of rows and columns. The spatial extent of the raster is transformed to the new CRS, and a new raster template is created to match these dimensions before projection.

Usage

sameDimProjection(initial_raster, finalCRS = "EPSG:4326")

Arguments

Details

The input extent is projected to the target CRS and used to create a template raster. Projection uses nearest-neighbor resampling (method = "near"), which is appropriate for categorical layers and avoids creating interpolated class values.

Value

A SpatRaster object reprojected to the specified CRS, maintaining the same number of rows and columns as the input raster.

See Also

terra::project(), terra::rast(), terra::ext()

Description

Adds a mobile-friendly viewport meta tag to a leaflet widget and saves it as a self-contained HTML file.

Usage

save_leaflet(x, file)

Arguments

Value

The return value of htmlwidgets::saveWidget(). The main side effect is writing file.

Description

Sentinel-2 IDs of the SCL Band

Usage

sceneIDs

Format

A data frame of two columsn 1) SCL ID and 2) SCL name

Description

Summarizes the pixel-level seasonal index matrix of one lake and year into lake-level statistics, including median, standard deviation, density-based modal candidates, and a selected modal index value.

Usage

seasonal_index_per_lake(seasonIndex, lakeName = NULL, lakeID = NULL)

Arguments

Details

If more than one valid pixel is available, potential modes are detected from a kernel density estimate using bw = "SJ" and adjust = 2. Among sufficiently high local maxima, the mode with the highest density is selected as IndexModusBest. If exactly one valid pixel is available, that value is used for both median and mode.

Value

A list with index statistics (IndexModusBest, IndexMedian, IndexSD, IndexModusPot, IndexDensity, IndexPixel), metadata (QualityThreshold, x, y, crs, year), and lake identifiers (Name, ID).

Description

Filters image-wise index matrices by Sentinel-2 SCL information, averages the remaining index values pixel by pixel, and removes pixels that do not meet a water-scene quality threshold.

Usage

seasonal_index_per_pixel(
  imageIndex,
  nc,
  water_scenes_only = TRUE,
  pixelQualityThreshold = 0.8
)

Arguments

Details

Water-scene proportions are calculated by waterscene_proportion(). A warning is issued if no pixel meets pixelQualityThreshold.

Value

A list with x, y, crs, year, QualityThreshold, RSindex, and sceneProportions. RSindex is a matrix of seasonal pixel index values; pixels below the water-quality threshold are set to NA.

Description

Projects input coordinates to WGS 84 and displays them as circle markers on a leaflet map.

Usage

show_pixels(x, y, crs, labels = NULL)

Arguments

Details

The marker colors are currently hard-coded as c("blue", "green", "orange", "purple"). If the number of points exceeds the number of colors, colors will be recycled.

Value

A leaflet map object.

Description

Builds an openEO process graph for a Sentinel-2 collection, spatial and temporal extent, optional property filters, and selected bands. The graph is saved as the requested output format and started as an openEO batch job.

Usage

start_openEO_job(
  title,
  geom,
  tBeg,
  tEnd,
  crs = 4326,
  collection = "SENTINEL2_L2A",
  bands = list("B02", "B05", "SCL"),
  relativeOrbitNumber = NULL,
  tileID = NULL,
  outputFormat = "netCDF",
  uniqueTitle = TRUE
)

Arguments

Details

Laitude-Longitude Pairs are switched to longitude-latitude which is the required order of openEO, however providing the data as latitude-longitude is more convient beacuse it is the google maps output format

Value

This function only returns the title of the job that is started on openEO. To download the job use function download_openEO_job

Description

Colors for the Classes

Usage

tenClassColors

Format

A data frame of two columns. "class" listing the classes 1 to 10 and "color" specifying the corresponding colors

Description

Colors for the Clusters

Usage

tenClusterColors

Format

A data frame of two columns. "cluster" listing the clusters 1 to 10 and "color" specifying the corresponding colors

Description

Adds categorical trend-significance and trend-strength columns to an assessment table containing trend estimates and standard errors.

Usage

trends_to_classes(assessmentTable, trendType = "long")

Arguments

Details

Significance classes are 0 if zero lies within ±1 standard error, ⁠±1⁠ if zero lies outside ±1 but inside ±2 standard errors, and ⁠±2⁠ if zero lies outside ±2 standard errors. Positive trend estimates are converted to negative classes, so class sign follows the package's interpretation that a negative numerical trend indicates improvement of the trophic index.

Value

The input data frame extended by ⁠trend_<trendType>_significance⁠ and ⁠trend_<trendType>_strength⁠.

Description

Computes per-pixel proportions for all Sentinel-2 SCL classes and derives a water-scene proportion after accounting for disturbance classes.

Usage

waterscene_proportion(scl_image)

Arguments

Details

The water proportion is defined as all pixels that are "correctly" classified as water. Thus, disturbances that occur but are not a false classification like clouds, snow or topographic impacts need to be removed before. After removing those pixels, the water classifiation should be 100% for a perfect pixel

Value

A list with water, NoFalseDisturbance, and allScenes. water is the derived water-scene proportion per pixel; NoFalseDisturbance is the proportion of pixels assigned to allowed disturbance classes; allScenes is a list of per-class proportions.