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!

Methods

astype(dtype)

Return Array cast to a specific type.

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

flatten()

Return a contiguous flattened version of Array.

inspect([geoctx, format, file, timeout, client])

Quickly compute this 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([name, description, client])

Publish this proxy object as a Workflow.

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.

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...>
astype(dtype)

Return Array cast to a specific type.

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(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.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.

  • 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

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

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

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(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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 (scenes.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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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.

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.

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.

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.

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(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • 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

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.

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.

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!

Methods

astype(dtype)

Return Array cast to a specific type.

compressed()

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

compute([geoctx, format, destination, file, …])

Compute this 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([geoctx, format, file, timeout, client])

Quickly compute this 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([name, description, client])

Publish this proxy object as a Workflow.

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.

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)
astype(dtype)

Return Array cast to a specific type.

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(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.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.

  • 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

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

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

count(axis=None)[source]

Count unmasked pixels along a given axis.

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

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(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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 (scenes.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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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.

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.

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.

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.

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(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • 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

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.

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.

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([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

flatten()

Return a contiguous flattened version of Array.

inspect([geoctx, format, file, timeout, client])

Quickly compute this 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([name, description, client])

Publish this proxy object as a Workflow.

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.

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(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.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.

  • 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

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

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

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(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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 (scenes.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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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.

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.

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.

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.

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(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • 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

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.

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.

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([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

inspect([geoctx, format, file, timeout, client])

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

publish([name, description, client])

Publish this proxy object as a Workflow.

compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.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.

  • 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

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

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

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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 (scenes.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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • 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

class DType(type_)[source]

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

Should not be worked with directly.

Methods

compute([geoctx, format, destination, file, …])

Compute this proxy object and wait for its result.

inspect([geoctx, format, file, timeout, client])

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

publish([name, description, client])

Publish this proxy object as a Workflow.

compute(geoctx=None, format='pyarrow', destination='download', file=None, timeout=None, block=True, progress_bar=None, client=None, cache=True, **params)

Compute this proxy object and wait for its result.

Parameters
  • geoctx (scenes.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.

  • 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

  • cache (bool, default True) – Whether to use the cache for this job.

  • **params (Proxytype) – Parameters under which to run the computation.

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

inspect(geoctx=None, format='pyarrow', file=None, timeout=30, client=None, **params)

Quickly compute this 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 (scenes.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.

  • timeout (int, optional, default 30) – 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

  • **params (Proxytype) – Parameters under which to run the computation.

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(name='', description='', client=None)

Publish this proxy object as a Workflow.

Parameters
  • name (str, default "") – Name for the new Workflow

  • description (str, default "") – Long-form description of this Workflow. Markdown is supported.

  • 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