update hf collection example

Author: M3nin0

inst/extdata/config_hf_example.yml

@@ -2,56 +2,94 @@
 #
 # To share a data cube on HuggingFace, store the images in a dataset
 # repository, naming them "<satellite>_<sensor>_<tile>_<band>_<date>.<ext>"
-# (the convention used for local data cubes), and place a file named
-# "sits.yml" at the root of the repository, describing the collection as
-# below. HuggingFace names are converted to sits names (upper case, with
-# characters other than letters, digits and "-" replaced by "-"); the same
-# conversion applies to the satellite and sensor names, which are part of the
-# names of files written by sits. The cube is then opened with:
+# (the convention used for local data cubes)
+#
+# Then, place a file "sits.yml" in the root of the repository, describing the
+# collection as much as possible. The content of this file can be the same one
+# as defined in any collection registered in sits. This means you are able to
+# define things like `bands`, `satellite`, `sensor`, `platforms` and so on.
+#
+# Once you have the dataset with files and the "sits.yml", you can load it using
+# the following standard:
 #
 #     sits_cube(
 #         source     = "HF:<user>",
 #         collection = "<repository>",
 #         tiles      = "<tile>"
 #     )
 #
-# Datasets can hold data cubes of images (as in this example), embeddings,
-# or classified maps:
-#   - embeddings: images named after the bands sits uses for embeddings
-#     ("EMB00", "EMB01", ...). sits defines how embeddings are stored, so
-#     these datasets describe no bands at all: how many of them the dataset
-#     holds is taken from the names of its images, and their resolution from
-#     the images. A dataset that describes its embedding bands must follow
-#     the sits definition (see embedding_values in the sits configuration);
-#   - classified maps: "class_cube: true" and a single band named "CLASS",
-#     whose "values" associate each pixel value to a label;
-#   - results produced by sits (e.g., probabilities, classified maps,
-#     uncertainty), keeping the file names written by sits
-#     ("<satellite>_<sensor>_<tile>_<start_date>_<end_date>_<band>_<version>"
-#     followed by the file extension).
-#     Their bands follow the sits definition of results, so each band only
-#     informs its resolution, and the labels are declared once:
-#
-#         labels:
-#             1: "Cerrado"
-#             2: "Forest"
-#         bands:
-#             PROBS : &band
-#                 resolution: 231.656
-#             CLASS : *band
-#
-#     Results are loaded one band at a time (e.g., bands = "probs").
+#
+# A dataset can hold four types of data cube. Each one is declared in a
+# different way:
+#
+# 1. Images (the type described in this example)
+#
+#    Declare every band of the images, as done below in "bands".
+#
+# 2. Embeddings
+#
+#    Use the band names sits uses for embeddings in the image names:
+#    "EMB00", "EMB01", and so on.
+#
+#    Here, bands are optional. If you store the embeddings the way sits
+#    does, declare nothing: sits reads the band names from the image
+#    names, and the resolution from the images.
+#
+#    You can still declare the bands, but then they must follow the sits
+#    definition (see "embedding_values" in the sits configuration).
+#
+# 3. Classified maps that were not produced by sits
+#
+#    Declare "class_cube: true" and a single band named "CLASS", whose
+#    "values" associate each pixel value to a label:
+#
+#        class_cube : true
+#
+#        bands:
+#            CLASS:
+#                bit_mask   : false
+#                band_name  : "CLASS"
+#                resolution : 231.656
+#                values     :
+#                    1 : "Cerrado"
+#                    2 : "Forest"
+#
+#    This is useful to host existing maps that were not produced by sits.
+#
+# 4. Results produced by sits (e.g., probabilities, classified maps,
+#    uncertainty)
+#
+#    Keep the names sits writes for its results, which carry the period
+#    of the classification and the version of the result:
+#
+#        <satellite>_<sensor>_<tile>_<start_date>_<end_date>_<band>_<version>
+#
+#    Bands are named as the results of sits ("PROBS", "BAYES", "CLASS",
+#    "VARIANCE", "ENTROPY", ...) and can't be mixed with other bands.
+#
+#    sits defines these bands, so each one only informs its resolution,
+#    and the labels are declared once for the whole collection:
+#
+#        labels:
+#            1: "Cerrado"
+#            2: "Forest"
+#
+#        bands:
+#            PROBS : &band
+#                resolution: 231.656
+#            CLASS : *band
+#
+#    Results are loaded one band at a time (e.g., bands = "probs").
 #
 # This example describes the dataset "felipemcarlos/sits_mod13q1_sinop", a
 # small crop (255 x 147 pixels) of the MOD13Q1 NDVI product over Sinop
 # (Mato Grosso, Brazil), distributed with sits as example data.
-
 satellite   : "TERRA"
 sensor      : "MODIS"
-# tiling system of the images. With a grid known to sits (e.g. "MGRS",
-# "BDC_MD_V2"), only the tiles that intersect a roi are read; otherwise use
-# a label (as sits does for other products, e.g. "STG", "WRS-2",
-# "NoTilingSystem")
+# You can define any name for the grid system. It will work in the same way as
+# in the other sources in sits. However, if the grid system defined is known by
+# sits, for instance "MGRS", this will allow users to filter the files loaded
+# using tile names of that grid (e.g., "20LMR" in the case of "MGRS")
 grid_system : "STG"
 dates       : "2013 to 2014"