FeatureCollection

Back to Vectors

class FeatureCollection(id=None, vector_client=None, refresh=True)[source]

A proxy object for accesssing millions of features within a collection having similar access controls, geometries and properties. Such a grouping is named a product and identified by id.

If creating a new FeatureCollection use create() instead.

Features will not be retrieved from the FeatureCollection until features() is called.

id

The unique identifier for this FeatureCollection.

Type:str
name

(Deprecated) Will be removed in future versions.

Type:str
title

A more verbose and expressive name for display purposes.

Type:str
description

Information about the FeatureCollection, why it exists, and what it provides.

Type:str
owners

User, group, or organization IDs that own this FeatureCollection. Defaults to [user:current_user, org:current_org]. The owner can edit, delete, and change access to this FeatureCollection.

Type:list(str)
readers

User, group, or organization IDs that can read this FeatureCollection.

Type:list(str)
writers

User, group, or organization IDs that can edit this FeatureCollection (includes read permission).

Type:list(str)

Note

All owner, reader, and writer IDs must be prefixed with email:, user:, group: or org:. Using org: as an owner will assign those privileges only to administrators for that organization; using org: as a reader or writer assigns those privileges to everyone in that organization.

add(features, fix_geometry='accept')[source]

Add multiple features to an existing FeatureCollection.

Parameters:
  • features (Feature or list(Feature)) – A single feature or list of features to add. Collections of more than 100 features will be batched in groups of 100, but consider using upload() instead.
  • fix_geometry (str) – String specifying how to handle certain problem geometries, including those which do not follow counter-clockwise winding order (which is required by the GeoJSON spec but not many popular tools). Allowed values are reject (reject invalid geometries with an error), fix (correct invalid geometries if possible and use this corrected value when creating the feature), and accept (the default) which will correct the geometry for internal use but retain the original geometry in the results.
Returns:

A copy of the given list of features that includes the id.

Return type:

list(Feature)

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • BadRequestError – Raised when the request is malformed. May also indicate that too many features were included. If more than 100 features were provided, some of these features may have been successfuly inserted while others may not have been inserted.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, Feature
>>> polygon = {
...    'type': 'Polygon',
...    'coordinates': [[[-95, 42],[-93, 42],[-93, 40],[-95, 41],[-95, 42]]]}
>>> features = [Feature(geometry=polygon, properties={}) for _ in range(100)]
>>> FeatureCollection('my-vector-product-id').add(features)  # doctest: +SKIP
copy(**kwargs)[source]

Apply a filter to an existing product and create a new vector product in your catalog from the result, taking into account calls to filter and limit.

A query of some sort must be set, otherwise a BadRequestError will be raised.

Copies occur asynchronously and can take a long time to complete. Features will not be accessible in the new FeatureCollection until the copy completes. Use wait_for_copy() to block until the copy completes.

Parameters:
  • product_id (str) – A unique name for this product. In the created product a namespace consisting of your user id (e.g. “ae60fc891312ggadc94ade8062213b0063335a3c:”) or your organization id (e.g., “yourcompany:”) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique.
  • title (str) – A more verbose and expressive name for display purposes.
  • description (str) – Information about the FeatureCollection, why it exists, and what it provides.
  • owners (list(str), optional) – User, group, or organization IDs that own the newly created FeatureCollection. Defaults to [current user, current org]. The owner can edit and delete this FeatureCollection.
  • readers (list(str), optional) – User, group, or organization IDs that can read the newly created FeatureCollection.
  • writers (list(str), optional) – User, group, or organization IDs that can edit the newly created FeatureCollection (includes read permission).
Returns:

A new FeatureCollection.

Return type:

FeatureCollection

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. no query was specified.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> aoi_geometry = {
...    'type': 'Polygon',
...    'coordinates': [[[-109, 31], [-102, 31], [-102, 37], [-109, 37], [-109, 31]]]}
>>> all_us_cities = FeatureCollection('d1349cc2d8854d998aa6da92dc2bd24')  # doctest: +SKIP
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  # doctest: +SKIP
>>> filtered_cities = filtered_cities.filter(geometry=aoi_geometry)  # doctest: +SKIP
>>> filtered_cities = filtered_cities.filter(properties=(p.area_land_meters > 1000))  # doctest: +SKIP
>>> filtered_cities_fc = filtered_cities.copy(product_id='filtered-cities',
...    title='My Filtered US Cities Vector Collection',
...    description='A collection of cities in the US')  # doctest: +SKIP
count()[source]

Return the number of features in the product, regardless of what filters have been applied to the FeatureCollection.

Returns:

Total number of features in the product.

Return type:

int

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> all_us_cities = FeatureCollection('d1349cc2d8854d998aa6da92dc2bd24')  # doctest: +SKIP
>>> count = all_us_cities.count()  # doctest: +SKIP
classmethod create(**kwargs)[source]

Create a vector product in your catalog.

Parameters:
  • product_id (str) – A unique name for this product. In the created product a namespace consisting of your user id (e.g. “ae60fc891312ggadc94ade8062213b0063335a3c:”) or your organization id (e.g., “yourcompany:”) will be prefixed to this, if it doesn’t already have one, in order to make the id globally unique.
  • title (str) – A more verbose and expressive name for display purposes.
  • description (str) – Information about the FeatureCollection, why it exists, and what it provides.
  • owners (list(str), optional) – User, group, or organization IDs that own the newly created FeatureCollection. Defaults to [current user, current org]. The owner can edit and delete this FeatureCollection.
  • readers (list(str), optional) – User, group, or organization IDs that can read the newly created FeatureCollection.
  • writers (list(str), optional) – User, group, or organization IDs that can edit the newly created FeatureCollection (includes read permission).
Returns:

A new FeatureCollection.

Return type:

FeatureCollection

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the supplied product id is already in use.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection.create(product_id='my-vector-product-id',
...    title='My Vector Collection',
...    description='Just a test')  # doctest: +SKIP
delete()[source]

Delete the FeatureCollection from the catalog.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection('my-vector-product-id').delete()  # doctest: +SKIP
delete_features()[source]

Apply a filter to a product and delete features that match the filter criteria, taking into account calls to filter(). Cannot be used with calls to limit()

A query of some sort must be set, otherwise a BadRequestError will be raised.

Delete jobs occur asynchronously and can take a long time to complete. You can access features() while a delete job is running, but you cannot issue another delete_features() until the current job has completed running. Use DeleteJob.wait_for_completion() to block until the job is done.

Returns:

A new DeleteJob.

Return type:

DeleteJob

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.
  • InvalidQueryException – Raised when a limit was applied to the FeatureCollection.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> aoi_geometry = {
...    'type': 'Polygon',
...    'coordinates': [[[-109, 31], [-102, 31], [-102, 37], [-109, 37], [-109, 31]]]}
>>> fc = FeatureCollection('my-vector-product-id')  # doctest: +SKIP
>>> fc.filter(geometry=aoi_geometry)  # doctest: +SKIP
>>> delete_job = fc.delete_features()  # doctest: +SKIP
>>> delete_job.wait_for_completion()  # doctest: +SKIP
export(key)[source]

Either export the full product, or the result of a filter chain. The exported geojson features will be stored as a data file in Descartes Labs Storage.

The export will occur asynchronously and can take a long time to complete. The data file will not be accessible until the export is complete.

Parameters:

key (str) – The name under which the export will be available in the Storage service. The storage_type will be data. Note that this will overwrite any existing data if the key already exists.

Returns:

The export task.

Return type:

ExportTask

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the query limit is not a number.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> from descarteslabs import Storage  # doctest: +SKIP
>>> aoi_geometry = {
...    "type": "Polygon",
...    "coordinates": [[ # A small area in Washington DC
...        [-77.05501556396483, 38.90946877327506],
...        [-77.0419692993164, 38.90946877327506],
...        [-77.0419692993164, 38.91855139233948],
...        [-77.05501556396483, 38.91855139233948],
...        [-77.05501556396483, 38.90946877327506]
...     ]]
... }
>>> buildings = FeatureCollection(
...     "a35126a241bd022c026e96ab9fe5e0ea23967d08:USBuildingFootprints")  # doctest: +SKIP
>>> filtered_buildings = buildings.filter(geometry=aoi_geometry)  # doctest: +SKIP
>>> task = filtered_buildings.export("my_export")  # doctest: +SKIP
>>> if task.is_success: # This waits for the task to complete
...     task.get_file("some_local_file.geojson")  # doctest: +SKIP
features()[source]

Iterate through each Feature in the FeatureCollection, taking into account calls to filter() and limit().

A query or limit of some sort must be set, otherwise a BadRequestError will be raised.

The length of the returned iterator indicates the full query size.

Returns:

Return type:

Iterator which returns Feature and has a length.

Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the limit is not a number.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> fc = FeatureCollection("a35126a241bd022c026e96ab9fe5e0ea23967d08:USBuildingFootprints")  # doctest: +SKIP
>>> features = fc.limit(10).features()  #doctest: +SKIP
>>> print(len(features))  #doctest: +SKIP
>>> for feature in features:  # doctest: +SKIP
...    print(feature)  # doctest: +SKIP
filter(geometry=None, properties=None)[source]

Include only the features matching the given geometry and properties. Filters are not evaluated until iterating over the FeatureCollection, and can be chained by calling filter multiple times.

Parameters:
  • geometry (GeoJSON-like dict, object with __geo_interface__; optional) – Include features intersecting this geometry. If this FeatureCollection is already filtered by a geometry, the new geometry will override it – they cannot be chained.
  • properties (Expression; optional) – Expression used to filter features by their properties, built from dl.properties. You can construct filter expression using the ==, !=, <, >, <= and >= operators as well as the like() method. You cannot use the boolean keywords and and or because of Python language limitations; instead you can combine filter expressions with & (boolean “and”) and | (boolean “or”). Example (assuming from descarteslabs import properties as p): query_expr=(p.temperature >= 50) & (p.hour_of_day > 18). More complex example: query_expr=(100 > p.temperature >= 50) | ((p.month != 10) & (p.day_of_month > 14)). If you supply a property which doesn’t exist as part of the expression that comparison will evaluate to False.
Returns:

A new FeatureCollection with the given filter.

Return type:

FeatureCollection

Raises:
  • InvalidQueryException – Raised when there is a previously applied geometry filter and a new geometry was provided.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> aoi_geometry = {
...    'type': 'Polygon',
...    'coordinates': [[[-109, 31], [-102, 31], [-102, 37], [-109, 37], [-109, 31]]]}
>>> all_us_cities = FeatureCollection('d1349cc2d8854d998aa6da92dc2bd24')  # doctest: +SKIP
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  # doctest: +SKIP
>>> filtered_cities = filtered_cities.filter(geometry=aoi_geometry)  # doctest: +SKIP
>>> filtered_cities = filtered_cities.filter(properties=(p.area_land_meters > 1000))  # doctest: +SKIP
limit(limit)[source]

Limit the number of Feature yielded in features().

Parameters:limit (int) – The number of rows to limit the result to.
Returns:A new FeatureCollection with the given limit.
Return type:FeatureCollection

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> fc = FeatureCollection('my-vector-product-id')  # doctest: +SKIP
>>> fc = fc.limit(10)  # doctest: +SKIP
classmethod list(vector_client=None)[source]

List all FeatureCollection products that you have access to.

Returns:

A list of all products that you have access to.

Return type:

list(FeatureCollection)

Raises:
  • NotFoundError – Raised if subsequent pages cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection.list()  # doctest: +SKIP
list_exports()[source]

Get all the export tasks for this product.

Returns:

The list of tasks for the product.

Return type:

list(ExportTask)

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> aoi_geometry = {
...    "type": "Polygon",
...    "coordinates": [[ # A small area in Washington DC
...        [-77.05501556396483, 38.90946877327506],
...        [-77.0419692993164, 38.90946877327506],
...        [-77.0419692993164, 38.91855139233948],
...        [-77.05501556396483, 38.91855139233948],
...        [-77.05501556396483, 38.90946877327506]
...     ]]
... }
>>> buildings = FeatureCollection(
...     "a35126a241bd022c026e96ab9fe5e0ea23967d08:USBuildingFootprints")  # doctest: +SKIP
>>> filtered_buildings = buildings.filter(geometry=aoi_geometry)  # doctest: +SKIP
>>> task = filtered_buildings.export("my_export")  # doctest: +SKIP
>>> exports = filtered_buildings.list_exports()   # doctest: +SKIP
list_uploads(pending=True)[source]

Get all the upload tasks for this product.

Parameters:

pending (bool) – If True then include pending/currently running upload tasks in the result, otherwise only include complete upload tasks. Defaults to True.

Returns:

The list of tasks for the product.

Return type:

list(UploadTask)

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, Feature
>>> fc = FeatureCollection('my-vector-product-id')   # doctest: +SKIP
>>> task = fc.upload("/path/to/features.ndjson")    # doctest: +SKIP
>>> uploads = fc.list_uploads()   # doctest: +SKIP
refresh()[source]

Loads the attributes for the FeatureCollection.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection('my-vector-product-id').refresh()  # doctest: +SKIP
replace(**kwargs)[source]

Replaces the attributes of the FeatureCollection.

To change a single attribute, see update().

Parameters:
  • name (str, optional) – (Deprecated) Will be removed in future version.
  • title (str) – (Required) A more verbose name for display purposes.
  • description (str) – (Required) Information about the FeatureCollection, why it exists, and what it provides.
  • owners (list(str), optional) – User, group, or organization IDs that own the FeatureCollection. Defaults to [current user, current org]. The owner can edit and delete this FeatureCollection.
  • readers (list(str), optional) – User, group, or organization IDs that can read the FeatureCollection.
  • writers (list(str), optional) – User, group, or organization IDs that can edit the FeatureCollection (includes read permission).
Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> attributes = dict(title='title',
...    description='description',
...    owners=['email:you@org.com'],
...    readers=['group:readers'],
...    writers=[])
>>> FeatureCollection('my-vector-product-id').replace(**attributes)  # doctest: +SKIP
update(**kwargs)[source]

Updates the attributes of the FeatureCollection.

Parameters:
  • name (str, optional) – (Deprecated) Will be removed in future versions.
  • title (str, optional) – A more verbose and expressive name for display purposes.
  • description (str, optional) – Information about the FeatureCollection, why it exists, and what it provides.
  • owners (list(str), optional) – User, group, or organization IDs that own the FeatureCollection. Defaults to [current user, current org]. The owner can edit and delete this FeatureCollection.
  • readers (list(str), optional) – User, group, or organization IDs that can read the FeatureCollection.
  • writers (list(str), optional) – User, group, or organization IDs that can edit the FeatureCollection (includes read permission).
Raises:
  • BadRequestError – Raised when the request is malformed, e.g. the owners list is missing prefixes.
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> attributes = dict(owners=['email:me@org.com'],
...    readers=['group:trusted'])
>>> FeatureCollection('my-vector-product-id').update(**attributes)  # doctest: +SKIP
upload(file_ref, max_errors=0, fix_geometry='accept')[source]

Asynchronously add features from a file of Newline Delimited JSON features. The file itself will be uploaded synchronously, but loading the features is done asynchronously.

Parameters:
  • file_ref (io.IOBase or str) – An open file object, or a path to the file to upload.
  • max_errors (int) – The maximum number of errors permitted before declaring failure.
  • fix_geometry (str) – String specifying how to handle certain problem geometries, including those which do not follow counter-clockwise winding order (which is required by the GeoJSON spec but not many popular tools). Allowed values are reject (reject invalid geometries with an error), fix (correct invalid geometries if possible and use this corrected value when creating the feature), and accept (the default) which will correct the geometry for internal use but retain the original geometry in the results.
Returns:

The upload task. The details may take time to become available so asking for them before they’re available will block until the details are available.

Return type:

UploadTask

Raises:
  • NotFoundError – Raised if the product cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.

Example

>>> from descarteslabs.vectors import FeatureCollection, Feature
>>> fc = FeatureCollection('my-vector-product-id')   # doctest: +SKIP
>>> task = fc.upload("/path/to/features.ndjson")    # doctest: +SKIP
wait_for_copy(timeout=None)[source]

Wait for a copy operation to complete. Copies occur asynchronously and can take a long time to complete. Features will not be accessible in the FeatureCollection until the copy completes.

If the product was not created using a copy job, a BadRequestError is raised. If the copy job ran, but failed, a FailedJobError is raised. If a timeout is specified and the timeout is reached, a WaitTimeoutError is raised.

Parameters:

timeout (int) – Number of seconds to wait before the wait times out. If not specified, will wait indefinitely.

Raises:
  • FailedJobError – Raised when the copy job fails to complete successfully.
  • NotFoundError – Raised if the product or status cannot be found.
  • RateLimitError – Raised when too many requests have been made within a given time period.
  • ServerError – Raised when a unknown error occurred on the server.
  • WaitTimeoutError – Raised when the copy job doesn’t complete before the timeout is reached.

Example

>>> from descarteslabs.vectors import FeatureCollection, properties as p
>>> aoi_geometry = {
...    'type': 'Polygon',
...    'coordinates': [[[-109, 31], [-102, 31], [-102, 37], [-109, 37], [-109, 31]]]}
>>> all_us_cities = FeatureCollection('d1349cc2d8854d998aa6da92dc2bd24')  # doctest: +SKIP
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  # doctest: +SKIP
>>> filtered_cities_fc = filtered_cities.copy(product_id='filtered-cities',
...    title='My Filtered US Cities Vector Collection',
...    description='A collection of cities in the US')  # doctest: +SKIP
>>> filtered_cities_fc.wait_for_copy(timeout=120)  # doctest: +SKIP