pysits 2.0.0.dev0__tar.gz → 2.0.0.dev1__tar.gz

{pysits-2.0.0.dev0 → pysits-2.0.0.dev1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pysits
-Version: 2.0.0.dev0
+Version: 2.0.0.dev1
 Summary: Python wrapper for the sits R package
 Project-URL: Homepage, https://github.com/e-sensing/pysits
 Project-URL: Issue Tracker, https://github.com/e-sensing/pysits/issues

{pysits-2.0.0.dev0 → pysits-2.0.0.dev1}/pyproject.toml

@@ -17,7 +17,7 @@
 
 [project]
 name = "pysits"
-version = "2.0.0.dev0"
+version = "2.0.0.dev1"
 description = "Python wrapper for the sits R package"
 readme = "README.md"
 requires-python = ">=3.10,<4"

pysits-2.0.0.dev1/pysits/docs/content/impute_linear.md

@@ -0,0 +1,9 @@
+Replace NA values by linear interpolation
+
+Remove NA by linear interpolation
+
+Args:
+    data (list | pandas.DataFrame): A time series vector or matrix.
+
+Returns:
+    R: A set of filtered time series using the imputation function.

pysits-2.0.0.dev1/pysits/docs/content/impute_mean.md

@@ -0,0 +1,9 @@
+Remove NA using mean
+
+Remove NA using mean
+
+Args:
+    data (list[float] | pandas.DataFrame): A time series or matrix.
+
+Returns:
+    R: A set of filtered time series using the imputation function.

pysits-2.0.0.dev1/pysits/docs/content/impute_mean_window.md

@@ -0,0 +1,23 @@
+Remove NA using weighted moving average
+
+Remove NA using weighted moving average
+
+Args:
+    data (list): A time series vector or matrix.
+    k (int): Width of the moving average window. Expands to both sides
+        of the center element e.g. k = 2 means 4 observations (2 left,
+        2 right) are taken into account. If all observations in the
+        current window are NA, the window size is automatically
+        increased until there are at least 2 non-NA values present.
+    weighting (str): The weighting strategy to be used. More details
+        below (default is "simple").
+
+Returns:
+    R: A set of filtered time series using the imputation function.
+
+Notes:
+    The `weighting` parameter defines the weighting strategy used in the
+    moving window. The strategies available are:
+    - `simple` - Simple Moving Average (SMA) (default option)
+    - `linear` - Linear Weighted Moving Average (LWMA)
+    - `exponential` - Exponential Weighted Moving Average (EWMA)

pysits-2.0.0.dev1/pysits/docs/content/impute_median.md

@@ -0,0 +1,9 @@
+Remove NA using median
+
+Remove NA using median
+
+Args:
+    data (list[float] | SITSMatrix): A time series vector or matrix.
+
+Returns:
+    R: A set of filtered time series using the imputation function.

pysits-2.0.0.dev1/pysits/docs/content/plot.md

@@ -0,0 +1,112 @@
+Plot sits objects.
+
+Unified plotting function that dispatches on the type of the object passed
+as `x`. It mirrors the many `plot` methods of the R `sits` package,
+covering data cubes (raster, SAR, DEM, vector, RGB), probability and
+uncertainty cubes, variance cubes, classified images, time series patterns
+and predictions, machine learning / deep learning models, clustering and
+self-organizing map (SOM) results, accuracy tables, and t-SNE / embedding
+visualizations. The set of accepted keyword arguments depends on the type
+of object being plotted.
+
+Args:
+    x (SITSCubeModel | SITSTimeSeriesModel | SITSTimeSeriesPatternsModel | SITSMachineLearningMethod | SITSConfusionMatrix): Object to be
+        plotted. Supported objects include classified raster images,
+        classified segments, digital elevation model cubes, multi-year
+        land use/cover embedding predictions, sample distances, class
+        temporal patterns, probability cubes, raster, SAR, and vector
+        data cubes, confusion matrices / accuracy metrics, dendrograms,
+        trained models, time series predictions, t-SNE projections, SOM
+        results, uncertainty cubes, and variance cubes.
+    y: Ignored. Present for compatibility with the generic `plot`.
+    band (str): Band used for plotting a single-band (grey scale) image.
+        Applies to raster, SAR, DEM, and vector cubes, and to SOM maps.
+    red (str): Band assigned to the red channel of an RGB composite
+        (raster, SAR, and vector cubes).
+    green (str): Band assigned to the green channel of an RGB composite.
+    blue (str): Band assigned to the blue channel of an RGB composite.
+    tile (str): Tile to be plotted (data cubes, probability, uncertainty,
+        and variance cubes).
+    dates (list[str]): Dates to be plotted (raster, SAR, and vector
+        cubes).
+    roi (dict | geopandas.GeoDataFrame): Spatial extent (region of
+        interest) to plot, in WGS 84.
+    labels (list[str]): Labels to plot (probability and variance cubes).
+    bands (list[str]): Bands to be viewed (patterns and time series
+        predictions).
+    legend (dict): Associates labels to colors, or a legend specification
+        for SOM plots.
+    legend_position (str): Where to place the legend (typically "inside"
+        or "outside", with defaults varying by plot type).
+    legend_title (str): Title of the legend (probability and variance
+        cubes).
+    palette (str): An RColorBrewer or "cols4all" (or HCL) palette used
+        for color mapping.
+    rev (bool): Whether to reverse the color order in the palette.
+    scale (float): Relative scale of plot text and map (typically 0.4 to
+        1.0).
+    quantile (float): Minimum quantile to plot (probability and variance
+        cubes).
+    first_quantile (float): First quantile for stretching images.
+    last_quantile (float): Last quantile for stretching images.
+    max_cog_size (int): Maximum size of COG (Cloud Optimized GeoTIFF)
+        overviews, in lines/columns or pixels.
+    seg_color (str): Color used to draw segment boundaries (vector cubes).
+    line_width (float): Line width used to draw segment boundaries
+        (vector cubes).
+    type (str): Type of plot; meaning depends on the object. For accuracy
+        objects it is "confusion_matrix" or "metrics"; for variance cubes
+        it is "map" or "hist"; for SOM maps it is "codes" or "mapping".
+    cluster: Cluster object produced by `sits_cluster_dendro`, used when
+        plotting a dendrogram.
+    cutree_height (float): Height at which to draw a dashed horizontal
+        line indicating where the dendrogram is cut.
+    name_cluster (str): Cluster to plot (SOM cluster evaluation).
+    title (str): Title of the plot (SOM cluster evaluation).
+    year_grid (bool): Whether to plot patterns as a grid of panels with
+        labels as columns and years as rows. Defaults to False.
+    tree_idx (int): Index of the tree to be plotted for an XGBoost model.
+    plot_embedding (str): For embedding predictions, either "none" (plot
+        only predicted class intervals) or "area" (overlay a smoothed
+        vertical embedding profile per year).
+    stretch (tuple[float, float]): For embedding plots, lower/upper
+        quantiles used to stretch embedding values before plotting.
+    class_alpha (float): Transparency of class polygons in embedding plots
+        (0-1).
+    area_alpha (float): Transparency of the embedding area in embedding
+        plots (0-1).
+    area_width (float): Horizontal width fraction of the embedding area.
+    area_spar (float): Smoothing parameter for the embedding area spline.
+    **kwargs (dict): Further specifications passed to the underlying plot.
+
+Returns:
+    None: A plot is produced. Depending on the input type this may be a
+    color map of classified pixels, an RGB or grey-scale image, a
+    probability or uncertainty map, a variance map (optionally with
+    segment overlays), a dendrogram, a confusion matrix, a SOM map, a
+    model diagnostic plot, or a plot for patterns, predictions,
+    embeddings, and t-SNE projections. Some methods are called only for
+    their side effect of drawing the plot.
+
+Notes:
+    The `roi` argument can be defined as a `dict` giving the spatial
+    extent (for example with `lon_min`, `lon_max`, `lat_min`, `lat_max`),
+    a `geopandas.GeoDataFrame`, or another spatial specification accepted
+    by `sits`. Vector cube plots overlay the segments produced by
+    `sits_segment` on top of the raster image; their appearance is
+    controlled by `seg_color` and `line_width`.
+
+Examples:
+    from pysits import *
+
+    # Plot a set of time series patterns
+    patterns = sits_patterns(cerrado_2classes)
+    plot(patterns)
+
+    # Train a random forest model and plot variable importance
+    rfor_model = sits_train(samples_modis_ndvi, ml_method=sits_rfor())
+    plot(rfor_model)
+
+    # Plot a SOM map produced from a set of samples
+    som_map = sits_som_map(samples_modis_ndvi)
+    plot(som_map)

pysits-2.0.0.dev1/pysits/docs/content/sits_accuracy.md

@@ -0,0 +1,80 @@
+Assess classification accuracy
+
+This function calculates the accuracy of the classification result. The input
+is either a set of classified time series or a classified data cube. Classified
+time series are produced by `sits_classify`. Classified images are generated
+using `sits_classify` followed by `sits_label_classification`.
+For a set of time series, `sits_accuracy` creates a confusion matrix and
+calculates the resulting statistics using package `caret`. For a classified
+image, the function uses an area-weighted technique proposed by Olofsson et al.
+according to references [1-3] to produce reliable accuracy estimates at 95%
+confidence level. In both cases, it provides an accuracy assessment of the
+classified, including Overall Accuracy, Kappa, User's Accuracy, Producer's
+Accuracy and error matrix (confusion matrix).
+
+Args:
+    data (SITSCubeModel | SITSTimeSeriesModel): Either a data cube with
+        classified images or a set of time series.
+    prediction_attr (str): Name of the column of the segments object that
+        contains the predicted values (only for vector class cubes).
+    reference_attr (str): Name of the column of the segments object that
+        contains the reference values (only for vector class cubes).
+    validation (str | pathlib.Path | pandas.DataFrame | geopandas.GeoDataFrame | SITSTimeSeriesModel):
+        Samples for validation (see below). Only required when data is a
+        raster class cube.
+    method (str): Either 'olofsson' or 'pixel' to compute accuracy (only
+        for raster class cubes).
+    **kwargs (dict): Specific parameters.
+
+Returns:
+    SITSData: The error_matrix, the class_areas, the unbiased estimated
+    areas, the standard error areas, confidence interval 95 and the accuracy
+    (user, producer, and overall), or `None` if the data is empty. The result
+    can be visualized directly on the screen.
+
+Notes:
+    The `validation` data needs to contain the following columns: "latitude",
+    "longitude", "start_date", "end_date", and "label". It can be either a path
+    to a CSV file, a `SITSTimeSeriesModel`, a `pandas.DataFrame`, or a
+    `geopandas.GeoDataFrame`.
+    When `validation` is a `geopandas.GeoDataFrame`, the columns "latitude"
+    and "longitude" are not required as the locations are extracted from the
+    geometry column. The `centroid` is calculated before extracting the
+    location values for any geometry type.
+
+Examples:
+    from pysits import *
+
+    # show accuracy for a set of samples
+    train_data = sits_sample(samples_modis_ndvi, frac=0.5)
+    test_data = sits_sample(samples_modis_ndvi, frac=0.5)
+    rfor_model = sits_train(train_data, sits_rfor())
+    points_class = sits_classify(
+        data=test_data, ml_model=rfor_model
+    )
+    acc = sits_accuracy(points_class)
+
+    # show accuracy for a data cube classification
+    # create a random forest model
+    rfor_model = sits_train(samples_modis_ndvi, sits_rfor())
+    # create a data cube from local files
+    data_dir = r_package_dir("extdata/raster/mod13q1", package="sits")
+    cube = sits_cube(
+        source="BDC",
+        collection="MOD13Q1-6.1",
+        data_dir=data_dir
+    )
+    # classify a data cube
+    import tempfile
+    probs_cube = sits_classify(
+        data=cube, ml_model=rfor_model, output_dir=tempfile.gettempdir()
+    )
+    # label the probability cube
+    label_cube = sits_label_classification(
+        probs_cube,
+        output_dir=tempfile.gettempdir()
+    )
+    # obtain the ground truth for accuracy assessment
+    ground_truth = r_package_dir("extdata/samples/samples_sinop_crop.csv", package="sits")
+    # make accuracy assessment
+    as_ = sits_accuracy(label_cube, validation=ground_truth)

pysits-2.0.0.dev1/pysits/docs/content/sits_accuracy_summary.md

@@ -0,0 +1,11 @@
+Print accuracy summary
+
+Adaptation of the caret::print.confusionMatrix method for the more common
+usage in Earth Observation.
+
+Args:
+    x (SITSConfusionMatrix): accuracy object to summarize.
+    digits (int): number of significant digits when printed.
+
+Returns:
+    SITSData: called for side effects.

pysits-2.0.0.dev1/pysits/docs/content/sits_add_base_cube.md

@@ -0,0 +1,55 @@
+Add base maps to a time series data cube
+
+This function add base maps to time series data cube. Base maps have
+information that is stable in time (e.g, DEM) which provide relevant
+information for modelling and classification.
+To add a base cube to an existing data cube, they should share the same
+sensor, resolution, bounding box, timeline, and have different bands.
+
+Args:
+    cube1 (SITSCubeModel): Data cube.
+    cube2 (SITSCubeModel): Data cube with base information.
+
+Returns:
+    SITSCubeModel: a merged data cube with the inclusion of base
+        information.
+
+Examples:
+    from pysits import *
+    import tempfile
+    import os
+
+    s2_cube = sits_cube(
+        source="MPC",
+        collection="SENTINEL-2-L2A",
+        tiles="18HYE",
+        bands=["B8A", "CLOUD"],
+        start_date="2022-01-01",
+        end_date="2022-03-31"
+    )
+    output_dir = os.path.join(tempfile.gettempdir(), "reg")
+    if not os.path.exists(output_dir):
+        os.makedirs(output_dir)
+    dem_cube = sits_cube(
+        source="MPC",
+        collection="COP-DEM-GLO-30",
+        tiles="18HYE",
+        bands="ELEVATION"
+    )
+    s2_reg = sits_regularize(
+        cube=s2_cube,
+        period="P1M",
+        res=240,
+        output_dir=output_dir,
+        multicores=2,
+        memsize=4
+    )
+    dem_reg = sits_regularize(
+        cube=dem_cube,
+        res=240,
+        tiles="18HYE",
+        output_dir=output_dir,
+        multicores=2,
+        memsize=4
+    )
+    s2_reg = sits_add_base_cube(s2_reg, dem_reg)

pysits-2.0.0.dev1/pysits/docs/content/sits_apply.md

@@ -0,0 +1,104 @@
+Apply a function on a set of time series
+
+Apply a named expression to a set of time series or a data cube to be
+evaluated and generate new bands (indices). In the case of data cubes,
+it creates a new band in `output_dir`.
+
+Args:
+    data (SITSTimeSeriesModel | SITSCubeModel): valid time series or data
+        cube.
+    window_size (int): an odd number representing the size of the sliding
+        window of kernel functions used in expressions (for a list of
+        supported kernel functions, please see details).
+    memsize (int): memory available for classification (in GB).
+    multicores (int): number of cores to be used for classification.
+    normalized (bool): does the expression produce a normalized band?
+    output_dir (str | pathlib.Path): directory where files will be saved.
+    progress (bool): show progress bar?
+    **kwargs (dict): named expressions to be evaluated (see details).
+
+Returns:
+    SITSFrame: time series or data cube with new bands, produced according
+        to the requested expression.
+
+Notes:
+    The main `sits` classification workflow has the following steps:
+    1. `sits_cube`: selects a ARD image collection from a cloud provider.
+    2. `sits_cube_copy`: copies an ARD image collection from a cloud provider
+       to a local directory for faster processing.
+    3. `sits_regularize`: create a regular data cube from an ARD image
+       collection.
+    4. `sits_apply`: create new indices by combining bands of a regular data
+       cube (optional).
+    5. `sits_get_data`: extract time series from a regular data cube based on
+       user-provided labelled samples.
+    6. `sits_train`: train a machine learning model based on image time series.
+    7. `sits_classify`: classify a data cube using a machine learning model and
+       obtain a probability cube.
+    8. `sits_smooth`: post-process a probability cube using a spatial smoother
+       to remove outliers and increase spatial consistency.
+    9. `sits_label_classification`: produce a classified map by selecting the
+       label with the highest probability from a smoothed cube.
+    `sits_apply()` allows any valid R expression to compute new bands. Use R
+    syntax to pass an expression to this function. Besides arithmetic
+    operators, you can use virtually any R function that can be applied to
+    elements of a matrix (functions that are unaware of matrix sizes, e.g.
+    `sqrt()`, `sin()`, `log()`).
+    Examples of valid expressions:
+    1. `NDVI = (B08 - B04) / (B08 + B04)` for Sentinel-2 images.
+    2. `EVI = 2.5 * (B05 \04) / (B05 + 6 * B04 \7.5 * B02 + 1)` for
+       Landsat-8/9 images.
+    3. `VV_VH_RATIO = VH/VV` for Sentinel-1 images. In this case, set the
+       `normalized` parameter to `False`.
+    4. `VV_DB = 10 * log10(VV)` to convert Sentinel-1 RTC images available in
+       Planetary Computer to decibels. Also, set the `normalized` parameter to
+       `False`.
+    `sits_apply()` also accepts a predefined set of kernel functions (see
+    below) that can be applied to pixels considering its neighborhood. The
+    function considers a neighborhood of a pixel as a set of pixels equidistant
+    to it (including itself). This neighborhood forms a square window (also
+    known as kernel) around the central pixel (Moore neighborhood). Users can
+    set the `window_size` parameter to adjust the size of the kernel window.
+    The image is conceptually mirrored at the edges so that neighborhood
+    including a pixel outside the image is equivalent to take the 'mirrored'
+    pixel inside the edge.
+    `sits_apply()` applies a function to the kernel and its result is assigned
+    to a corresponding central pixel on a new matrix. The kernel slides
+    throughout the input image and this process generates an entire new matrix,
+    which is returned as a new band to the cube. The kernel functions ignores
+    any `NA` values inside the kernel window. If all pixels in the window are
+    `NA` the result will be `NA`.
+    By default, the indexes generated by `sits_apply()` function are normalized
+    between -1 and 1, scaled by a factor of 0.0001. Normalized indexes are
+    saved as INT2S (Integer with sign). If the `normalized` parameter is
+    `False`, no scaling factor will be applied and the index will be saved as
+    FLT4S (signed float) and the values will vary between -3.4e+38 and
+    3.4e+38.
+
+Examples:
+    from pysits import *
+    import tempfile
+
+    # get a time series
+    # Apply a normalization function
+    point2 = sits_apply(
+        sits_select(point_mt_6bands, "NDVI"),
+        NDVI_norm="(NDVI - min(NDVI)) / (max(NDVI) - min(NDVI))"
+    )
+
+    # Example of generation texture band with variance
+    # Create a data cube from local files
+    data_dir = r_package_dir("extdata/raster/mod13q1", package="sits")
+    cube = sits_cube(
+        source="BDC",
+        collection="MOD13Q1-6.1",
+        data_dir=data_dir
+    )
+
+    # Generate a texture images with variance in NDVI images
+    cube_texture = sits_apply(
+        data=cube,
+        NDVITEXTURE="w_median(NDVI)",
+        window_size=5,
+        output_dir=tempfile.mkdtemp()
+    )

pysits-2.0.0.dev1/pysits/docs/content/sits_as_geopandas.md

@@ -0,0 +1,28 @@
+Return time series or a data cube as a `geopandas.GeoDataFrame`.
+
+Converts time series or a data cube to a `geopandas.GeoDataFrame`.
+
+Args:
+    data (SITSTimeSeriesModel | SITSCubeModel): time series or data
+            cube.
+    crs (str): input coordinate reference system.
+    as_crs (str): output coordinate reference system.
+    **kwargs (dict): additional parameters.
+
+Returns:
+    SITSFrame: point or polygon geometry.
+
+Examples:
+    from pysits import *
+
+    # convert sits tibble to a geopandas object (point)
+    geo_object = sits_as_geopandas(cerrado_2classes)
+
+    # convert sits cube to a geopandas object (polygon)
+    data_dir = r_package_dir("extdata/raster/mod13q1", package="sits")
+    cube = sits_cube(
+        source="BDC",
+        collection="MOD13Q1-6.1",
+        data_dir=data_dir
+    )
+    geo_object = sits_as_geopandas(cube)

pysits-2.0.0.dev1/pysits/docs/content/sits_bands.md

@@ -0,0 +1,30 @@
+Get the names of the bands
+
+Finds the names of the bands of a set of time series or of a data cube
+
+Args:
+    x (SITSTimeSeriesModel | SITSCubeModel): time series or data cube.
+    value (list[str]): new value for the bands.
+
+Returns:
+    list: the names of the bands.
+
+Examples:
+    from pysits import *
+
+    # Create a data cube from local files
+    data_dir = r_package_dir("extdata/raster/mod13q1", package="sits")
+    cube = sits_cube(
+        source="BDC",
+        collection="MOD13Q1-6.1",
+        data_dir=data_dir
+    )
+    # Get the bands from a data cube
+    bands = sits_bands(cube)
+    # Get the bands from a sits tibble
+    bands = sits_bands(samples_modis_ndvi)
+    # Get the bands from patterns
+    bands = sits_bands(sits_patterns(samples_modis_ndvi))
+    # Get the bands from ML model
+    rf_model = sits_train(samples_modis_ndvi, sits_rfor())
+    bands = sits_bands(rf_model)

pysits-2.0.0.dev1/pysits/docs/content/sits_barlow_twins.md

@@ -0,0 +1,65 @@
+Barlow Twins encoder for image time series
+
+Supervised pre-training using the Barlow Twins loss and a torch encoder. Two
+time series with the same class label are passed through a shared encoder +
+projector. The Barlow Twins loss makes the cross-correlation matrix of the two
+views' embeddings close to the identity: the diagonal -> 1 (invariance) and the
+off-diagonal -> 0 (redundancy reduction). No negatives are required.
+The function can be used in two ways:
+- If `samples` is provided, it trains immediately and returns an encoder-ready
+  model object (see Value).
+- If `samples = None`, it returns a training function with signature
+  `function(samples)` that can be passed to `sits_pre_train` or called later.
+
+Args:
+    samples (SITSTimeSeriesModel): A set of sample time series. If `None`
+        (default), returns a training function. If provided, triggers
+        immediate training. Base data samples (e.g., `sits_base`) are not
+        supported.
+    embedding_dim (int): Dimensionality of the encoder embedding (exported
+        features). Default: 64.
+    proj_dim (int): Dimensionality of the projector head used only during
+        pre-training. Default: 256.
+    bt_lambda (float): Weight of the redundancy-reduction (off-diagonal)
+        term in the Barlow Twins loss. Default: 5e-3.
+    num_pairs (int | None): Total number of pairs to form per epoch. When
+        `None` (default), one pair is formed for every sample in the
+        training split.
+    encoder_model (SITSMachineLearningMethod): Deep learning method that
+        takes time series as input and produces latent representations that
+        are used to compute the loss function (suggested options:
+        `sits_tempcnn()`, `sits_lighttae()`, `sits_resnet()`). Default:
+        `sits_tempcnn()`.
+    epochs (int): Maximum number of training epochs.
+    batch_size (int): Batch size for training. Larger values improve the
+        Barlow Twins cross-correlation estimate. Default: 128.
+    validation_split (float): Fraction of samples held out for validation
+        loss monitoring, in the range (0, 1).
+    optimizer: A `torch` optimizer constructor (default:
+        `torch::optim_adamw`).
+    opt_hparams (dict): Optimizer hyperparameters. Common entries: `lr`,
+        `eps`, `weight_decay`.
+    lr_decay_epochs (int): Step size (in epochs) for LR decay.
+    lr_decay_rate (float): Multiplicative LR decay factor.
+    patience (int): Early-stopping patience (epochs without improvement).
+    min_delta (float): Minimum improvement required to reset the patience
+        counter.
+    verbose (bool): Print training progress?
+    seed (int): Random seed for reproducibility.
+
+Returns:
+    R: If `samples = None`, a training function with signature
+    `function(samples)` that trains a Barlow Twins model and returns a
+    pretrained encoder. If `samples` is provided, the result of applying the
+    training function to `samples` directly.
+
+Examples:
+    from pysits import *
+
+    model = sits_pre_train(
+        samples_modis_ndvi,
+        sits_barlow_twins(
+            embedding_dim=32,
+            epochs=20
+        )
+    )

pysits-2.0.0.dev1/pysits/docs/content/sits_bbox.md

@@ -0,0 +1,33 @@
+Get the bounding box of the data
+
+Obtain a vector of limits (either on lat/long for time series or in
+projection coordinates in the case of cubes)
+
+Args:
+    data (SITSTimeSeriesModel | SITSCubeModel): samples or data cube.
+    crs (str): CRS of the time series.
+    as_crs (str): CRS to project the resulting bounding box.
+    **kwargs (dict): parameters for specific types.
+
+Returns:
+    SITSFrame: the bounding box.
+
+Notes:
+    Time series in `sits` are associated with lat/long values in WGS84,
+    while each data cube is associated to a cartographic projection. To
+    obtain the bounding box of a data cube in a different projection than
+    the original, use the `as_crs` parameter.
+
+Examples:
+    from pysits import *
+
+    # get the bbox of a set of samples
+    sits_bbox(samples_modis_ndvi)
+    # get the bbox of a cube in WGS84
+    data_dir = r_package_dir("extdata/raster/mod13q1", package="sits")
+    cube = sits_cube(
+        source="BDC",
+        collection="MOD13Q1-6.1",
+        data_dir=data_dir
+    )
+    sits_bbox(cube, as_crs="EPSG:4326")