Note

Array is an experimental API. It may be changed in the future, will not necessarily be backwards compatible, and may have unexpected bugs. Please contact us with any feedback!

For NumPy functionality that can be used with Array, see NumPy Functions.

Array¶

Classes:

`Array`(arr)	Proxy Array representing a multidimensional, homogenous array of fixed-size items.
`MaskedArray`(data[, mask, fill_value])	Proxy MaskedArray representing a multidimensional, homogenous array of fixed-size items that may have missing or invalid entries.
`BaseArray`
`Scalar`(obj)	Proxy Scalar object
`DType`(type_)	A Proxy object for representing the data type of an Array/MaskedArray.

class Array(arr)[source]¶

Proxy Array representing a multidimensional, homogenous array of fixed-size items.

Can be instantiated from a NumPy ndarray (via from_numpy), or a Python iterable. Currently, Arrays can only be constructed from small local arrays (< 10MB). Array follows the same syntax as NumPy arrays. It supports vectorized operations, broadcasting, and multidimensional indexing. There are some limitations including slicing with lists/arrays in multiple axes (x[[1, 2, 3], [3, 2, 1]]) and slicing with a multidimensional list/array of integers.

Note

Array is an experimental API. It may be changed in the future, will not necessarily be backwards compatible, and may have unexpected bugs. Please contact us with any feedback!

Examples

>>> import descarteslabs.workflows as wf
>>> # Create a 1-dimensional Array of Ints
>>> arr = wf.Array([1, 2, 3, 4, 5])
>>> arr
<descarteslabs.workflows.types.array.array_.Array object at 0x...>
>>> arr.compute(geoctx) 
array([1, 2, 3, 4, 5])

>>> import numpy as np
>>> import descarteslabs.workflows as wf
>>> ndarray = np.ones((3, 10, 10))
>>> # Create an Array from the 3-dimensional numpy array
>>> arr = wf.Array(ndarray)
>>> arr
<descarteslabs.workflows.types.array.array_.Array object at 0x...>

Methods:

`astype`(dtype)	Return `Array` cast to a specific type.
`compute`([format, destination, file, …])	Compute a proxy object and wait for its result.
`flatten`()	Return a contiguous flattened version of `Array`.
`inspect`([format, file, cache, _ruster, …])	Quickly compute a proxy object using a low-latency, lower-reliability backend.
`max`([axis])	Maximum along a given axis.
`mean`([axis])	Mean along a given axis.
`median`([axis])	Median along a given axis.
`min`([axis])	Minimum along a given axis.
`publish`(version[, title, description, …])	Publish a proxy object as a `Workflow` with the given version.
`reshape`(*newshape)	Returns an `Array` containing the same data with a new shape.
`std`([axis])	Standard deviation along a given axis.
`sum`([axis])	Sum along a given axis.
`to_imagery`([properties, bandinfo])	Turns a proxy Array into an `ImageCollection`.

Attributes:

`dtype`	The type of the data contained in the Array.
`literal_value`	Python literal value this proxy object was constructed with, or None if not constructed from a literal value.
`ndim`	The number of dimensions of the Array.
`shape`	The shape of the Array.
`size`	The number of elements in the Array.

astype(dtype)¶

Return Array cast to a specific type.

Parameters:	dtype (Str) – Data type to cast Array to. Can be one of `int`, `float`, or `bool` (and their variations).

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([True, False, True])
>>> int_arr = arr.astype("int")
>>> int_arr.dtype.compute() 
dtype('int64')
>>> int_arr.compute() 
array([1, 0, 1])

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)¶

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters:	geoctx (`GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None. destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. timeout (Int, optional) – The number of seconds to wait for the result, if `block` is True. Raises `JobTimeoutError` if the timeout passes. block (Bool, default True) – If True (default), block until the job is completed, or `timeout` has passed. If False, immediately returns a `Job` (which has already had `execute` called). progress_bar (Bool, default None) – Whether to draw the progress bar. If `None` (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if `block==False`. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous `compute` requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information. *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.
Return type:	Python object, bytes, or None
Raises:	RetryError – Raised if there are too many failed retries. Inspect `RetryError.exceptions` to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more `ResourceExhausted` exceptions.

flatten()¶

Return a contiguous flattened version of Array.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.flatten().compute() 
array([1, 2, 3, 4, 5, 6])

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)¶

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters:	geoctx (`common.geo.geocontext.GeoContext`, `GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. cache (bool, default True) – Whether to use the cache for this job. timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises `JobTimeoutError` if the timeout passes. client (`workflows.inspect.InspectClient`, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file.
Return type:	Python object or bytes

max(axis=None)¶

Maximum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply maximum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.max(axis=2).compute(geoctx) 
masked_array(
  data=[[0.3429, 0.3429, 0.3429, ..., 0.4685, 0.4685, 0.4685],
        [0.4548, 0.4758, 0.5089, ..., 0.4457, 0.4548, 0.4589],
        [0.4095, 0.4338, 0.439 , ..., 0.417 , 0.4261, 0.4361],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ]],
mask=False,
fill_value=1e+20)

mean(axis=None)¶

Mean along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply mean over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.mean(axis=2).compute(geoctx) 
masked_array(
  data=[[0.12258809, 0.12258809, 0.12258809, ..., 0.20478262, 0.20478262, 0.20478262],
        [0.11682598, 0.11911875, 0.11996387, ..., 0.17967012, 0.18027852, 0.1817543 ],
        [0.10004336, 0.10156348, 0.10262227, ..., 0.17302051, 0.17299277, 0.17431074],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375]],
mask=False,
fill_value=1e+20)

median(axis=None)¶

Median along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply median over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.median(axis=2).compute(geoctx) 
masked_array(
  data=[[0.1128 , 0.1128 , 0.1128 , ..., 0.1613 , 0.1613 , 0.1613 ],
        [0.0881 , 0.08595, 0.08545, ..., 0.133  , 0.1306 , 0.13135],
        [0.0739 , 0.0702 , 0.0695 , ..., 0.13035, 0.13025, 0.1308 ],
        ...,
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ]],
mask=False,
fill_value=1e+20)

min(axis=None)¶

Minimum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply minimum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.min(axis=2).compute(geoctx) 
masked_array(
  data=[[0.0901, 0.0901, 0.0901, ..., 0.1025, 0.1025, 0.1025],
        [0.0642, 0.0645, 0.065 , ..., 0.0792, 0.0788, 0.079 ],
        [0.0462, 0.0462, 0.0464, ..., 0.0614, 0.0616, 0.0622],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ]],
mask=False,
fill_value=1e+20)

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)¶

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters:	id (Str) – ID for the new Workflow object. This should be of the form `email:workflow_name` and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow. version (Str) – The version to be set, tied to the given `obj`. This should adhere to the semantic versioning schema. title (Str, default "") – User-friendly title for the `Workflow`. description (str, default "") – Long-form description of this `Workflow`. Markdown is supported. labels (Dict, optional) – Key-value pair labels to add to the `Workflow`. tags (list, optional) – A list of strings to add as tags to the `Workflow`. docstring (Str, default "") – The docstring for this version. version_labels (Dict, optional) – Key-value pair labels to add to the version. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:	workflow – The saved `Workflow` object. `workflow.id` contains the ID of the new Workflow.
Return type:	Workflow or Function

reshape(*newshape)¶

Returns an Array containing the same data with a new shape.

See reshape for full documentation.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.reshape(-1).compute() 
array([1, 2, 3, 4, 5, 6])

std(axis=None)¶

Standard deviation along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply standard deviation over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.std(axis=2).compute(geoctx) 
masked_array(
  data=[[0.04008153, 0.04008153, 0.04008153, ..., 0.09525769, 0.09525769, 0.09525769],
        [0.08456076, 0.09000384, 0.09356615, ..., 0.09512879, 0.09453823, 0.09345682],
        [0.07483621, 0.08026347, 0.08554651, ..., 0.0923489 , 0.09133476, 0.09047391],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277]],
mask=False,
fill_value=1e+20)

sum(axis=None)¶

Sum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply sum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.sum(axis=2).compute(geoctx) 
masked_array(
  data=[[ 62.7651,  62.7651,  62.7651, ..., 104.8487, 104.8487, 104.8487],
        [ 59.8149,  60.9888,  61.4215, ...,  91.9911,  92.3026,  93.0582],
        [ 51.2222,  52.0005,  52.5426, ...,  88.5865,  88.5723,  89.2471],
        ...,
        [  0.    ,   0.    ,   0.    , ...,   0.    ,   0.    ,   0.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ]],
mask=False,
fill_value=1e+20)

to_imagery(properties=None, bandinfo=None)¶

Turns a proxy Array into an ImageCollection.

Note that this function always returns an ImageCollection, even if the Array is only 3D. If you are expecting an Image, you can index into the result like my_col[0].

Parameters:

properties (Dict or List, default None) – Properties of the new Image or ImageCollection. If the Array is 3-dimensional, properties should be a dictionary. If the Array is 4-dimensional and properties is a dictionary, the properties will be broadcast to the length of the new ImageCollection. If the Array is 4-dimensional and properties is a list, the length of the list must be equal to the length of the outermost dimension of the Array (arr.shape[0]). If no properties are given, the properties will be an empty dictionary (Image), or list of empty dictionaries (ImageCollection).
bandinfo (Dict, default None) – Bandinfo for the new Image or ImageCollection. Must be equal in length to the number of bands in the Array. Therefore, if the Array is 3-dimensional (an Image), bandinfo must be the length of arr.shape[0]. If the Array is 4-dimensional (an ImageCollection), bandinfo must be the length of arr.shape[1]. If no bandinfo is given, the bandinfo will be a dict of bandname (of the format ‘band_<num>’, where ‘num’ is 1…N) to empty dictionary.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-12-01")
>>>
>>> # Take images 1, 2, and 3, as well as their first 3 bands
>>> # This complicated indexing cannot be done on an ImageCollection
>>> # so we index the underlying Array instead
>>> arr = col.ndarray[[1, 2, 3], :3]
>>>
>>> # Construct a new ImageCollection with specified bandinfo
>>> new_col = arr.to_imagery(bandinfo={"red": {}, "green": {}, "blue": {}})
>>> new_col.compute(geoctx) 
ImageCollectionResult of length 3:
  * ndarray: MaskedArray<shape=(3, 3, 512, 512), dtype=float64>
  * properties: 3 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...

property dtype¶

The type of the data contained in the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.dtype.compute(geoctx) 
dtype("float64")

property literal_value¶: Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

property ndim¶

The number of dimensions of the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.ndim.compute(geoctx) 
3

property shape¶

The shape of the Array. If the shape of the Array is unknown along a dimension, it will be -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> # The x and y pixel shapes are dependent upon 'geoctx'
>>> arr.shape.compute(geoctx) 
(3, 512, 512)

property size¶

The number of elements in the Array. If the shape of the Array is unknown along a dimension, the resulting size is also unknown. In this case size will return -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> arr.size.compute() 
786432

class MaskedArray(data, mask=False, fill_value=None)[source]¶

Proxy MaskedArray representing a multidimensional, homogenous array of fixed-size items that may have missing or invalid entries. MaskedArray follows the same syntax as NumPy masked arrays. It supports vectorized operations, broadcasting, and multidimensional indexing. There are some limitations including slicing with lists/arrays in multiple axes (x[[1, 2, 3], [3, 2, 1]]) and slicing with a multidimensional list/array of integers.

Note

MaskedArray is an experimental API. It may be changed in the future, will not necessarily be backwards compatible, and may have unexpected bugs. Please contact us with any feedback!

Examples

>>> import descarteslabs.workflows as wf
>>> arr = wf.MaskedArray(data=[1, 2, 3, 4], mask=[True, False, False, True], fill_value=0)
>>> arr
<descarteslabs.workflows.types.array.masked_array.MaskedArray object at 0x...>
>>> arr.compute(geoctx) 
masked_array(data=[--, 2, 3, --],
             mask=[ True, False, False,  True],
       fill_value=0)

Methods:

`astype`(dtype)	Return `Array` cast to a specific type.
`compressed`()	Returns all the non-masked data as a 1D `Array`.
`compute`([format, destination, file, …])	Compute a proxy object and wait for its result.
`count`([axis])	Count unmasked pixels along a given axis.
`filled`([fill_value])	Returns an Array with all masked data replaced by the given fill value.
`flatten`()	Return a contiguous flattened version of `Array`.
`from_numpy`(arr)	Construct a Workflows MaskedArray from a NumPy MaskedArray.
`getdata`()	The data array underlying this `MaskedArray`.
`getmaskarray`()	The mask array underlying this `MaskedArray`.
`inspect`([format, file, cache, _ruster, …])	Quickly compute a proxy object using a low-latency, lower-reliability backend.
`max`([axis])	Maximum along a given axis.
`mean`([axis])	Mean along a given axis.
`median`([axis])	Median along a given axis.
`min`([axis])	Minimum along a given axis.
`publish`(version[, title, description, …])	Publish a proxy object as a `Workflow` with the given version.
`reshape`(*newshape)	Returns an `Array` containing the same data with a new shape.
`std`([axis])	Standard deviation along a given axis.
`sum`([axis])	Sum along a given axis.
`to_imagery`([properties, bandinfo])	Turns a proxy Array into an `ImageCollection`.

Attributes:

`dtype`	The type of the data contained in the Array.
`literal_value`	Python literal value this proxy object was constructed with, or None if not constructed from a literal value.
`ndim`	The number of dimensions of the Array.
`shape`	The shape of the Array.
`size`	The number of elements in the Array.

astype(dtype)¶

Return Array cast to a specific type.

Parameters:	dtype (Str) – Data type to cast Array to. Can be one of `int`, `float`, or `bool` (and their variations).

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([True, False, True])
>>> int_arr = arr.astype("int")
>>> int_arr.dtype.compute() 
dtype('int64')
>>> int_arr.compute() 
array([1, 0, 1])

compressed()[source]¶

Returns all the non-masked data as a 1D Array.

Example

>>> import descarteslabs.workflows as wf
>>> ma = wf.MaskedArray([[1, 2], [3, 4]], mask=[[True, False], [False, True]])
>>> compressed = ma.compressed()
>>> compressed.compute() 
array([2, 3])

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)¶

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters:	geoctx (`GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None. destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. timeout (Int, optional) – The number of seconds to wait for the result, if `block` is True. Raises `JobTimeoutError` if the timeout passes. block (Bool, default True) – If True (default), block until the job is completed, or `timeout` has passed. If False, immediately returns a `Job` (which has already had `execute` called). progress_bar (Bool, default None) – Whether to draw the progress bar. If `None` (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if `block==False`. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous `compute` requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information. *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.
Return type:	Python object, bytes, or None
Raises:	RetryError – Raised if there are too many failed retries. Inspect `RetryError.exceptions` to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more `ResourceExhausted` exceptions.

count(axis=None)[source]¶

Count unmasked pixels along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply count over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.count(axis=2).compute(geoctx) 
masked_array(
  data=[[512., 512., 512., ..., 512., 512., 512.],
        [512., 512., 512., ..., 512., 512., 512.],
        [512., 512., 512., ..., 512., 512., 512.],
        ...,
        [512., 512., 512., ..., 512., 512., 512.],
        [512., 512., 512., ..., 512., 512., 512.],
        [512., 512., 512., ..., 512., 512., 512.]],
mask=False,
fill_value=1e+20)

filled(fill_value=None)[source]¶

Returns an Array with all masked data replaced by the given fill value. If no fill_value argument is provided, the fill value on this MaskedArray will be used.

Parameters:	fill_value (scalar or Array, optional, default None) – The value used to replace masked data.
Returns:	a
Return type:	Array

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> # In this case, 'geoctx' results in fully masked data
>>> arr.filled(0.1).compute(geoctx) 
array([[[0.1, 0.1, 0.1, ..., 0.1, 0.1, 0.1],
        [0.1, 0.1, 0.1, ..., 0.1, 0.1, 0.1],
        [0.1, 0.1, 0.1, ..., 0.1, 0.1, 0.1],
...

flatten()¶

Return a contiguous flattened version of Array.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.flatten().compute() 
array([1, 2, 3, 4, 5, 6])

classmethod from_numpy(arr)[source]¶

Construct a Workflows MaskedArray from a NumPy MaskedArray.

Parameters:	arr (numpy.ma.MaskedArray) –
Returns:
Return type:	MaskedArray

Example

>>> import descarteslabs.workflows as wf
>>> import numpy as np
>>> arr = np.ma.array(data=[1, 2, 3, 4], mask=[True, False, False, True], fill_value=0)
>>> ma = wf.MaskedArray.from_numpy(arr)
>>> ma.compute() 
masked_array(data=[--, 2, 3, --],
...          mask=[ True, False, False,  True],
...    fill_value=0)

getdata()[source]¶

The data array underlying this MaskedArray.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.getdata().compute(geoctx) 
array([[[0.3429, 0.3429, 0.3429, ..., 0.0952, 0.0952, 0.0952],
        [0.3429, 0.3429, 0.3429, ..., 0.0952, 0.0952, 0.0952],
        [0.3429, 0.3429, 0.3429, ..., 0.0952, 0.0952, 0.0952],
...

getmaskarray()[source]¶

The mask array underlying this MaskedArray.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.getmaskarray().compute(geoctx) 
array([[[False, False, False, ..., False, False, False],
        [False, False, False, ..., False, False, False],
        [False, False, False, ..., False, False, False],
...

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)¶

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters:	geoctx (`common.geo.geocontext.GeoContext`, `GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. cache (bool, default True) – Whether to use the cache for this job. timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises `JobTimeoutError` if the timeout passes. client (`workflows.inspect.InspectClient`, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file.
Return type:	Python object or bytes

max(axis=None)¶

Maximum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply maximum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.max(axis=2).compute(geoctx) 
masked_array(
  data=[[0.3429, 0.3429, 0.3429, ..., 0.4685, 0.4685, 0.4685],
        [0.4548, 0.4758, 0.5089, ..., 0.4457, 0.4548, 0.4589],
        [0.4095, 0.4338, 0.439 , ..., 0.417 , 0.4261, 0.4361],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ]],
mask=False,
fill_value=1e+20)

mean(axis=None)¶

Mean along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply mean over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.mean(axis=2).compute(geoctx) 
masked_array(
  data=[[0.12258809, 0.12258809, 0.12258809, ..., 0.20478262, 0.20478262, 0.20478262],
        [0.11682598, 0.11911875, 0.11996387, ..., 0.17967012, 0.18027852, 0.1817543 ],
        [0.10004336, 0.10156348, 0.10262227, ..., 0.17302051, 0.17299277, 0.17431074],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375]],
mask=False,
fill_value=1e+20)

median(axis=None)¶

Median along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply median over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.median(axis=2).compute(geoctx) 
masked_array(
  data=[[0.1128 , 0.1128 , 0.1128 , ..., 0.1613 , 0.1613 , 0.1613 ],
        [0.0881 , 0.08595, 0.08545, ..., 0.133  , 0.1306 , 0.13135],
        [0.0739 , 0.0702 , 0.0695 , ..., 0.13035, 0.13025, 0.1308 ],
        ...,
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ]],
mask=False,
fill_value=1e+20)

min(axis=None)¶

Minimum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply minimum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.min(axis=2).compute(geoctx) 
masked_array(
  data=[[0.0901, 0.0901, 0.0901, ..., 0.1025, 0.1025, 0.1025],
        [0.0642, 0.0645, 0.065 , ..., 0.0792, 0.0788, 0.079 ],
        [0.0462, 0.0462, 0.0464, ..., 0.0614, 0.0616, 0.0622],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ]],
mask=False,
fill_value=1e+20)

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)¶

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters:	id (Str) – ID for the new Workflow object. This should be of the form `email:workflow_name` and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow. version (Str) – The version to be set, tied to the given `obj`. This should adhere to the semantic versioning schema. title (Str, default "") – User-friendly title for the `Workflow`. description (str, default "") – Long-form description of this `Workflow`. Markdown is supported. labels (Dict, optional) – Key-value pair labels to add to the `Workflow`. tags (list, optional) – A list of strings to add as tags to the `Workflow`. docstring (Str, default "") – The docstring for this version. version_labels (Dict, optional) – Key-value pair labels to add to the version. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:	workflow – The saved `Workflow` object. `workflow.id` contains the ID of the new Workflow.
Return type:	Workflow or Function

reshape(*newshape)¶

Returns an Array containing the same data with a new shape.

See reshape for full documentation.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.reshape(-1).compute() 
array([1, 2, 3, 4, 5, 6])

std(axis=None)¶

Standard deviation along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply standard deviation over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.std(axis=2).compute(geoctx) 
masked_array(
  data=[[0.04008153, 0.04008153, 0.04008153, ..., 0.09525769, 0.09525769, 0.09525769],
        [0.08456076, 0.09000384, 0.09356615, ..., 0.09512879, 0.09453823, 0.09345682],
        [0.07483621, 0.08026347, 0.08554651, ..., 0.0923489 , 0.09133476, 0.09047391],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277]],
mask=False,
fill_value=1e+20)

sum(axis=None)¶

Sum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply sum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.sum(axis=2).compute(geoctx) 
masked_array(
  data=[[ 62.7651,  62.7651,  62.7651, ..., 104.8487, 104.8487, 104.8487],
        [ 59.8149,  60.9888,  61.4215, ...,  91.9911,  92.3026,  93.0582],
        [ 51.2222,  52.0005,  52.5426, ...,  88.5865,  88.5723,  89.2471],
        ...,
        [  0.    ,   0.    ,   0.    , ...,   0.    ,   0.    ,   0.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ]],
mask=False,
fill_value=1e+20)

to_imagery(properties=None, bandinfo=None)¶

Turns a proxy Array into an ImageCollection.

Note that this function always returns an ImageCollection, even if the Array is only 3D. If you are expecting an Image, you can index into the result like my_col[0].

Parameters:

properties (Dict or List, default None) – Properties of the new Image or ImageCollection. If the Array is 3-dimensional, properties should be a dictionary. If the Array is 4-dimensional and properties is a dictionary, the properties will be broadcast to the length of the new ImageCollection. If the Array is 4-dimensional and properties is a list, the length of the list must be equal to the length of the outermost dimension of the Array (arr.shape[0]). If no properties are given, the properties will be an empty dictionary (Image), or list of empty dictionaries (ImageCollection).
bandinfo (Dict, default None) – Bandinfo for the new Image or ImageCollection. Must be equal in length to the number of bands in the Array. Therefore, if the Array is 3-dimensional (an Image), bandinfo must be the length of arr.shape[0]. If the Array is 4-dimensional (an ImageCollection), bandinfo must be the length of arr.shape[1]. If no bandinfo is given, the bandinfo will be a dict of bandname (of the format ‘band_<num>’, where ‘num’ is 1…N) to empty dictionary.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-12-01")
>>>
>>> # Take images 1, 2, and 3, as well as their first 3 bands
>>> # This complicated indexing cannot be done on an ImageCollection
>>> # so we index the underlying Array instead
>>> arr = col.ndarray[[1, 2, 3], :3]
>>>
>>> # Construct a new ImageCollection with specified bandinfo
>>> new_col = arr.to_imagery(bandinfo={"red": {}, "green": {}, "blue": {}})
>>> new_col.compute(geoctx) 
ImageCollectionResult of length 3:
  * ndarray: MaskedArray<shape=(3, 3, 512, 512), dtype=float64>
  * properties: 3 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...

property dtype¶

The type of the data contained in the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.dtype.compute(geoctx) 
dtype("float64")

property literal_value¶: Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

property ndim¶

The number of dimensions of the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.ndim.compute(geoctx) 
3

property shape¶

The shape of the Array. If the shape of the Array is unknown along a dimension, it will be -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> # The x and y pixel shapes are dependent upon 'geoctx'
>>> arr.shape.compute(geoctx) 
(3, 512, 512)

property size¶

The number of elements in the Array. If the shape of the Array is unknown along a dimension, the resulting size is also unknown. In this case size will return -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> arr.size.compute() 
786432

class BaseArray[source]¶

Methods:

`astype`(dtype)	Return `Array` cast to a specific type.
`compute`([format, destination, file, …])	Compute a proxy object and wait for its result.
`flatten`()	Return a contiguous flattened version of `Array`.
`inspect`([format, file, cache, _ruster, …])	Quickly compute a proxy object using a low-latency, lower-reliability backend.
`max`([axis])	Maximum along a given axis.
`mean`([axis])	Mean along a given axis.
`median`([axis])	Median along a given axis.
`min`([axis])	Minimum along a given axis.
`publish`(version[, title, description, …])	Publish a proxy object as a `Workflow` with the given version.
`reshape`(*newshape)	Returns an `Array` containing the same data with a new shape.
`std`([axis])	Standard deviation along a given axis.
`sum`([axis])	Sum along a given axis.
`to_imagery`([properties, bandinfo])	Turns a proxy Array into an `ImageCollection`.

Attributes:

`dtype`	The type of the data contained in the Array.
`literal_value`	Python literal value this proxy object was constructed with, or None if not constructed from a literal value.
`ndim`	The number of dimensions of the Array.
`shape`	The shape of the Array.
`size`	The number of elements in the Array.

astype(dtype)[source]¶

Return Array cast to a specific type.

Parameters:	dtype (Str) – Data type to cast Array to. Can be one of `int`, `float`, or `bool` (and their variations).

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([True, False, True])
>>> int_arr = arr.astype("int")
>>> int_arr.dtype.compute() 
dtype('int64')
>>> int_arr.compute() 
array([1, 0, 1])

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)¶

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters:	geoctx (`GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None. destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. timeout (Int, optional) – The number of seconds to wait for the result, if `block` is True. Raises `JobTimeoutError` if the timeout passes. block (Bool, default True) – If True (default), block until the job is completed, or `timeout` has passed. If False, immediately returns a `Job` (which has already had `execute` called). progress_bar (Bool, default None) – Whether to draw the progress bar. If `None` (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if `block==False`. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous `compute` requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information. *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.
Return type:	Python object, bytes, or None
Raises:	RetryError – Raised if there are too many failed retries. Inspect `RetryError.exceptions` to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more `ResourceExhausted` exceptions.

flatten()[source]¶

Return a contiguous flattened version of Array.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.flatten().compute() 
array([1, 2, 3, 4, 5, 6])

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)¶

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters:	geoctx (`common.geo.geocontext.GeoContext`, `GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. cache (bool, default True) – Whether to use the cache for this job. timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises `JobTimeoutError` if the timeout passes. client (`workflows.inspect.InspectClient`, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file.
Return type:	Python object or bytes

max(axis=None)[source]¶

Maximum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply maximum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.max(axis=2).compute(geoctx) 
masked_array(
  data=[[0.3429, 0.3429, 0.3429, ..., 0.4685, 0.4685, 0.4685],
        [0.4548, 0.4758, 0.5089, ..., 0.4457, 0.4548, 0.4589],
        [0.4095, 0.4338, 0.439 , ..., 0.417 , 0.4261, 0.4361],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ],
        [1.    , 1.    , 1.    , ..., 1.    , 1.    , 1.    ]],
mask=False,
fill_value=1e+20)

mean(axis=None)[source]¶

Mean along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply mean over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.mean(axis=2).compute(geoctx) 
masked_array(
  data=[[0.12258809, 0.12258809, 0.12258809, ..., 0.20478262, 0.20478262, 0.20478262],
        [0.11682598, 0.11911875, 0.11996387, ..., 0.17967012, 0.18027852, 0.1817543 ],
        [0.10004336, 0.10156348, 0.10262227, ..., 0.17302051, 0.17299277, 0.17431074],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375],
        [0.00390625, 0.00390625, 0.00390625, ..., 0.05859375, 0.05859375, 0.05859375]],
mask=False,
fill_value=1e+20)

median(axis=None)[source]¶

Median along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply median over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.median(axis=2).compute(geoctx) 
masked_array(
  data=[[0.1128 , 0.1128 , 0.1128 , ..., 0.1613 , 0.1613 , 0.1613 ],
        [0.0881 , 0.08595, 0.08545, ..., 0.133  , 0.1306 , 0.13135],
        [0.0739 , 0.0702 , 0.0695 , ..., 0.13035, 0.13025, 0.1308 ],
        ...,
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ],
        [0.     , 0.     , 0.     , ..., 0.     , 0.     , 0.     ]],
mask=False,
fill_value=1e+20)

min(axis=None)[source]¶

Minimum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply minimum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.min(axis=2).compute(geoctx) 
masked_array(
  data=[[0.0901, 0.0901, 0.0901, ..., 0.1025, 0.1025, 0.1025],
        [0.0642, 0.0645, 0.065 , ..., 0.0792, 0.0788, 0.079 ],
        [0.0462, 0.0462, 0.0464, ..., 0.0614, 0.0616, 0.0622],
        ...,
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ],
        [0.    , 0.    , 0.    , ..., 0.    , 0.    , 0.    ]],
mask=False,
fill_value=1e+20)

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)¶

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters:	id (Str) – ID for the new Workflow object. This should be of the form `email:workflow_name` and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow. version (Str) – The version to be set, tied to the given `obj`. This should adhere to the semantic versioning schema. title (Str, default "") – User-friendly title for the `Workflow`. description (str, default "") – Long-form description of this `Workflow`. Markdown is supported. labels (Dict, optional) – Key-value pair labels to add to the `Workflow`. tags (list, optional) – A list of strings to add as tags to the `Workflow`. docstring (Str, default "") – The docstring for this version. version_labels (Dict, optional) – Key-value pair labels to add to the version. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:	workflow – The saved `Workflow` object. `workflow.id` contains the ID of the new Workflow.
Return type:	Workflow or Function

reshape(*newshape)[source]¶

Returns an Array containing the same data with a new shape.

See reshape for full documentation.

Example

>>> import descarteslabs.workflows as wf
>>> arr = wf.Array([[1, 2, 3], [4, 5, 6]])
>>> arr.reshape(-1).compute() 
array([1, 2, 3, 4, 5, 6])

std(axis=None)[source]¶

Standard deviation along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply standard deviation over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.std(axis=2).compute(geoctx) 
masked_array(
  data=[[0.04008153, 0.04008153, 0.04008153, ..., 0.09525769, 0.09525769, 0.09525769],
        [0.08456076, 0.09000384, 0.09356615, ..., 0.09512879, 0.09453823, 0.09345682],
        [0.07483621, 0.08026347, 0.08554651, ..., 0.0923489 , 0.09133476, 0.09047391],
        ...,
        [0.        , 0.        , 0.        , ..., 0.        , 0.        , 0.        ],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277],
        [0.06237781, 0.06237781, 0.06237781, ..., 0.23486277, 0.23486277, 0.23486277]],
mask=False,
fill_value=1e+20)

sum(axis=None)[source]¶

Sum along a given axis.

Parameters:	axis (Int or sequence of Ints, optional, default None) – Axis or axes to apply sum over

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.sum(axis=2).compute(geoctx) 
masked_array(
  data=[[ 62.7651,  62.7651,  62.7651, ..., 104.8487, 104.8487, 104.8487],
        [ 59.8149,  60.9888,  61.4215, ...,  91.9911,  92.3026,  93.0582],
        [ 51.2222,  52.0005,  52.5426, ...,  88.5865,  88.5723,  89.2471],
        ...,
        [  0.    ,   0.    ,   0.    , ...,   0.    ,   0.    ,   0.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ],
        [  2.    ,   2.    ,   2.    , ...,  30.    ,  30.    ,  30.    ]],
mask=False,
fill_value=1e+20)

to_imagery(properties=None, bandinfo=None)[source]¶

Turns a proxy Array into an ImageCollection.

Note that this function always returns an ImageCollection, even if the Array is only 3D. If you are expecting an Image, you can index into the result like my_col[0].

Parameters:

properties (Dict or List, default None) – Properties of the new Image or ImageCollection. If the Array is 3-dimensional, properties should be a dictionary. If the Array is 4-dimensional and properties is a dictionary, the properties will be broadcast to the length of the new ImageCollection. If the Array is 4-dimensional and properties is a list, the length of the list must be equal to the length of the outermost dimension of the Array (arr.shape[0]). If no properties are given, the properties will be an empty dictionary (Image), or list of empty dictionaries (ImageCollection).
bandinfo (Dict, default None) – Bandinfo for the new Image or ImageCollection. Must be equal in length to the number of bands in the Array. Therefore, if the Array is 3-dimensional (an Image), bandinfo must be the length of arr.shape[0]. If the Array is 4-dimensional (an ImageCollection), bandinfo must be the length of arr.shape[1]. If no bandinfo is given, the bandinfo will be a dict of bandname (of the format ‘band_<num>’, where ‘num’ is 1…N) to empty dictionary.

Example

>>> import descarteslabs.workflows as wf
>>> col = wf.ImageCollection.from_id("landsat:LC08:01:RT:TOAR",
...     start_datetime="2017-01-01", end_datetime="2017-12-01")
>>>
>>> # Take images 1, 2, and 3, as well as their first 3 bands
>>> # This complicated indexing cannot be done on an ImageCollection
>>> # so we index the underlying Array instead
>>> arr = col.ndarray[[1, 2, 3], :3]
>>>
>>> # Construct a new ImageCollection with specified bandinfo
>>> new_col = arr.to_imagery(bandinfo={"red": {}, "green": {}, "blue": {}})
>>> new_col.compute(geoctx) 
ImageCollectionResult of length 3:
  * ndarray: MaskedArray<shape=(3, 3, 512, 512), dtype=float64>
  * properties: 3 items
  * bandinfo: 'red', 'green', 'blue'
  * geocontext: 'geometry', 'key', 'resolution', 'tilesize', ...

property dtype¶

The type of the data contained in the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.dtype.compute(geoctx) 
dtype("float64")

property literal_value¶: Python literal value this proxy object was constructed with, or None if not constructed from a literal value.

property ndim¶

The number of dimensions of the Array.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> arr = img.ndarray
>>> arr.ndim.compute(geoctx) 
3

property shape¶

The shape of the Array. If the shape of the Array is unknown along a dimension, it will be -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> # The x and y pixel shapes are dependent upon 'geoctx'
>>> arr.shape.compute(geoctx) 
(3, 512, 512)

property size¶

The number of elements in the Array. If the shape of the Array is unknown along a dimension, the resulting size is also unknown. In this case size will return -1.

Example

>>> import descarteslabs.workflows as wf
>>> img = wf.Image.from_id("sentinel-2:L1C:2019-05-04_13SDV_99_S2B_v1")
>>> rgb = img.pick_bands("red green blue")
>>> arr = rgb.ndarray
>>> arr.size.compute() 
786432

class Scalar(obj)[source]¶

Proxy Scalar object

Internal class used as the return type for Array operations that return scalar values

You shouldn’t use this class directly. Instead, use the Int, Float, or Bool classes.

Methods:

`compute`([format, destination, file, …])	Compute a proxy object and wait for its result.
`inspect`([format, file, cache, _ruster, …])	Quickly compute a proxy object using a low-latency, lower-reliability backend.
`publish`(version[, title, description, …])	Publish a proxy object as a `Workflow` with the given version.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)¶

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters:	geoctx (`GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None. destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. timeout (Int, optional) – The number of seconds to wait for the result, if `block` is True. Raises `JobTimeoutError` if the timeout passes. block (Bool, default True) – If True (default), block until the job is completed, or `timeout` has passed. If False, immediately returns a `Job` (which has already had `execute` called). progress_bar (Bool, default None) – Whether to draw the progress bar. If `None` (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if `block==False`. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous `compute` requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information. *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.
Return type:	Python object, bytes, or None
Raises:	RetryError – Raised if there are too many failed retries. Inspect `RetryError.exceptions` to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more `ResourceExhausted` exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)¶

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters:	geoctx (`common.geo.geocontext.GeoContext`, `GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. cache (bool, default True) – Whether to use the cache for this job. timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises `JobTimeoutError` if the timeout passes. client (`workflows.inspect.InspectClient`, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file.
Return type:	Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)¶

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters:	id (Str) – ID for the new Workflow object. This should be of the form `email:workflow_name` and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow. version (Str) – The version to be set, tied to the given `obj`. This should adhere to the semantic versioning schema. title (Str, default "") – User-friendly title for the `Workflow`. description (str, default "") – Long-form description of this `Workflow`. Markdown is supported. labels (Dict, optional) – Key-value pair labels to add to the `Workflow`. tags (list, optional) – A list of strings to add as tags to the `Workflow`. docstring (Str, default "") – The docstring for this version. version_labels (Dict, optional) – Key-value pair labels to add to the version. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:	workflow – The saved `Workflow` object. `workflow.id` contains the ID of the new Workflow.
Return type:	Workflow or Function

class DType(type_)[source]¶

A Proxy object for representing the data type of an Array/MaskedArray.

Should not be worked with directly.

Methods:

`compute`([format, destination, file, …])	Compute a proxy object and wait for its result.
`inspect`([format, file, cache, _ruster, …])	Quickly compute a proxy object using a low-latency, lower-reliability backend.
`publish`(version[, title, description, …])	Publish a proxy object as a `Workflow` with the given version.

compute(format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, cache=True, _ruster=None, _trace=False, client=None, num_retries=None, **arguments)¶

Compute a proxy object and wait for its result.

If the caller has too many outstanding compute jobs, this will raise a ResourceExhausted exception.

Parameters:	geoctx (`GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (Str or Dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes or None. destination (str or dict, default "download") – The destination for the result. See the destinations documentation for more information. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. timeout (Int, optional) – The number of seconds to wait for the result, if `block` is True. Raises `JobTimeoutError` if the timeout passes. block (Bool, default True) – If True (default), block until the job is completed, or `timeout` has passed. If False, immediately returns a `Job` (which has already had `execute` called). progress_bar (Bool, default None) – Whether to draw the progress bar. If `None` (default), will display a progress bar in Jupyter Notebooks, but not elsewhere. Ignored if `block==False`. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters num_retries (Int, optional) – The number of retries to make in the event of a request failure. If you are making numerous long-running asynchronous requests, you can use this parameter as a way to indicate that you are comfortable waiting and retrying in response to RESOURCE EXHAUSTED errors. By default, most failures will trigger a small number of retries, but if you have reached your outstanding job limit, by default, the client will not retry. This parameter is unnecessary when making synchronous `compute` requests (ie. block=True, the default). See the compute section of the Workflows Guide for more information. *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file. If the destination doesn’t support retrieving results (like “email”), returns None.
Return type:	Python object, bytes, or None
Raises:	RetryError – Raised if there are too many failed retries. Inspect `RetryError.exceptions` to determine the ultimate cause of the error. If you reach your maximum number of outstanding compute jobs, there will be one or more `ResourceExhausted` exceptions.

inspect(format='pyarrow', file=None, cache=True, _ruster=None, timeout=60, client=None, **arguments)¶

Quickly compute a proxy object using a low-latency, lower-reliability backend.

Inspect is meant for getting simple computations out of Workflows, primarily for interactive use. It’s quicker but less resilient, won’t be retried if it fails, and has no progress updates.

If you have a larger computation (longer than ~30sec), or you want to be sure the computation will succeed, use compute instead. compute creates a Job, which runs asynchronously, will be retried if it fails, and stores its results for later retrieval.

Parameters:	geoctx (`common.geo.geocontext.GeoContext`, `GeoContext`, or None) – The GeoContext parameter under which to run the computation. Almost all computations will require a `GeoContext`, but for operations that only involve non-geospatial types, this parameter is optional. format (str or dict, default "pyarrow") – The serialization format for the result. See the formats documentation for more information. If “pyarrow” (the default), returns an appropriate Python object, otherwise returns raw bytes. file (path or file-like object, optional) – If specified, writes results to the path or file instead of returning them. cache (bool, default True) – Whether to use the cache for this job. timeout (int, optional, default 60) – The number of seconds to wait for the result. Raises `JobTimeoutError` if the timeout passes. client (`workflows.inspect.InspectClient`, optional) – Allows you to use a specific InspectClient instance with non-default auth and parameters *arguments (Any*) – Values for all parameters that `obj` depends on (or arguments that `obj` takes, if it’s a `Function`). Can be given as Proxytypes, or as Python objects like numbers, lists, and dicts that can be promoted to them. These arguments cannot depend on any parameters.
Returns:	result – When `format="pyarrow"` (the default), returns an appropriate Python object representing the result, either as a plain Python type, or object from `descarteslabs.workflows.result_types`. For other formats, returns raw bytes. Consider using `file` in that case to save the results to a file.
Return type:	Python object or bytes

publish(version, title='', description='', labels=None, tags=None, docstring='', version_labels=None, viz_options=None, client=None)¶

Publish a proxy object as a Workflow with the given version.

If the proxy object depends on any parameters (obj.params is not empty), it’s first internally converted to a Function that takes those parameters (using Function.from_object).

Parameters:	id (Str) – ID for the new Workflow object. This should be of the form `email:workflow_name` and should be globally unique. If this ID is not of the proper format, you will not be able to save the Workflow. version (Str) – The version to be set, tied to the given `obj`. This should adhere to the semantic versioning schema. title (Str, default "") – User-friendly title for the `Workflow`. description (str, default "") – Long-form description of this `Workflow`. Markdown is supported. labels (Dict, optional) – Key-value pair labels to add to the `Workflow`. tags (list, optional) – A list of strings to add as tags to the `Workflow`. docstring (Str, default "") – The docstring for this version. version_labels (Dict, optional) – Key-value pair labels to add to the version. client (`workflows.client.Client`, optional) – Allows you to use a specific client instance with non-default auth and parameters
Returns:	workflow – The saved `Workflow` object. `workflow.id` contains the ID of the new Workflow.
Return type:	Workflow or Function