FeatureCollection¶

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.

Methods:

`add`(features[, fix_geometry])	Add multiple features to an existing `FeatureCollection`.
`copy`(product_id, title, description[, …])	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`.
`count`()	Return the number of features in the product, regardless of what filters have been applied to the `FeatureCollection`.
`create`(product_id, title, description[, …])	Create a vector product in your catalog.
`delete`()	Delete the `FeatureCollection` from the catalog.
`delete_features`()	Apply a filter to a product and delete features that match the filter criteria, taking into account calls to `filter()`.
`export`(key)	Either export the full product, or the result of a filter chain.
`features`()	Iterate through each `Feature` in the `FeatureCollection`, taking into account calls to `filter()` and `limit()`.
`filter`([geometry, properties])	Include only the features matching the given `geometry` and `properties`.
`limit`(limit)	Limit the number of `Feature` yielded in `features()`.
`list`([vector_client])	List all `FeatureCollection` products that you have access to.
`list_exports`()	Get all the export tasks for this product.
`list_uploads`([pending])	Get all the upload tasks for this product.
`refresh`()	Loads the attributes for the `FeatureCollection`.
`replace`([name, title, description, owners, …])	Replaces the attributes of the `FeatureCollection`.
`update`([name, title, description, owners, …])	Updates the attributes of the `FeatureCollection`.
`upload`(file_ref[, max_errors, fix_geometry])	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..
`wait_for_copy`([timeout])	Wait for a copy operation to complete.

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)  