stacterm

Name	stacterm JSON
Version	0.1.0 JSON
	download
home_page	https://github.com/stac-utils/stac-terminal
Summary	STAC Items in the terminal
upload_time	2021-04-16 22:55:21
maintainer
docs_url	None
author	Matthew Hanson
requires_python	>=3
license
keywords	an awesome python module
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            # stacterm

This library is for displaying information (tables, calendars, plots, histograms) about [STAC](https://stacspec.org/) Items in the terminal. It takes as input a STAC ItemCollection (a GeoJSON FeatureCollection of STAC Items), either by specifying a filename or by piping output from another program.

## Installation

Install from PyPi:

```
$ pip install stacterm
```

PySTAC and Pandas are required, along with two dependencies for rendering tables (`termtables`) and plots (`plotext`) in the terminal.

## Usage

stacterm main usage is as a CLI progam `stacterm`. Use help to see options available:

```
$ stacterm -h
usage: stacterm [-h] {table,cal,hist,plot} ...

Terminal STAC

positional arguments:
  {table,cal,hist,plot}
    table               Output a table
    cal                 Output a calendar
    hist                Output a histogram
    plot                Output a plot

optional arguments:
  -h, --help            show this help message and exit
```

The detailed usage examples below are shown using a saved file, however `stacterm` can also read in stdin allowing other programs to pipe output to it, such as [pystac-client](https://github.com/stac-utils/pystac-client).

```
$ export STAC_API_URL=https://earth-search.aws.element84.com/v0
$ stac-client search --intersects aoi.json --datetime 2020-07-01/2020-12-31 -c sentinel-s2-l2a-cogs landsat-8-l1-c1 | stacterm cal --label platform
```

![](images/cal.png)

All of the sub-commands in `stacterm` can take optional field names. A field name is:

- `id`: The ID of the Item
- `date`: The date portion of the Item's `datetime` field
- `collection`: The collection of the Item
- Any property


### Tables

Use `stacterm` to display tabularized data from a saved ItemCollection.

```
$ stacterm table items.json

| id                                       | date       |
|------------------------------------------|------------|
| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |
| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |
| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |
```

By default this is a markdown table (note the terminal will not render Markdown)

| id                                       | date       |
|------------------------------------------|------------|
| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |
| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |
| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |

The fields displayed can be changed via the `--fields` keyword, and sorted via the `--sort` keyword.

```
$ stacterm table items.json --fields date eo:cloud_cover collection --sort eo:cloud_cover

| date       | eo:cloud_cover | collection           |
|------------|----------------|----------------------|
| 2020-10-13 | 0.0            | sentinel-s2-l1c      |
| 2020-10-13 | 0.0            | sentinel-s2-l2a      |
| 2020-10-13 | 0.0            | sentinel-s2-l2a-cogs |
| 2020-10-13 | 0.0            | sentinel-s2-l1c      |
```

The style of the table can also be changed via the `--style` keyword, although it will no longer be usable in a Markdown renderer. See [termtables styles](https://github.com/nschloe/termtables/blob/master/termtables/styles.py) for list of styles.

```
$ stacterm table items.json --fields id date platform sentinel:grid_square --sort date --style thick

┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━┓
┃ id                                       ┃ date       ┃ platform    ┃ sentinel:grid_square ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXR_20201003_0_L2A                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XR                   ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXQ_20201003_0_L1C                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃
┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╋━━━━━━━━━━━━╋━━━━━━━━━━━━━╋━━━━━━━━━━━━━━━━━━━━━━┫
┃ S2B_12JXQ_20201003_0_L2A                 ┃ 2020-10-03 ┃ sentinel-2b ┃ XQ                   ┃
┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┻━━━━━━━━━━━━┻━━━━━━━━━━━━━┻━━━━━━━━━━━━━━━━━━━━━━┛
```

### Calendars

A UNIX-like calendar (see [`cal`](https://en.wikipedia.org/wiki/Cal_(Unix))) is available to show dates of individual items. By default `cal` will use the field `datetime` (the collection datetime) and group Items by their Collection. These can be overridden by the `--date_field` and `--label_field` keywords. Note that the specified `--date_field` needs to be a date field, such as `created` or `updated`.

```
$ stacterm cal items.json --date_field created --label_field gsd
```

![](images/cal2.png)

### Histograms

Histograms can be created for any numeric field.

```
$ stacterm hist items.json eo:cloud_cover
```

![](images/hist.png)

### Plots

Plots can be created with 1 or 2 numeric fields. If a single field it will be plotted against the scene number. The `--sort` keyword can control how to sort the data if plotting a single field.

```
$ stacterm plot items.json eo:cloud_cover --sort eo:cloud_cover
```

![](images/plot.png)


## Development

There are a lot more options in the [plotext library](https://github.com/piccolomo/plotext) that could be surfaced here. Additionally, if [support for datetimes](https://github.com/piccolomo/plotext/issues/7) in histograms and plots is added, `stacterm` could create temporal histograms, or plot quantities vs date.



            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/stac-utils/stac-terminal",
    "name": "stacterm",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3",
    "maintainer_email": "",
    "keywords": "An Awesome python module",
    "author": "Matthew Hanson",
    "author_email": "matt.a.hanson@gmail.com",
    "download_url": "https://files.pythonhosted.org/packages/b0/35/43ba166b3e0fff8dcaabef8104ae591ca6e6dd72635639dc451036c4f21c/stacterm-0.1.0.tar.gz",
    "platform": "",
    "description": "# stacterm\n\nThis library is for displaying information (tables, calendars, plots, histograms) about [STAC](https://stacspec.org/) Items in the terminal. It takes as input a STAC ItemCollection (a GeoJSON FeatureCollection of STAC Items), either by specifying a filename or by piping output from another program.\n\n## Installation\n\nInstall from PyPi:\n\n```\n$ pip install stacterm\n```\n\nPySTAC and Pandas are required, along with two dependencies for rendering tables (`termtables`) and plots (`plotext`) in the terminal.\n\n## Usage\n\nstacterm main usage is as a CLI progam `stacterm`. Use help to see options available:\n\n```\n$ stacterm -h\nusage: stacterm [-h] {table,cal,hist,plot} ...\n\nTerminal STAC\n\npositional arguments:\n  {table,cal,hist,plot}\n    table               Output a table\n    cal                 Output a calendar\n    hist                Output a histogram\n    plot                Output a plot\n\noptional arguments:\n  -h, --help            show this help message and exit\n```\n\nThe detailed usage examples below are shown using a saved file, however `stacterm` can also read in stdin allowing other programs to pipe output to it, such as [pystac-client](https://github.com/stac-utils/pystac-client).\n\n```\n$ export STAC_API_URL=https://earth-search.aws.element84.com/v0\n$ stac-client search --intersects aoi.json --datetime 2020-07-01/2020-12-31 -c sentinel-s2-l2a-cogs landsat-8-l1-c1 | stacterm cal --label platform\n```\n\n![](images/cal.png)\n\nAll of the sub-commands in `stacterm` can take optional field names. A field name is:\n\n- `id`: The ID of the Item\n- `date`: The date portion of the Item's `datetime` field\n- `collection`: The collection of the Item\n- Any property\n\n\n### Tables\n\nUse `stacterm` to display tabularized data from a saved ItemCollection.\n\n```\n$ stacterm table items.json\n\n| id                                       | date       |\n|------------------------------------------|------------|\n| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |\n| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |\n| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |\n```\n\nBy default this is a markdown table (note the terminal will not render Markdown)\n\n| id                                       | date       |\n|------------------------------------------|------------|\n| LC08_L1TP_026079_20201014_20201104_01_T1 | 2020-10-14 |\n| LC08_L1TP_026079_20201115_20201210_01_T1 | 2020-11-15 |\n| S2A_12JXQ_20201008_0_L1C                 | 2020-10-08 |\n\nThe fields displayed can be changed via the `--fields` keyword, and sorted via the `--sort` keyword.\n\n```\n$ stacterm table items.json --fields date eo:cloud_cover collection --sort eo:cloud_cover\n\n| date       | eo:cloud_cover | collection           |\n|------------|----------------|----------------------|\n| 2020-10-13 | 0.0            | sentinel-s2-l1c      |\n| 2020-10-13 | 0.0            | sentinel-s2-l2a      |\n| 2020-10-13 | 0.0            | sentinel-s2-l2a-cogs |\n| 2020-10-13 | 0.0            | sentinel-s2-l1c      |\n```\n\nThe style of the table can also be changed via the `--style` keyword, although it will no longer be usable in a Markdown renderer. See [termtables styles](https://github.com/nschloe/termtables/blob/master/termtables/styles.py) for list of styles.\n\n```\n$ stacterm table items.json --fields id date platform sentinel:grid_square --sort date --style thick\n\n\u250f\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2533\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2513\n\u2503 id                                       \u2503 date       \u2503 platform    \u2503 sentinel:grid_square \u2503\n\u2523\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u252b\n\u2503 S2B_12JXR_20201003_0_L2A                 \u2503 2020-10-03 \u2503 sentinel-2b \u2503 XR                   \u2503\n\u2523\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u252b\n\u2503 S2B_12JXQ_20201003_0_L1C                 \u2503 2020-10-03 \u2503 sentinel-2b \u2503 XQ                   \u2503\n\u2523\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u254b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u252b\n\u2503 S2B_12JXQ_20201003_0_L2A                 \u2503 2020-10-03 \u2503 sentinel-2b \u2503 XQ                   \u2503\n\u2517\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u253b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u253b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u253b\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u2501\u251b\n```\n\n### Calendars\n\nA UNIX-like calendar (see [`cal`](https://en.wikipedia.org/wiki/Cal_(Unix))) is available to show dates of individual items. By default `cal` will use the field `datetime` (the collection datetime) and group Items by their Collection. These can be overridden by the `--date_field` and `--label_field` keywords. Note that the specified `--date_field` needs to be a date field, such as `created` or `updated`.\n\n```\n$ stacterm cal items.json --date_field created --label_field gsd\n```\n\n![](images/cal2.png)\n\n### Histograms\n\nHistograms can be created for any numeric field.\n\n```\n$ stacterm hist items.json eo:cloud_cover\n```\n\n![](images/hist.png)\n\n### Plots\n\nPlots can be created with 1 or 2 numeric fields. If a single field it will be plotted against the scene number. The `--sort` keyword can control how to sort the data if plotting a single field.\n\n```\n$ stacterm plot items.json eo:cloud_cover --sort eo:cloud_cover\n```\n\n![](images/plot.png)\n\n\n## Development\n\nThere are a lot more options in the [plotext library](https://github.com/piccolomo/plotext) that could be surfaced here. Additionally, if [support for datetimes](https://github.com/piccolomo/plotext/issues/7) in histograms and plots is added, `stacterm` could create temporal histograms, or plot quantities vs date.\n\n\n",
    "bugtrack_url": null,
    "license": "",
    "summary": "STAC Items in the terminal",
    "version": "0.1.0",
    "project_urls": {
        "Homepage": "https://github.com/stac-utils/stac-terminal"
    },
    "split_keywords": [
        "an",
        "awesome",
        "python",
        "module"
    ],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "36a5e9bebfdd2836b376d279a10af988e98cda0b0ecd5886612e0f399f1b458f",
                "md5": "6126b174aa65977935f1a2894318eac9",
                "sha256": "70ad57cc346fda86290f095e61ea218af5e8c0db77bfdc858fd10d2a8a9c9e63"
            },
            "downloads": -1,
            "filename": "stacterm-0.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "6126b174aa65977935f1a2894318eac9",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3",
            "size": 6662,
            "upload_time": "2021-04-16T22:55:19",
            "upload_time_iso_8601": "2021-04-16T22:55:19.913514Z",
            "url": "https://files.pythonhosted.org/packages/36/a5/e9bebfdd2836b376d279a10af988e98cda0b0ecd5886612e0f399f1b458f/stacterm-0.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "b03543ba166b3e0fff8dcaabef8104ae591ca6e6dd72635639dc451036c4f21c",
                "md5": "ba19db619721337ed690faa3c873a035",
                "sha256": "4d73704fecc697e00472825dc0133fc43725e73eb45f263a640c53e2e8707e65"
            },
            "downloads": -1,
            "filename": "stacterm-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "ba19db619721337ed690faa3c873a035",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3",
            "size": 7618,
            "upload_time": "2021-04-16T22:55:21",
            "upload_time_iso_8601": "2021-04-16T22:55:21.265215Z",
            "url": "https://files.pythonhosted.org/packages/b0/35/43ba166b3e0fff8dcaabef8104ae591ca6e6dd72635639dc451036c4f21c/stacterm-0.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2021-04-16 22:55:21",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "stac-utils",
    "github_project": "stac-terminal",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [],
    "lcname": "stacterm"
}