pcoras 1.0.0__py3-none-any.whl

_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cli/__init__.py

@@ -0,0 +1,5 @@
+"""Command-line interface for PCoRaS."""
+
+from .cli import cli_parser, main
+
+__all__ = ["cli_parser", "main"]

cli/cli.py

@@ -0,0 +1,157 @@
+"""Command-line parser and entry point for PCoRaS."""
+
+import argparse
+import json
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as package_version
+from pathlib import Path
+
+from . import convert
+
+
+try:
+    VERSION = package_version("pcoras")
+except PackageNotFoundError:
+    VERSION = "unknown"
+
+
+def parse_json_object(value):
+    """Read a JSON object from an inline value or a JSON file."""
+    candidate = Path(value).expanduser()
+    try:
+        if candidate.is_file():
+            with candidate.open(encoding="utf-8") as stream:
+                parsed = json.load(stream)
+        else:
+            parsed = json.loads(value)
+    except (OSError, json.JSONDecodeError) as exc:
+        raise argparse.ArgumentTypeError(
+            f"Expected a JSON object or JSON file: {exc}"
+        ) from exc
+
+    if not isinstance(parsed, dict):
+        raise argparse.ArgumentTypeError("The value must be a JSON object.")
+    return parsed
+
+
+def parse_extra_attrs(value):
+    """Read extra attributes from JSON, a JSON file, or key=value pairs."""
+    try:
+        return parse_json_object(value)
+    except argparse.ArgumentTypeError:
+        parsed = {}
+        for item in value.split(","):
+            key, separator, raw_value = item.partition("=")
+            if not separator or not key.strip():
+                raise argparse.ArgumentTypeError(
+                    "--extra-attrs expects a JSON object, JSON file, "
+                    "or comma-separated key=value pairs."
+                )
+            try:
+                parsed[key.strip()] = json.loads(raw_value.strip())
+            except json.JSONDecodeError:
+                parsed[key.strip()] = raw_value.strip()
+        return parsed
+
+
+def csv_values(value):
+    """Split a comma-separated CLI value."""
+    return [item.strip() for item in value.split(",")]
+
+
+def add_convert_subparser(subparsers):
+    """Add the ``convert``/``co`` command."""
+    parser = subparsers.add_parser(
+        "convert",
+        aliases=["co"],
+        help="Convert multidimensional datasets to a Zarr data cube.",
+    )
+    parser.set_defaults(validate=convert.validate_args, run=convert.run)
+
+    required = parser.add_argument_group("required arguments")
+    required.add_argument("--path", required=True, help="List or String, Path to the input dataset (file or directory).")
+    required.add_argument("--output-folder", required=True, help="Path to the output folder.")
+    required.add_argument("--output-name", required=True, help="String, Name of the output dataset.")
+    required.add_argument("--xdim", required=True, help="String, Name of the x dimension.")
+    required.add_argument("--ydim", required=True, help="String, Name of the y dimension.")
+    required.add_argument("--tdim", required=True, help="String, Name of the time dimension.")
+
+    stac = parser.add_argument_group("STAC")
+    stac.add_argument("--collection-url", help="URL of the STAC collection to publish to.")
+    stac.add_argument("--collection-id", help="ID of the STAC collection to publish to.")
+    stac.add_argument("--publish-stac", default=False, action="store_true", help="Boolean, Whether to publish the output dataset to a STAC collection.")
+    stac.add_argument("--stac-version", default="1.0.0", help="String, Version of the STAC specification to use for publishing (default is 1.0.0).")
+
+    storage = parser.add_argument_group("S3 storage")
+    storage.add_argument("--bucket-name", help="String, Name of the S3 bucket to upload data to.")
+    storage.add_argument("--bucket-file-prefix", help="String, Prefix for the files in the S3 bucket.") 
+    storage.add_argument("--aws-region", help="String, AWS region for the S3 bucket.")
+    storage.add_argument("--aws-access-key", help="String, AWS access key for the S3 bucket.")
+    storage.add_argument("--aws-secret-key", help="String, AWS secret key for the S3 bucket.")
+    storage.add_argument("--s3-endpoint-url", help="String, Endpoint URL for the S3 service.")
+    storage.add_argument("--upload-s3-data", default=False, action="store_true", help="Boolean, Whether to upload the data to S3.")
+
+    dataset = parser.add_argument_group("dataset")
+    dataset.add_argument("--file-ext", default=".nc", help="String, File extension for the input dataset.")
+    dataset.add_argument("--sel-ds", default="unmatched", help="String, Dataset selection criteria.")
+    dataset.add_argument("--filter-keyword", help="List or String, Keywords to filter the dataset by their filename.")
+    dataset.add_argument("--filter-on", default=False, action="store_true", help="Boolean, Toggle for --filter-keyword (True/False to exclude/include files by keyword).")
+    dataset.add_argument("--variables", nargs="+", help="List, Variables to include in the output.")
+    dataset.add_argument("--odim", nargs="+", type=int, help="list of int, List of dimension indices to be used for the output dataset (default is None, meaning all dimensions will be used)")
+    dataset.add_argument("--olabel", help="String,  Name of the label dimension to be used for the output dataset (default is None, meaning no label dimension will be added)")
+    dataset.add_argument("--bands", nargs="+", help="list of strings, Bands to include.")
+    dataset.add_argument("--band-specification", help="String, specification for how to create the band dimension (default is None, meaning no band dimension will be created).")
+    dataset.add_argument("--bands-dimensions", type=parse_json_object, help="Dictionary, specifying how to create the band dimension based on the input datasets (default is None, meaning no band dimension will be created).")
+    dataset.add_argument("--pattern", help="String, Pattern for matching files with similar names.")
+
+    temporal = parser.add_argument_group("temporal transformation")
+    temporal.add_argument("--time-interval", type=csv_values, help="list of Strings, List specifying the time interval for selecting data from the input datasets (default is None, meaning no time filtering will be applied")
+    temporal.add_argument("--new-time-dimension", help="String, Name of a new time dimension to be added to the output dataset (default is None, meaning no new dimension will be added)")
+    temporal.add_argument("--new-time-labels", type=parse_json_object, help="Dictionary, Labels for the new time dimension to be added to the output dataset (default is None, meaning no new dimension will be added)")
+
+    metadata = parser.add_argument_group("metadata and output")
+    metadata.add_argument("--concat-attrs", nargs="+", help="list of strings, List of attribute names to concatenate from the input datasets to the output dataset (default is None, meaning no attributes will be concatenated).")
+    metadata.add_argument("--extra-attrs", type=parse_extra_attrs, help="Dictionary of extra attributes to be added to the output dataset (default is None, meaning no extra attributes will be added).")
+    metadata.add_argument("--crs", type=int, help="Integer, EPSG code for the coordinate reference system to be used for the output dataset (default is None, meaning no CRS will be assigned to the output dataset).")
+    metadata.add_argument("--chunking", type=parse_json_object, default={}, help="Dictionary, specifying the chunk sizes for the output dataset (default is an empty dictionary, meaning no chunking will be applied).")
+
+    parser.add_argument("--dry-run", action="store_true")
+    return parser
+
+
+def cli_parser():
+    """Create the top-level PCoRaS parser."""
+    parser = argparse.ArgumentParser(
+        prog="pcoras",
+        description="Build Zarr data cubes from raster datasets.",
+        formatter_class=argparse.ArgumentDefaultsHelpFormatter,
+    )
+    parser.add_argument("-d", "--debug", action="store_true")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"%(prog)s {VERSION}",
+    )
+    subparsers = parser.add_subparsers(dest="action_name", title="actions")
+    add_convert_subparser(subparsers)
+    return parser
+
+
+def main():
+    """Run the PCoRaS CLI."""
+    parser = cli_parser()
+    args = parser.parse_args()
+
+    if args.action_name is None:
+        parser.print_help()
+        return 0
+
+    try:
+        args.validate(args)
+        return args.run(args)
+    except (OSError, RuntimeError, TypeError, ValueError) as exc:
+        parser.error(str(exc))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cli/convert.py

@@ -0,0 +1,162 @@
+"""Validation and execution for the PCoRaS ``convert`` command."""
+
+import importlib
+import json
+import logging
+from pathlib import Path
+
+
+LOGGER = logging.getLogger(__name__)
+
+
+def validate_args(args) -> bool:
+    """Validate CLI arguments before constructing PCoRaS."""
+    input_path = Path(args.path).expanduser()
+    if not input_path.exists():
+        raise ValueError(f"Input path does not exist: '{input_path}'")
+    if not input_path.is_file() and not input_path.is_dir():
+        raise ValueError(
+            f"Input path must be a file or directory: '{input_path}'"
+        )
+
+    output_folder = Path(args.output_folder).expanduser()
+    if output_folder.exists() and not output_folder.is_dir():
+        raise ValueError(
+            f"Output path is not a directory: '{output_folder}'"
+        )
+
+    if (args.odim is None) != (args.olabel is None):
+        raise ValueError("--odim and --olabel must be provided together.")
+
+    temporal_values = (
+        args.time_interval,
+        args.new_time_dimension,
+        args.new_time_labels,
+    )
+    if any(value is not None for value in temporal_values) and not all(
+        value is not None for value in temporal_values
+    ):
+        raise ValueError(
+            "--time-interval, --new-time-dimension and --new-time-labels "
+            "must be provided together."
+        )
+    if args.time_interval is not None and len(args.time_interval) != 2:
+        raise ValueError(
+            "--time-interval requires exactly two comma-separated values."
+        )
+
+    if args.publish_stac:
+        missing = [
+            option
+            for option, value in {
+                "--collection-url": args.collection_url,
+                "--collection-id": args.collection_id,
+            }.items()
+            if not value
+        ]
+        if missing:
+            raise ValueError(
+                "--publish-stac requires: " + ", ".join(missing)
+            )
+
+    if args.upload_s3_data:
+        missing = [
+            option
+            for option, value in {
+                "--bucket-name": args.bucket_name,
+                "--aws-access-key": args.aws_access_key,
+                "--aws-secret-key": args.aws_secret_key,
+                "--s3-endpoint-url": args.s3_endpoint_url,
+            }.items()
+            if not value
+        ]
+        if missing:
+            raise ValueError(
+                "--upload-s3-data requires: " + ", ".join(missing)
+            )
+
+    return True
+
+
+def build_configuration(args):
+    """Map CLI arguments one-to-one to the PCoRaS constructor."""
+    return {
+        "path": args.path,
+        "output_folder": args.output_folder,
+        "output_name": args.output_name,
+        "xdim": args.xdim,
+        "ydim": args.ydim,
+        "tdim": args.tdim,
+        "collection_url": args.collection_url,
+        "collection_id": args.collection_id,
+        "bucket_name": args.bucket_name,
+        "bucket_file_prefix": args.bucket_file_prefix,
+        "aws_region": args.aws_region,
+        "aws_access_key": args.aws_access_key,
+        "aws_secret_key": args.aws_secret_key,
+        "s3_endpoint_url": args.s3_endpoint_url,
+        "file_ext": args.file_ext,
+        "upload_s3_data": args.upload_s3_data,
+        "publish_stac": args.publish_stac,
+        "stac_version": args.stac_version,
+        "sel_ds": args.sel_ds,
+        "filter_keyword": args.filter_keyword,
+        "filter_on": args.filter_on,
+        "variables": args.variables,
+        "odim": args.odim,
+        "olabel": args.olabel,
+        "bands": args.bands,
+        "band_specification": args.band_specification,
+        "bands_dimensions": args.bands_dimensions,
+        "pattern": args.pattern,
+        "time_interval": args.time_interval,
+        "new_time_dimension": args.new_time_dimension,
+        "new_time_labels": args.new_time_labels,
+        "concat_attrs": args.concat_attrs,
+        "extra_attrs": args.extra_attrs,
+        "crs": args.crs,
+        "chunking": args.chunking,
+    }
+
+
+def _pcoras_class():
+    """Support the project's current ``Pcoras`` or ``pcoras`` class name."""
+    module = importlib.import_module("pcoras")
+    implementation = getattr(module, "Pcoras", None)
+    if implementation is None:
+        implementation = getattr(module, "pcoras", None)
+    if implementation is None:
+        raise RuntimeError("Module 'pcoras' does not expose Pcoras or pcoras.")
+    return implementation
+
+
+def run(args) -> int:
+    """Construct PCoRaS with the parsed arguments and execute its pipeline."""
+    configuration = build_configuration(args)
+
+    if args.dry_run:
+        protected = {
+            "aws_access_key",
+            "aws_secret_key",
+        }
+        printable = {
+            key: ("***" if key in protected and value else value)
+            for key, value in configuration.items()
+        }
+        print(json.dumps(printable, indent=2, default=str))
+        return 0
+
+    Path(args.output_folder).expanduser().mkdir(parents=True, exist_ok=True)
+    process = _pcoras_class()(**configuration)
+
+    if hasattr(process, "pcoras"):
+        process.pcoras()
+    elif hasattr(process, "run"):
+        process.run()
+    else:
+        raise RuntimeError(
+            "The PCoRaS class exposes neither pcoras() nor run()."
+        )
+
+    LOGGER.info("PCoRaS conversion completed")
+    return 0

pcoras-1.0.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: pcoras
+Version: 1.0.0
+Summary: Package for Cloud-Optimized Raster and Spatio-temporal data
+Author-email: Miguel Martinez <mmartinezguerrero@eurac.edu>, Piero Campalani <pcampalani@eurac.edu>, Alexander Jacob <Alexander.Jacob@eurac.edu>, Michele Claus <michele.claus@eurac.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://gitlab.inf.unibz.it/earth_observation_public/pcoras
+Project-URL: Issues, https://gitlab.inf.unibz.it/earth_observation_public/pcoras/-/issues
+Keywords: STAC,Metadata,Zarr,NetCDF
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: raster2stac>=2026.2.1
+Requires-Dist: requests
+Requires-Dist: importlib_metadata
+Provides-Extra: dev
+Requires-Dist: isort; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+![Logo](/docs/Diagrams/logo.png)
+
+![PyPI - Status](https://img.shields.io/pypi/status/pcoras)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pcoras)
+![PyPI](https://img.shields.io/pypi/v/pcoras)
+![PyPI - License](https://img.shields.io/pypi/l/pcoras)
+
+# PCoRaS
+
+Python Package for Cloud Optimzed Raster and Spatio-temporal Data, following the STAC guidelines this repository
+is based Cloud optimized type of files and Raster2stac functions to create an STAC collections compatible with
+OpenEO backend, getting an output up to a 5D hypercube dataset for different spatio-temporal data, following a
+collection of local OpenEO processes to test the compability of the item. 
+
+## Setup
+
+```bash
+pip install pcoras
+```
+
+Note: Conda support is in development
+ 
+## Getting started
+
+### Command-line interface
+
+Convert a NetCDF file into a local Zarr data cube:
+
+```sh 
+    python -m pcoras convert \
+    --path ./data/precipitation.nc \
+    --output-folder ./output \
+    --output-name precipitation \
+    --xdim x \
+    --ydim y \
+    --tdim time
+```
+ 
+Replace the input path and dimension names with those in your dataset. For example, a dataset with longitude and latitude dimensions may require `--xdim lon --ydim lat`.
+
+These six arguments are required by the command-line parser. NetCDF (`.nc`) is the default input extension. S3 upload and STAC publication are disabled by default; enable them with `--upload-s3-data` and `--publish-stac`, respectively, and supply the corresponding storage or collection settings.
+
+The `--path` option accepts one command-line value: a file or directory path. The `co` command is an alias for `convert`.
+
+Display the available commands and conversion options:
+
+```sh
+python -m pcoras --help
+python -m pcoras convert --help
+```
+
+Selected conversion options:
+
+| Option | Purpose |
+| --- | --- |
+| `--variables pr tas` | Select variables by name. Replace `pr` and `tas` with names from your dataset. |
+| `--file-ext .nc` | Set the input file extension; defaults to `.nc`. |
+| `--crs 32632` | Supply a CRS as an integer EPSG code appropriate for your dataset. |
+| `--chunking '{"time": 31}'` | Supply chunk sizes as a JSON object, using your dataset's dimension names. |
+
+Options defined as flags, such as `--upload-s3-data`, are enabled by their presence; do not append `True` or `False`.
+
+### Python API
+
+Check that the package can be imported and inspect its Python API:
+
+```python
+from pcoras import pcoras
+
+help(pcoras)
+```
+
+Conversion examples are available in the repository's test folder. They illustrate how to configure input datasets, output data cubes, metadata, and storage options.
+
+## Metadata
+
+PCoRaS preserves attributes shared by the source datasets. You can supply additional attributes through `extra_attr`, for example:
+
+```python
+extra_attr = {
+    "keywords": ["climate", "precipitation", "Zarr"],
+    "License": "MIT",
+    "Producer": "Your organisation",
+}
+```
+
+These are example dataset attributes. Set them to match the source data and its actual licensing and provenance.
+
+STAC metadata describes the collection or item, including its title, description, providers, and licensing. The constructor accepts additional dataset attributes through `extra_attr`; The user must ensure that attibutes contains `title`, `description`, `providers`, `License`, `Producer` or `links` parameters. Inspect the generated STAC metadata to check that it describes your dataset correctly.
+
+The dataset license may differ from the software license.
+
+## S3-compatible storage
+
+For workflows that upload outputs to S3-compatible storage, configure the upload options and credentials. The following snippet defines example configuration values; it does not start an upload:
+
+```python
+upload_s3_data = True
+bucket_name = "pcoras-data"
+bucket_file_prefix = "precipitation/v01"
+aws_region = None
+aws_access_key = ["AWS_ACCESS_KEY_ID"]
+aws_secret_key = ["AWS_SECRET_ACCESS_KEY"]
+s3_endpoint_url = "https://your-s3-endpoint.example.org"
+```
+
+Set the environment variables before running the workflow, and replace the bucket, prefix, endpoint, and region with values for your storage service.
+
+For the CLI, enable `--upload-s3-data` and pass the storage settings through `--bucket-name`, `--bucket-file-prefix`, `--aws-region`, `--aws-access-key`, `--aws-secret-key`, and `--s3-endpoint-url`, as required by your storage service. The Python snippet above reads environment variables explicitly; it does not imply that the CLI reads them automatically.
+
+Set `stac_version` to the STAC version supported by your workflow and target catalog.
+
+### Mindmap and Flowchart
+
+Below, is a the current mindmap and flowchart follow by this repo
+
+[Mindmap](/docs/Diagrams/mindmap.png)
+
+[Flowchart](/docs/Diagrams/PCoRaS_flowchart.png)
+
+### Not supported
+
+Currently authentification to upload the STAC collection is not supported yet. However the code for request and publication is provided.
+
+## License
+
+[MIT](https://choosealicense.com/licenses/mit/).
+
+## Credits
+
+This project was done thanks to the collaboration of the Institute of Earth Observation and the Center for Climate change and Transformation at Eurac Research
+
+Thanks To Irma Ruiz Velasco for the great work on graphics and pcoras logo!
+
+![Eurac](/docs/Diagrams/eurac_research_logo_footer_2021.png)

pcoras-1.0.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+_version.py,sha256=Pru0BlFBASFCFo7McHdohtKkUtgMPDwbGfyUZlE2_Vw,21
+pcoras.py,sha256=oCc61y2YjImxKkfNSl_Ji75O0kEMLoeOeC4-XmmAj0M,23168
+cli/__init__.py,sha256=U7nw7Q9NaRKvlvMeE9ifzfHoSc8k09t7Iu9jcANh4jY,110
+cli/cli.py,sha256=Ni2gqG9agsVdOlfekH4lWj89FtIiHvwkWCyHC8_bhTA,8436
+cli/convert.py,sha256=xa9grT8zGRO9H7Ez-wX3tKFVPbqSQtiFttfEFgRKTM4,5314
+pcoras-1.0.0.dist-info/licenses/LICENSE,sha256=bVCdJ5uYMJnvA8DYKRuA5TAocC1VeWaOxwLlSvCHQ40,1106
+sub/__init__.py,sha256=jl1330S4ENrN_Nf7wydRTAmJ8r0mxasfOrXMe375_tw,308
+sub/data_process.py,sha256=rZV6vHYAtKQgaJlrOs5bKYI3nxrHDG4-6JU-GeizK2Q,17901
+sub/preprocess.py,sha256=3I8AfhCsekQdBLpffgrHqnPQ2Gj5q7c14PdjehDjeE4,17195
+sub/utils.py,sha256=lvjKNlU2qltCY1al2lkSf1nefC48X_w8x-kx5ckF5yY,26474
+pcoras-1.0.0.dist-info/METADATA,sha256=I6xRZ4xaQlO7OaQz3WUIT2aNMrL7Q1qgLhTqjMDtw3U,6527
+pcoras-1.0.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pcoras-1.0.0.dist-info/entry_points.txt,sha256=Di1qBF8s09k5EQH8emhgehjn-X-kp1Hl00jDS2HinuE,40
+pcoras-1.0.0.dist-info/top_level.txt,sha256=xGV-VbC6Kc-ec4nqE-dI9250Ki0jamHt0hdue8Kddxg,24
+pcoras-1.0.0.dist-info/RECORD,,

pcoras-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pcoras-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pcoras = cli.cli:main

pcoras-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2024 Eurac Research - Institute for Earth Observation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

pcoras-1.0.0.dist-info/top_level.txt

@@ -0,0 +1,4 @@
+_version
+cli
+pcoras
+sub