%% File getCatchments.Rd
%% Part of 'RcamelsCL' R package, https://gitlab.com/hgarcesf/RcamelsCL ;
%%                               https://cran.r-project.org/package=RcamelsCL
%% Copyright 2024-2025 Hector Garces-Figueroa and Mauricio Zambrano-Bigiarini
%% Distributed under GPL 2 or later

\name{getCatchments}
\Rdversion{1.1}
\alias{getCatchments}
\alias{getCatchments.default}

\title{getCatchments}
\description{
Select catchments from the CAMELS-CL dataset based on user-defined attribute
filters.
}
\usage{
getCatchments(attr, op, attr.val, include.values = FALSE, attr.val2 = NULL,
              include.lower = TRUE, include.upper = TRUE,
              get.data = FALSE, ...)
}
\arguments{
  \item{attr}{
Character. Name of the catchment attribute used for filtering.

See \code{RcamelsCL:::.print_attr_names()} for the list of valid
attribute names.
}
  \item{op}{
Character. Comparison operator applied to \code{attr}. Valid values are
\kbd{"=="}, \kbd{"<"}, \kbd{"<="}, \kbd{">"}, \kbd{">="} or \kbd{"between"}.
}
  \item{attr.val}{
Numeric or character. Threshold used together with \code{op} to filter the
selected attribute. When \code{op = "between"}, \code{attr.val} defines
the lower limit of the range.
}
  \item{include.values}{
Logical. If TRUE, the output includes both the catchment IDs and their
attribute values. If FALSE, only the IDs are returned. Default is \kbd{FALSE}.
}
  \item{attr.val2}{
Numeric. Upper limit of the range when \code{op = "between"}.
}
  \item{include.lower}{
Logical. Should the lower limit defined in \code{attr.val} be included
in the \kbd{"between"} operation? Default is \kbd{TRUE}.
}
  \item{include.upper}{
Logical. Should the upper limit defined in \code{attr.val2} be included
in the \kbd{"between"} operation? Default is \kbd{TRUE}.
}
  \item{get.data}{
Logical. If \kbd{TRUE}, the function returns the data for each identified
catchment using \code{RcamelsCL::getData()}. If \kbd{FALSE}, only the
matching catchment IDs are returned. Default is \kbd{FALSE}.
}
  \item{\dots}{
Additional arguments passed to \code{RcamelsCL::getData()} when
\code{get.data = TRUE}. See \code{?RcamelsCL::getData} for details on the
supported options.
}
}
\details{
\code{getCatchments()} filters the CAMELS-CL catchments by applying a
user-defined condition to a single attribute. The condition is specified
through a comparison operator (\code{op}) and one or two threshold values
(\code{attr.val} and \code{attr.val2}, when \code{op = "between"}).

The function first identifies all catchments whose attribute values satisfy
the specified condition. By default, only the corresponding catchment IDs
are returned. When \code{get.data = TRUE}, \code{getCatchments()} internally
calls \code{getData()} for each identified catchment, returning their data
in a list.
}
\value{
If \code{get.data = FALSE}, a numeric vector containing the IDs of all
catchments that satisfy the specified attribute filter.

If \code{get.data = TRUE}, a list where each element corresponds to the
output of \code{getData()} for one of the selected catchments.
}
\references{
\url{https://camels.cr2.cl}

\cite{Alvarez-Garreton, C.; Mendoza, P. A.; Boisier, J. P.; Addor, N.; Galleguillos, 
M.; Zambrano-Bigiarini, M.; Lara, A.; Puelma, C.; Cortes, G.; Garreaud, R.; McPhee, J.; 
and Ayala, A. (2018). The CAMELS-CL dataset: catchment attributes and meteorology 
for large sample studies - Chile dataset, Hydrology and Earth System Sciences 22, 
5817-5846. doi:10.5194/hess-22-5817-2018.}
}
\author{
Hector Garces-Figueroa <hegarcesf@gmail.com>
}
\examples{
##################
\donttest{
# Example 1: Getting the IDs of catchments whose most common geologic class is
# "Pyroclastics"
x1 <- getCatchments(attr = "geol_class_1st", attr.val = "Pyroclastics")
head(x1)

# Example 2: Getting the IDs of catchments whose most common geologic class is
# "Pyroclastics" and the daily time series of hydrometeorological variables
x2 <- getCatchments(attr = "geol_class_1st", attr.val = "Pyroclastics",
                    get.data = TRUE)
str(x2, 1)

# Example 3: Getting the IDs of catchments whose most common geologic class is
# "Pyroclastics" and the monthly time series of hydrometeorological variables
x3 <- getCatchments(attr = "geol_class_1st", attr.val = "Pyroclastics",
                    get.data = TRUE, tscale = "monthly")
str(x3, 1)

# Example 4: Getting the IDs of catchments whose most common geologic class is
# "Pyroclastics", the monthly time series of hydrometeorological variables,
# and the shapefile of the selected catchments
x4 <- getCatchments(attr = "geol_class_1st", attr.val = "Pyroclastics",
                    get.data = TRUE, tscale = "monthly", include.shp = TRUE)
str(x4, 2)

# Example 5: Getting the IDs of catchments with area greater than or equal to
# 20,000 km2
x5 <- getCatchments(attr = "area_km2", op = ">=", attr.val = 20000)
head(x5)

# Example 6: Getting the IDs of catchments with area less than or equal to
# 20,000 km2 and the corresponding area values for each selected catchment
x6 <- getCatchments(attr = "area_km2", op = "<=", attr.val = 20000,
                    include.values = TRUE)
head(x6)

# Example 7: Getting the IDs of catchments with area greater than or equal to
# 20,000 km2 but less than 25,000 km2
x7 <- getCatchments(attr = "area_km2", op = "between", attr.val = 20000,
                    attr.val2 = 25000, include.lower = TRUE,
                    include.upper = FALSE)
head(x7)

# Example 8: Getting the IDs of catchments with area greater than 20,000 km2
# but less than or equal to 25,000 km2, and the monthly time series of
# hydrometeorological variables
x8 <- getCatchments(attr = "area_km2", op = "between", attr.val = 20000,
                    attr.val2 = 25000, include.lower = FALSE,
                    include.upper = TRUE, get.data = TRUE)
str(x8, 2)

# Example 9: Getting the IDs of catchments with area greater than 20,000 km2
# but less than or equal to 25,000 km2, the corresponding area values for
# each selected catchment, and the daily time series of hydrometeorological
# variables
x9 <- getCatchments(attr = "area_km2", op = "between", attr.val = 20000,
                    attr.val2 = 25000, include.lower = FALSE,
                    include.upper = TRUE, get.data = TRUE,
                    include.values = TRUE)
str(x9, 2)
}
}
\keyword{ data }