From 55b28afe4caf3d6d21734db79d63d536a0a2b6dd Mon Sep 17 00:00:00 2001 From: Taylor Date: Tue, 31 Oct 2023 16:11:58 +0100 Subject: [PATCH] DOC-724: Convert JobTask to markdown (#484) --- docs/reference/asset-reference.md | 4 +- docs/reference/catalog-reference.md | 6 +- docs/reference/job-reference.md | 10 +- docs/reference/jobtask-reference.md | 214 +++++++++++++++++++++++++++- docs/structure.md | 25 +++- 5 files changed, 241 insertions(+), 18 deletions(-) diff --git a/docs/reference/asset-reference.md b/docs/reference/asset-reference.md index a5b0ea769..b5e53af72 100644 --- a/docs/reference/asset-reference.md +++ b/docs/reference/asset-reference.md @@ -78,7 +78,7 @@ The returned format is `list[str]`. | Argument | Overview | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. | | `unpacking` | **bool**
Determines how to download the asset:
The default value is `True`. |
Example
@@ -134,7 +134,7 @@ The returned format is `pathlib.Path`. | Argument | Description | | ------------------ | ----------------------------------------------------------------------------------------------------- | | `stac_asset` | **pystac.Asset / required**
The STAC asset to be downloaded. | -| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. |
Example
diff --git a/docs/reference/catalog-reference.md b/docs/reference/catalog-reference.md index e11b64fff..470bb364b 100644 --- a/docs/reference/catalog-reference.md +++ b/docs/reference/catalog-reference.md @@ -109,7 +109,7 @@ The returned format is `list[str]`. | ------------------ | ----------------------------------------------------------------------------------------------------- | | `image_ids` | **list[str] / required**
The scene IDs. | | `collection` | **str / required**
The geospatial collection name. | -| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. |
Example
@@ -172,7 +172,7 @@ The returned format is `int`. | Argument | Overview | | ------------------ | ----------------------------------------------------------------------------- | -| `order_parameters` | **Union[dict, none] / required**
Parameters with which to place an order. | +| `order_parameters` | **Union[dict, None] / required**
Parameters with which to place an order. |
Example
@@ -323,7 +323,7 @@ plot_quicklooks( | Argument | Overview | | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(8, 8)`. | -| `filepaths` | **Union[list[Union[str, Path]], dict, none]**
The file paths. By default, the last downloaded quicklooks will be used. | +| `filepaths` | **Union[list[Union[str, Path]], dict, None]**
The file paths. By default, the last downloaded quicklooks will be used. | | `titles` | **list[str]**
The titles for the subplots. |
Example
diff --git a/docs/reference/job-reference.md b/docs/reference/job-reference.md index 91cc8d24e..d74e02b74 100644 --- a/docs/reference/job-reference.md +++ b/docs/reference/job-reference.md @@ -110,7 +110,7 @@ The returned format is `list[str]`. | Argument | Overview | | ------------------ | ----------------------------------------------------------------------------------------------------- | -| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. |
Example
@@ -157,7 +157,7 @@ The returned format is `list[str]`. | Argument | Overview | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `output_directory` | **Union[str, Path, none]**
The file output directory. The default value is the current directory. | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. | | `unpacking` | **bool**
Determines how to download the job results:
The default value is `True`. |
Example
@@ -221,7 +221,7 @@ job.cancel_job() ## Job tasks -Job tasks are unique configurations of workflow tasks in a job. +Job tasks are unique configurations of workflow tasks in a job. You can access a specific job task's results with the [JobTask](../../reference/jobtask-reference) class. ### get_jobtasks() @@ -357,7 +357,7 @@ plot_results( | `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(14, 8)`. | | `bands` | **list[int]**
A list of image bands to plot and their order. | | `titles` | **list[str]**
The titles for the subplots. | -| `filepaths` | **Union[list[Union[str, Path]], dict, none]**
The file paths. By default, the last downloaded results will be used. | +| `filepaths` | **Union[list[Union[str, Path]], dict, None]**
The file paths. By default, the last downloaded results will be used. | | `plot_file_format` | **list[str]**
Accepted file formats. The default value is `[".tif"]`. | | `**kwargs` | Any additional arguments of [rasterio.plot.show](https://rasterio.readthedocs.io/en/latest/api/rasterio.plot.html#rasterio.plot.show). | @@ -368,7 +368,7 @@ job.plot_results( figsize=(10, 10), bands=[1], titles=["SPOT imagery over Berlin"], - filpaths="/Users/max.mustermann/Desktop/IMG_SPOT6_PMS.TIF", + filepaths="/Users/max.mustermann/Desktop/IMG_SPOT6_PMS.TIF", plot_file_format=[".tif"], ) ``` diff --git a/docs/reference/jobtask-reference.md b/docs/reference/jobtask-reference.md index 62517fba8..17ef38c73 100644 --- a/docs/reference/jobtask-reference.md +++ b/docs/reference/jobtask-reference.md @@ -1,6 +1,212 @@ # JobTask -::: up42.jobtask.JobTask - selection: - inherited_members: True - members: {{ funcs_jobtask }} +The JobTask class enables access to [results of a specific job task](analytics.md). Job tasks are unique configurations of workflow tasks in a job. + +```python +jobtask = up42.initialize_jobtask( + jobtask_id="3f772637-09aa-4164-bded-692fcd746d20", + job_id="de5806aa-5ef1-4dc9-ab1d-06d7ec1a5021", +) +``` + +## Job tasks + +### info + +The `info` attribute returns metadata of a specific job task. + +The returned format is `dict`. + +
Example
+ +```python +jobtask.info +``` + +### download_quicklooks() + +The `download_quicklooks()` function allows you to download low-resolution preview images. Not all job tasks have quicklooks. + +```python +download_quicklooks(output_directory) +``` + +The returned format is `list[str]`. If an empty list `[]` is returned, no quicklooks are available. + +
Arguments
+ +| Argument | Overview | +| ------------------ | ----------------------------------------------------------------------------------------------------- | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. | + +
Example
+ +```python +jobtask.download_quicklooks(output_directory="/Users/max.mustermann/Desktop/") +``` + +### get_results_json() + +The `get_results_json()` function allows you to get the `data.json` from a specific job task. + +```python +get_results_json(as_dataframe) +``` + +The returned format is `Union[dict, GeoDataFrame]`. + +
Arguments
+ +| Argument | Overview | +| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `as_dataframe` | **bool**
Determines how `data.json` is returned:
The default value is `False`. | + +
Example
+ +```python +jobtask.get_results_json(as_dataframe=True) +``` + +### download_results() + +The `download_results()` function allows you to download a specific job task's results and returns a list of download paths. + +```python +download_results(output_directory) +``` + +The returned format is `list[str]`. + +
Arguments
+ +| Argument | Overview | +| ------------------ | ----------------------------------------------------------------------------------------------------- | +| `output_directory` | **Union[str, Path, None]**
The file output directory. The default value is the current directory. | + +
Example
+ +```python +jobtask.download_results(output_directory="/Users/max.mustermann/Desktop/") +``` + +## Visualization + +To use the visualization functions, [install](installation.md) the SDK's advanced installation with plotting functionalities. + +### map_results() + +The `map_results()` function allows you to visualize a specific job task's results on a Folium map. Use together with [`download_results()`](#download_results). + +```python +map_results( + bands, + aoi, + show_images, + show_features, + name_column, + save_html, +) +``` + +The returned format is `folium.Map`. + +
Arguments
+ +| Argument | Overview | +| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `bands` | **list[int]**
A list of image bands to show on the map and their order. | +| `aoi` | **GeoDataFrame**
An additional geometry to visualize on the map. | +| `show_images` | **bool**
Determines whether to visualize the job task results: The default value is `True`. | +| `show_features` | **bool**
Determines whether to visualize the geometry of the job task results:
The default value is `True`. | +| `name_column` | **str**
The name of the feature property that provides the feature name. The default value is `uid`. | +| `save_html` | **path**
Use to specify a path to save the map as an HTML file. | + +
Example
+ +```python +jobtask.map_results( + bands=[1], + aoi="/Users/max.mustermann/Desktop/sentinel-job.geojson", + show_images=True, + show_features=False, + name_column="uid", + save_html="/Users/max.mustermann/Desktop/", +) +``` + +### plot_results() + +The `plot_results()` function allows you to visualize downloaded job task's results. Use together with [`download_results()`](#download_results). + +```python +plot_results( + figsize, + bands, + titles, + filepaths, + plot_file_format, + **kwargs, +) +``` + +
Arguments
+ +| Argument | Overview | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(14, 8)`. | +| `bands` | **list[int]**
A list of image bands to plot and their order. | +| `titles` | **list[str]**
The titles for the subplots. | +| `filepaths` | **Union[list[Union[str, Path]], dict, None]**
The file paths. By default, the last downloaded results will be used. | +| `plot_file_format` | **list[str]**
Accepted file formats. The default value is `[".tif"]`. | +| `**kwargs` | Any additional arguments of [rasterio.plot.show](https://rasterio.readthedocs.io/en/latest/api/rasterio.plot.html#rasterio.plot.show). | + +
Example
+ +```python +jobtask.plot_results( + figsize=(10, 10), + bands=[1], + titles=["SPOT imagery over Berlin"], + filepaths="/Users/max.mustermann/Desktop/IMG_SPOT6_PMS.TIF", + plot_file_format=[".tif"], +) +``` + +### plot_quicklooks() + +The `plot_quicklooks()` function allows you to visualize downloaded quicklooks. Use together with [`download_quicklooks()`](#download_quicklooks). + +```python +plot_quicklooks( + figsize, + filepaths, + titles +) +``` + +
Arguments
+ +| Argument | Overview | +| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | +| `figsize` | **tuple[int, int]**
The size of the visualization, in inches. The first number is height, the second one is width. The default value is `(8, 8)`. | +| `filepaths` | **Union[list[Union[str, Path]], dict, None]**
The file paths. By default, the last downloaded quicklooks will be used. | +| `titles` | **list[str]**
The titles for the subplots. | + +
Example
+ +```python +# Download quicklooks + +jobtask.download_quicklooks(output_directory="/Users/max.mustermann/Desktop/") + +# Map quicklooks + +jobtask.plot_quicklooks( + figsize=(10, 10), + filepaths=[ + "/Users/max.mustermann/Desktop/quicklook_d0a7e38a-0087-48c9-b3f7-8b422388e101.jpg", + "/Users/max.mustermann/Desktop/quicklook_b7f2c82f-641d-4119-baff-7001a5ceb4f6.jpg", + ], + titles=["Scene 1", "Scene 2"], +) +``` diff --git a/docs/structure.md b/docs/structure.md index e5b3baf87..63de77cae 100644 --- a/docs/structure.md +++ b/docs/structure.md @@ -204,10 +204,27 @@ === "JobTask" - {{ docstring_jobtask }} -
- Available functions, see also [**JobTask reference**](jobtask-reference.md): - {{ format_funcs(funcs_jobtask) }} + The JobTask class enables access to [results of a specific job task](analytics.md). + + Job tasks are unique configurations of workflow tasks in a job. + + ```python + jobtask = up42.initialize_jobtask( + jobtask_id="3f772637-09aa-4164-bded-692fcd746d20", + job_id="de5806aa-5ef1-4dc9-ab1d-06d7ec1a5021", + ) + ``` + + See available attributes and functions on the [JobTask](jobtask-reference.md) reference page: + === "Webhooks"