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)  
copy(product_id, title, description, owners=None, readers=None, writers=None)[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')  
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  
>>> filtered_cities = filtered_cities.filter(geometry=aoi_geometry)  
>>> filtered_cities = filtered_cities.filter(properties=(p.area_land_meters > 1000))  
>>> 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')  
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')  
>>> count = all_us_cities.count()  
classmethod create(product_id, title, description, owners=None, readers=None, writers=None, vector_client=None)[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')  
delete()[source]

Delete the FeatureCollection from the catalog.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection('my-vector-product-id').delete()  
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')  
>>> fc.filter(geometry=aoi_geometry)  
>>> delete_job = fc.delete_features()  
>>> delete_job.wait_for_completion()  
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  
>>> 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")  
>>> filtered_buildings = buildings.filter(geometry=aoi_geometry)  
>>> task = filtered_buildings.export("my_export")  
>>> if task.is_success: # This waits for the task to complete
...     task.get_file("some_local_file.geojson")  
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")  
>>> features = fc.limit(10).features()  
>>> print(len(features))  
>>> for feature in features:  
...    print(feature)  
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() and in_() methods. 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')  
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  
>>> filtered_cities = filtered_cities.filter(geometry=aoi_geometry)  
>>> filtered_cities = filtered_cities.filter(properties=(p.area_land_meters > 1000))  
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')  
>>> fc = fc.limit(10)  
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()  
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")  
>>> filtered_buildings = buildings.filter(geometry=aoi_geometry)  
>>> task = filtered_buildings.export("my_export")  
>>> exports = filtered_buildings.list_exports()   
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')   
>>> task = fc.upload("/path/to/features.ndjson")    
>>> uploads = fc.list_uploads()   
refresh()[source]

Loads the attributes for the FeatureCollection.

Example

>>> from descarteslabs.vectors import FeatureCollection
>>> FeatureCollection('my-vector-product-id').refresh()  
replace(name=None, title=None, description=None, owners=None, readers=None, writers=None)[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)  
update(name=None, title=None, description=None, owners=None, readers=None, writers=None)[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)  
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')   
>>> task = fc.upload("/path/to/features.ndjson")    
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')  
>>> filtered_cities = all_us_cities.filter(properties=(p.name.like("S%")))  
>>> 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')  
>>> filtered_cities_fc.wait_for_copy(timeout=120)