Quickstart¶

Warning

All of these extensions are experimental and subject to breaking changes. They should not be used in production code.

For a quickstart guide see the main SDK Documentation at https://cognite-docs.readthedocs-hosted.com/projects/cognite-sdk-python/en/latest/cognite.html

The currently available extensions for a client ( CogniteClient) instance are:

client.model_hosting = Model Hosting
client.annotations: `Annotations`_ (New Annotations API, see also the API documentation )
client.entity_matching: Extensions for entity matching Create Entity Matching Pipeline
client.match_rules: New multi-field entity matching rules Suggest match rules
client.pnid_parsing: Detect entities in a PNID
client.pnid_object_detection: Detect common objects in a PNID
client.templates: Extensions for Templates
client.geospatial: Geospatial
client.alerts: Alerting
client.vision: Vision

CogniteClient¶

class cognite.experimental.CogniteClient(api_key: str = None, project: str = None, client_name: str = None, base_url: str = None, max_workers: int = None, headers: Dict[str, str] = None, timeout: int = None, token: Union[str, Callable[[], str], None] = None, token_url: Optional[str] = None, token_client_id: Optional[str] = None, token_client_secret: Optional[str] = None, token_scopes: Optional[List[str]] = None, token_custom_args: Optional[Dict[str, str]] = None, disable_pypi_version_check: Optional[bool] = None, debug: bool = False, server=None, **kwargs)¶

Initializes cognite client, with experimental extensions.

Parameters:	api_key () – Your api key. If not given, looks for it in environment variables COGNITE_API_KEY and [PROJECT]_API_KEY server* () – Sets base_url to https://[server].cognitedata.com, e.g. server=greenfield. Other keyword arguments are passed to the base SDK directly.* (*) –

Annotations¶

Retrieve an annotation by id¶

AnnotationsAPI.retrieve(id: int) → cognite.experimental.data_classes.annotations.Annotation¶

Retrieve an annotation by id

Parameters:	id (int) – id of the annotation to be retrieved
Returns:	annotation requested
Return type:	Annotation

Retrieve multiple annotations by id¶

AnnotationsAPI.retrieve_multiple(ids: List[int]) → cognite.experimental.data_classes.annotations.AnnotationList¶

Retrieve annotations by IDs

Parameters:	(List[int]] (ids) – list of IDs to be retrieved
Returns:	list of annotations
Return type:	AnnotationList

List annotation¶

AnnotationsAPI.list(filter: Union[cognite.experimental.data_classes.annotations.AnnotationFilter, Dict[KT, VT]], limit: int = 25) → cognite.experimental.data_classes.annotations.AnnotationList¶

List annotations.

Parameters:	limit (int) – Maximum number of annotations to return. Defaults to 25. filter (AnnotationFilter, optional) – Return annotations with parameter values that matches what is specified. Note that annotated_resource_type and annotated_resource_ids are always required.
Returns:	list of annotations
Return type:	AnnotationList

Create an annotation¶

AnnotationsAPI.create(annotations: Union[cognite.experimental.data_classes.annotations.Annotation, List[cognite.experimental.data_classes.annotations.Annotation]]) → Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationList]¶

Create annotations

Parameters:	annotations (Union[Annotation, List[Annotation]]) – annotation(s) to create
Returns:	created annotation(s)
Return type:	Union[Annotation, AnnotationList]

Suggest an annotation¶

AnnotationsAPI.suggest(annotations: Union[cognite.experimental.data_classes.annotations.Annotation, List[cognite.experimental.data_classes.annotations.Annotation]]) → Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationList]¶

Suggest annotations

Parameters:	annotations (Union[Annotation, List[Annotation]]) – annotation(s) to suggest. They must have status set to “suggested”.
Returns:	suggested annotation(s)
Return type:	Union[Annotation, AnnotationList]

Update annotations¶

AnnotationsAPI.update(item: Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationUpdate, List[Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationUpdate]]]) → Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationList]¶

Update annotations

Parameters:	id (Union[int, List[int]]) – ID or list of IDs to be deleted

Delete annotations¶

AnnotationsAPI.delete(id: Union[int, List[int]]) → None¶

Delete annotations

Parameters:	id (Union[int, List[int]]) – ID or list of IDs to be deleted

Data classes¶

class cognite.experimental.data_classes.annotations.Annotation(annotation_type: str, data: dict, status: str, creating_app: str, creating_app_version: str, creating_user: Optional[str], annotated_resource_type: str, annotated_resource_id: Optional[int] = None, annotated_resource_external_id: Optional[str] = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

Representation of an annotation in CDF.

Parameters:

annotation_type (str) – The type of the annotation. This uniquely decides what the structure of the ‘data’ block will be.
data (dict) – The annotation information. The format of this object is decided by and validated against the ‘annotation_type’ attribute.
status (str) – The status of the annotation, e.g. “suggested”, “approved”, “rejected”.
annotated_resource_type (str) – Type name of the CDF resource that is annotated, e.g. “file”.
annotated_resource_id (int, optional) – The internal ID of the annotated resource.
creating_app (str) – The name of the app from which this annotation was created.
creating_app_version (str) – The version of the app that created this annotation. Must be a valid semantic versioning (SemVer) string.
creating_user – (str, optional): A username, or email, or name. This is not checked nor enforced. If the value is None, it means the annotation was created by a service.
id (int, optional) – A server-generated id for the object. Read-only.
created_time (int, optional) – Time when this annotation was created in CDF. The time is measured in milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds. Read-only.
last_updated_time (int, optional) – Time when this annotation was last updated in CDF. The time is measured in milliseconds since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), minus leap seconds. Read-only.
cognite_client (CogniteClient, optional) – The client to associate with this object. Read-only.

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

class cognite.experimental.data_classes.annotations.AnnotationFilter(annotated_resource_type: str, annotated_resource_ids: List[Dict[str, Any]], status: Optional[str] = None, creating_user: Optional[str] = '', creating_app: Optional[str] = None, creating_app_version: Optional[str] = None, annotation_type: Optional[str] = None, data: Optional[Dict[str, Any]] = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on annotations with various criteria

Parameters:

annotated_resource_type (str) – The type of the CDF resource that is annotated, e.g. “file”.
annotated_resource_ids (List[Dict[str, Any]]) – List of ids and external ids of the annotated CDF resources to filter in. Example format: [{“id”: 1234}, {“external_id”: “ext_1234”}]. Must contain at least one item.
status (str, optional) – Status of annotations to filter for, e.g. “suggested”, “approved”, “rejected”.
creating_user (str, optional) – Name of the user who created the annotations to filter for. Can be set explicitly to “None” to filter for annotations created by a service.
creating_app (str, optional) – Name of the app from which the annotations to filter for where created.
creating_app_version (str, optional) – Version of the app from which the annotations to filter for were created.
annotation_type (str, optional) – Type name of the annotations.
data (Dict[str, Any], optional) – The annotation data to filter by. Example format: {“label”: “cat”, “confidence”: 0.9}

dump(camel_case: bool = False)¶

Dump the instance into a json serializable Python data type.

Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

class cognite.experimental.data_classes.annotations.AnnotationList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.annotations.AnnotationUpdate(id: int)¶

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes applied to annotation

Parameters:	id (int) – A server-generated ID for the object.

Model Hosting¶

Models¶

Retrieve model by name¶

List models¶

Create model¶

Update model¶

Deprecate model¶

Delete model¶

Perform online prediction¶

Model Versions¶

Retrieve model version by name¶

List model versions¶

Create and deploy model version¶

Create model version without deploying¶

Deploy awaiting model version¶

Update model version¶

Deprecate model version¶

Delete model version¶

Model Version Artifacts¶

List artifacts for a model version¶

Upload an artifact from a file to a model version awating deployment¶

Upload artifacts from a directory to a model version awating deployment¶

Download an artifact for a model version¶

Schedules¶

Retrieve schedule by name¶

List schedules¶

Create Schedule¶

Deprecate Schedule¶

Delete Schedule¶

Retrieve schedule logs¶

Source Packages¶

Retrieve source package by id¶

List source packages¶

Upload a source package¶

Build and upload a source package¶

Deprecate source package¶

Delete source package¶

Download source package code¶

Delete source package code¶

Data classes¶

class cognite.experimental.data_classes.model_hosting.models.Model(name: str = None, description: str = None, created_time: int = None, metadata: Dict[KT, VT] = None, is_deprecated: bool = None, active_version_name: str = None, input_fields: List[T] = None, output_fields: List[T] = None, webhook_url: str = None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a Model in the model hosting environment.

Parameters:

name (str) – Name of the model.
description (str) – Description of the model.
created_time (int) – Created time in UNIX.
metadata (Dict) – User-defined metadata about the model.
is_deprecated (bool) – Whether or not the model is deprecated.
active_version_name (str) – The name of the active version on this model.
input_fields (List) – A list of input fields this model takes.
output_fields (List) – A list of output fields this model defines.
webhook_url (str) – A url used to catch webhooks which are reported upon failing scheduled predictions.
cognite_client (CogniteClient) – An optional CogniteClient to associate with this data class.

class cognite.experimental.data_classes.model_hosting.models.ModelList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.model_hosting.versions.ModelArtifactList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.model_hosting.versions.ModelVersion(name: str = None, is_deprecated: bool = None, training_details: Dict[KT, VT] = None, error_msg: str = None, model_name: str = None, created_time: int = None, metadata: Dict[KT, VT] = None, source_package_id: int = None, status: str = None, description: str = None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a Model version in the model hosting environment.

Parameters:

name (str) – Name of the model version.
is_deprecated (bool) – Whether or not the model version is deprecated.
training_details (Dict) – The training details for this model version. None if the associated source package does not define a .train() method.
error_msg (str) – The error message produced when trying to deploy the model version.
model_name (str) – The name of the model associated with this version.
created_time (int) – Created time in UNIX.
metadata (Dict) – User-defined metadata about the model.
source_package_id (int) – The id of the source package associated with this version.
status (str) – The current status of the model version deployment.
description (str) – Description of the model.
cognite_client (CogniteClient) – An optional CogniteClient to associate with this data class.

class cognite.experimental.data_classes.model_hosting.versions.ModelVersionList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.model_hosting.versions.ModelVersionLog(prediction_logs: List[T] = None, training_logs: List[T] = None)¶

Bases: cognite.client.data_classes._base.CogniteResponse

An object containing the logs for a model version.

Parameters:	prediction_logs (List) – A list of log entries for the prediction routine training_logs (List) – A list of log entries for the training routine

class cognite.experimental.data_classes.model_hosting.schedules.LogEntry(timestamp: int = None, scheduled_execution_time: int = None, message: str = None)¶

Bases: cognite.client.data_classes._base.CogniteResponse

An object containing a log entry for a schedule.

Parameters:	timestamp (int) – The time the log entry was recorded. scheduled_execution_time (int) – The time the prediction was scheduled to run. message (str) – The log message.

class cognite.experimental.data_classes.model_hosting.schedules.Schedule(name: str = None, model_name: str = None, description: str = None, data_spec: Union[ScheduleDataSpec, Dict[KT, VT]] = None, is_deprecated: bool = None, created_time: int = None, metadata: Dict[KT, VT] = None, args: Dict[KT, VT] = None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a Schedule in the model hosting environment.

Parameters:

name (str) – Name of the schedule.
model_name (str) – The name of the model associated with this schedule.
description (str) – Description of the schedule.
data_spec (Union[Dict, ScheduleDataSpec]) – The data spec for the schedule.
is_deprecated (bool) – Whether or not the model version is deprecated.
created_time (int) – Created time in UNIX.
metadata (Dict) – User-defined metadata about the model.
args (Dict) – Additional arguments passed to the predict routine.
cognite_client (CogniteClient) – An optional CogniteClient to associate with this data class.

class cognite.experimental.data_classes.model_hosting.schedules.ScheduleList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.model_hosting.schedules.ScheduleLog(failed: List[T] = None, completed: List[T] = None)¶

Bases: cognite.client.data_classes._base.CogniteResponse

An object containing the logs for a schedule.

Parameters:	failed (List[LogEntry]) – A list of log entries for failed executions. completed (List[LogEntry]) – A list of log entries for succesful executions.

class cognite.experimental.data_classes.model_hosting.source_packages.CreateSourcePackageResponse(id: int = None, upload_url: str = None)¶

Bases: cognite.client.data_classes._base.CogniteResponse

The response returned from the API when creating a new source package.

Parameters:	id (int) – The id of the source package upload_url (str) – The url to upload the source package distribution to.

class cognite.experimental.data_classes.model_hosting.source_packages.SourcePackage(id: int = None, name: str = None, description: str = None, is_deprecated: bool = None, package_name: str = None, is_uploaded: bool = None, available_operations: List[T] = None, created_time: int = None, runtime_version: str = None, metadata: Dict[KT, VT] = None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a source package in the model hosting environment.

Parameters:

id (int) – Id of the source package.
name (str) – Name of the source package.
description (str) – Description of the schedule.
is_deprecated (bool) – Whether or not the source package is deprecated.
package_name (str) – The name of the package containing the model.py file.
is_uploaded (bool) – Whether or not the source package has been uploaded
available_operations (List[str]) – The available operations on this source package. Can be any of [PREDICT, TRAIN].
created_time (int) – Created time in UNIX.
runtime_version (str) – The runtime version this source package should be deployed with. Can be any of [“0.1”]
metadata (Dict) – User-defined metadata about the source package.
cognite_client (CogniteClient) – An optional CogniteClient to associate with this data class.

class cognite.experimental.data_classes.model_hosting.source_packages.SourcePackageList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

Contextualization¶

These APIs will return as soon as possible, defering a blocking wait until the last moment. Nevertheless, they can block for a long time awaiting results. For examples of using this api, see: https://github.com/cognitedata/cognite-sdk-python-experimental/blob/master/CONTEXTUALIZATION.md

Entity Matching Methods¶

See the main SDK documentation for most other methods.

Fit Entity Matching Model¶

EntityMatchingAPI.fit(sources: List[Union[Dict[KT, VT], cognite.client.data_classes._base.CogniteResource]], targets: List[Union[Dict[KT, VT], cognite.client.data_classes._base.CogniteResource]], true_matches: List[Union[Dict[KT, VT], Tuple[Union[int, str], Union[int, str]]]] = None, match_fields: Union[Dict[KT, VT], List[Tuple[str, str]]] = None, feature_type: str = None, classifier: str = None, ignore_missing_fields: bool = False, name: str = None, description: str = None, external_id: str = None, replacements: List[Dict[KT, VT]] = None) → cognite.client.data_classes.contextualization.EntityMatchingModel¶

Fit entity matching model. Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all capabilities in the project, are able to access the data sent to this endpoint.

Parameters:	sources – entities to match from, should have an ‘id’ field. Tolerant to passing more than is needed or used (e.g. json dump of time series list). Metadata fields are automatically flattened to “metadata.key” entries, such that they can be used in match_fields. targets – entities to match to, should have an ‘id’ field. Tolerant to passing more than is needed or used. true_matches – Known valid matches given as a list of dicts with keys ‘sourceId’, ‘sourceExternalId’, ‘sourceId’, ‘sourceExternalId’). If omitted, uses an unsupervised model. A tuple can be used instead of the dictionary for convenience, interpreted as id/externalId based on type. match_fields – List of (from,to) keys to use in matching. Default in the API is [(‘name’,’name’)]. Also accepts {“source”: .., “target”: ..}. feature_type (str) – feature type that defines the combination of features used, see API docs for details. classifier (str) – classifier used in training. ignore_missing_fields (bool) – whether missing data in match_fields should return error or be filled in with an empty string. name (str) – Optional user-defined name of model. description (str) – Optional user-defined description of model. external_id (str) – Optional external id. Must be unique within the project. replacements (dict) – Optional list of strings to replace in fields. Each entry has the format {“field”: field, “string”: from, “replacement”: to}, where field can be “*” for all fields.
Returns:	Resulting queued model.
Return type:	EntityMatchingModel

Suggest Match Fields¶

EntityMatchingAPI.suggest_fields(sources: List[Union[Dict[KT, VT], cognite.client.data_classes._base.CogniteResource]], targets: List[Union[Dict[KT, VT], cognite.client.data_classes._base.CogniteResource]], score_threshold: float = 0.5) → List[Dict[KT, VT]]¶

Get suggestions for match fields in entity matching

Parameters:	sources – a sample of typical sources, best used on existing matches. No more than 10,000. targets – a sample of typical targets, best used on existing matches. No more than 10,000. score_threshold – only return suggestions above this threshold.
Returns:	results sorted by score, each entry having ‘source’ and ‘target’ field along with a score and exampleTokens which match
Return type:	List[Dict]

Create Entity Matching Pipeline¶

EntityMatchingPipelinesAPI.create(pipeline: cognite.experimental.data_classes.contextualization.EntityMatchingPipeline) → cognite.experimental.data_classes.contextualization.EntityMatchingPipeline¶

Create an Entity Matching Pipeline.

Parameters:	pipeline (EntityMatchingPipeline) – Pipeline to create.
Returns:	created pipeline.
Return type:	EntityMatchingPipeline

Retrieve Entity Matching Pipelines¶

EntityMatchingPipelinesAPI.retrieve(id: Optional[int] = None, external_id: Optional[str] = None) → Optional[cognite.experimental.data_classes.contextualization.EntityMatchingPipeline]¶

Retrieve pipeline

Parameters:	id – id of the pipeline to retrieve. external_id – external id of the pipeline to retrieve.
Returns:	Pipeline requested.
Return type:	EntityMatchingPipeline

EntityMatchingPipelinesAPI.retrieve_multiple(ids: Optional[List[int]] = None, external_ids: Optional[List[str]] = None) → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineList¶

Retrieve models

Parameters:	ids (Union[int, List[int]) – List of ids of the pipelines to retrieve. external_ids (Union[str, List[str]]) – List of external ids of the pipelines to retrieve.
Returns:	Pipelines requested.
Return type:	EntityMatchingPipelineList

EntityMatchingPipelinesAPI.list(limit=100) → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineList¶

List entity matching pipelines

Parameters:	limit (int, optional) – Maximum number of items to return. Defaults to 100. Set to None to return all items.
Returns:	List of pipelines.
Return type:	EntityMatchingPipelineList

Run Entity Matching Pipeline¶

EntityMatchingPipelinesAPI.run(id: int = None, external_id: str = None) → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun¶

Run pipeline

Parameters:	id – id of the pipeline to run. external_id – external id of the pipeline to run.
Returns:	object which can be used to wait for and retrieve results.
Return type:	EntityMatchingPipelineRun

Delete Entity Matching Pipeline¶

EntityMatchingPipelinesAPI.delete(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → None¶

Delete pipelines

Parameters:	id (Union[int, List[int]) – Id or list of ids external_id (Union[str, List[str]]) – External ID or list of external ids

Retrieve Entity Matching Pipelines Run¶

EntityMatchingPipelineRunsAPI.retrieve(id: int) → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun¶

Retrieve pipeline run

Parameters:	id – id of the pipeline run to retrieve.
Returns:	object which can be used to wait for and retrieve results.
Return type:	EntityMatchingPipelineRun

EntityMatchingPipelineRunsAPI.retrieve_latest(id: Union[int, List[int]] = None, external_id: Union[str, List[str]] = None) → Union[cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun, cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRunList]¶

List latest pipeline run for pipelines. Note that pipelines without a run are not returned, so output may not align with input.

Parameters:	id – id or list of ids of the pipelines to retrieve the latest run for. external_id – external id or list of external ids of the pipelines to retrieve the latest run for.
Returns:	list of latest pipeline runs, or a single object if a single id was given and the run was found
Return type:	Union[EntityMatchingPipelineRun,EntityMatchingPipelineRunList]

EntityMatchingPipelineRunsAPI.list(id=None, external_id=None, limit=100) → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRunList¶

List pipeline runs

Parameters:	id – id of the pipeline to retrieve runs for. external_id – external id of the pipeline to retrieve runs for. limit (int, optional) – Maximum number of items to return. Defaults to 100. Set to -1, float(“inf”) or None to return all items.
Returns:	list of pipeline runs
Return type:	EntityMatchingPipelineRunList

Suggest match rules¶

MatchRulesAPI.suggest(sources: List[dict], targets: List[dict], matches: List[dict]) → cognite.experimental.data_classes.contextualization.MatchRulesSuggestJob¶

Suggest match rules with priorities based on existing matches between source and target entities.

Parameters:	sources (List[dict]) – List of dict representation of source entities to suggest rules for. targets (List[dict]) – List of dict representation of target entities to suggest rules for. matches (list[dict]) – List of matches in terms of source_id or source_external_id and similar for target.
Returns:	Resulting queued job. Note that .rules property of this job will block waiting for results.
Return type:	MatchRulesSuggestJob

Apply match rules¶

MatchRulesAPI.apply(sources: List[dict], targets: List[dict], rules: Union[List[dict], cognite.experimental.data_classes.contextualization.EntityMatchingMatchRuleList]) → cognite.experimental.data_classes.contextualization.MatchRulesApplyJob¶

Apply match rules with priorities to match source entities with target entities.

Parameters:	sources (List[dict]) – List of source entities in json format. targets (List[dict]) – List of target entities in json format. rules (Union[List[dict], EntityMatchingMatchruleList]) – List of match rules with priorities to apply to the entities
Returns:	Job, calling .rules waits for completion.
Return type:	MatchRulesApplyJob

Detect entities in a PNID¶

PNIDParsingAPI.detect(entities: List[Union[str, dict, cognite.client.data_classes._base.CogniteResource]], search_field: str = 'name', name_mapping: Dict[str, str] = None, partial_match: bool = False, min_tokens: int = 1, file_id: int = None, file_external_id: str = None) → cognite.experimental.data_classes.contextualization.PNIDDetectResults¶

Detect entities in a PNID. The results are not written to CDF. Note: All users on this CDF subscription with assets read-all and files read-all capabilities in the project, are able to access the data sent to this endpoint.

Parameters:	file_id (int) – ID of the file, should already be uploaded in the same tenant. file_external_id – File external id entities (List[Union[str, dict]]) – List of entities to detect search_field (str) – If entities is a list of dictionaries, this is the key to the values to detect in the PnId name_mapping (Dict[str,str]) – Optional mapping between entity names and their synonyms in the P&ID. Used if the P&ID contains names on a different form than the entity list (e.g a substring only). The response will contain names as given in the entity list. partial_match (bool) – Allow for a partial match (e.g. missing prefix). min_tokens (int) – Minimal number of tokens a match must be based on
Returns:	Resulting queued job. Note that .result property of this job will block waiting for results.
Return type:	PNIDDetectResults

Extract tags from P&ID based on pattern¶

PNIDParsingAPI.extract_pattern(patterns: List[str], file_id: int = None, file_external_id: str = None) → cognite.experimental.data_classes.contextualization.PNIDDetectResults¶

Extract tags from P&ID based on pattern. The results are not written to CDF.

Parameters:	file_id (int) – ID of the file, should already be uploaded in the same tenant. patterns (list) – List of regular expression patterns to look for in the P&ID. See API docs for details.
Returns:	Resulting queued job. Note that .result property of this job will block waiting for results.
Return type:	PNIDDetectResults

Convert a P&ID to an interactive SVG where the provided annotations are highlighted¶

PNIDParsingAPI.convert(items: List[Dict[KT, VT]], grayscale: bool = None, file_id: int = None, file_external_id: str = None) → cognite.experimental.data_classes.contextualization.PNIDConvertResults¶

Convert a P&ID to an interactive SVG where the provided annotations are highlighted. The resulting SVG is not uploaded to CDF.

Parameters:	file_id (int) – ID of the file, should already be uploaded in the same tenant. items (List[Dict]) – List of entity annotations for entities detected in the P&ID. For instance the resulting items from calling the detect or extract_pattern-method. grayscale (bool, optional) – Return the SVG version in grayscale colors only (reduces the file size). Defaults to None.
Returns:	Resulting queued job. Note that .result property of this job will block waiting for results.
Return type:	PNIDConvertResults

Retrieve caches OCR results¶

PNIDParsingAPI.ocr(file_id: int) → cognite.experimental.data_classes.contextualization.PNIDDetectionPageList¶

Retrieve the cached raw OCR result. Only works when detect (or the vision ocr service) has already been used on the file.

Parameters:	file_id (int) – ID of the file.
Returns:	Cached OCR results, one list per page.
Return type:	PNIDDetectionPageList (effectively List[PNIDDetectionList])

Detect common objects in a PNID¶

PNIDObjectDetectionAPI.find_objects(file_id: int) → cognite.client.data_classes.contextualization.ContextualizationJob¶

Find objects in a PnID

Parameters:	file_id (int) – ID of the file, should already be uploaded in the same tenant.
Returns:	Resulting queued job. Note that .results property of this job will block waiting for results.
Return type:	ContextualizationJob

Contextualization Data Classes¶

class cognite.experimental.data_classes.contextualization.ContextualizationJobType¶

Bases: enum.Enum

An enumeration.

PNID_PARSER = 'pnid_parsing'¶

VISION = 'vision'¶

class cognite.experimental.data_classes.contextualization.EntityMatchingMatch(source=None, target=None, score=None, match_type=None, match_fields=None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case=False)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingMatchList(resources: List[Any], cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResourceList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

dump(camel_case: bool = False) → List[Dict[str, Any]]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A list of dicts representing the instance.
Return type:	List[Dict[str, Any]]

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]¶

Get an item from this list by id or exernal_id.

Parameters:	id (int) – The id of the item to get. external_id (str) – The external_id of the item to get.
Returns:	The requested item
Return type:	Optional[CogniteResource]

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

to_pandas(camel_case=False)¶

Convert the instance into a pandas DataFrame.

Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingMatchRule(conditions=None, extractors=None, priority=None, matches=None, flags=None, conflicts=None, overlaps=None, number_of_matches=None, num_conflicts=None, num_overlaps=None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingMatchRuleList(resources: List[Any], cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResourceList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

dump(camel_case: bool = False) → List[Dict[str, Any]]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A list of dicts representing the instance.
Return type:	List[Dict[str, Any]]

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]¶

Get an item from this list by id or exernal_id.

Parameters:	id (int) – The id of the item to get. external_id (str) – The external_id of the item to get.
Returns:	The requested item
Return type:	Optional[CogniteResource]

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

to_pandas(camel_case=True) → pandas.DataFrame¶

Convert the instance into a pandas DataFrame.

Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingPipeline(id: int = None, external_id: str = None, name: str = None, description: str = None, model_parameters: Dict[KT, VT] = None, sources: Dict[KT, VT] = None, targets: Dict[KT, VT] = None, true_matches: List[T] = None, rejected_matches: List[T] = None, confirmed_matches: List[T] = None, use_existing_matches: bool = None, replacements: List[Dict[KT, VT]] = None, score_threshold: float = None, rules: List[T] = None, status=None, error_message=None, created_time=None, start_time=None, status_time=None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

Rerunnable entity matching pipeline, used to continuously iterate and improve.: Entity matching pipelines supports expert knowledge (confirmed and/or rejected matches), regex rules (match rules) and entity matching models. The fields below can be filled when creating a pipeline. Other fields should be left empty, and return status information on successful creation and retrieval.

Parameters:

external_id (str) – External Id provided by user. Should be unique within a given project/resource combination.
name (str) – User defined name of the pipeline.
description (str) – User defined description of the pipeline.
model_parameters – A dictionary with fields match_fields, feature_type, classifier, as in the fit method for entity matching.
targets (sources,) – a dictionary of the format {‘resource’: …, ‘dataSetIds’: [{‘id’:…},{‘externalId’:…}]}
confirmed_matches – user-confirmed certain matches which will be used to override any other results.
rejected_matches – user-confirmed wrong results which will be used to blank output for a match result if it is one of these.
use_existing_matches – If set, uses existing matches on resources as additional training data when the entity matching model is fit.
replacements – Expects a list of {‘field’:.., ‘string’:.. ,’replacement’: ..} which will be used to replace substrings in a field with a synonym, such as “Pressure Transmitter” -> “PT”, or “Æ” -> AE. Field can be ‘*’ for all.
rules – list of matching rules (either old or new format)

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

latest_run() → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun¶: Retrieve the latest run

run() → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun¶: Runs the pipeline and returns a run job

runs() → cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRunList¶: Retrieve the list of runs

to_pandas(camel_case=False)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingPipelineList(resources: List[Any], cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResourceList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

dump(camel_case: bool = False) → List[Dict[str, Any]]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A list of dicts representing the instance.
Return type:	List[Dict[str, Any]]

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]¶

Get an item from this list by id or exernal_id.

Parameters:	id (int) – The id of the item to get. external_id (str) – The external_id of the item to get.
Returns:	The requested item
Return type:	Optional[CogniteResource]

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

to_pandas(camel_case=True) → pandas.DataFrame¶

Convert the instance into a pandas DataFrame.

Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRun(pipeline_id=None, **kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

errors¶: Returns list of error messages encountered while running. Depends on .result and may block

generated_rules¶: List of suggested new match rules. Depends on .result and may block

matches¶: List of matches. Depends on .result and may block

pipeline¶: Retrieve the pipeline that owns this run, may call the API or use a cached value

result¶: Waits for the job to finish and returns the results.

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.contextualization.EntityMatchingPipelineRunList(resources: List[Any], cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResourceList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

dump(camel_case: bool = False) → List[Dict[str, Any]]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A list of dicts representing the instance.
Return type:	List[Dict[str, Any]]

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]¶

Get an item from this list by id or exernal_id.

Parameters:	id (int) – The id of the item to get. external_id (str) – The external_id of the item to get.
Returns:	The requested item
Return type:	Optional[CogniteResource]

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

to_pandas(camel_case=True) → pandas.DataFrame¶

Convert the instance into a pandas DataFrame.

Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.EntityMatchingPipelineUpdate(id: int = None, external_id: str = None)¶

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes applied to entity matching pipeline

Parameters:	id (int) – A server-generated ID for the object. external_id (str) – The external ID provided by the client. Must be unique for the resource type.

confirmed_matches¶

description¶

dump()¶

Dump the instance into a json serializable Python data type.

Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

model_parameters¶

name¶

rejected_matches¶

replacements¶

rules¶

score_threshold¶

sources¶

targets¶

true_matches¶

class cognite.experimental.data_classes.contextualization.MatchRulesApplyJob(**kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

result¶: Waits for the job to finish and returns the results.

rules¶: Depends on .result and may block

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.contextualization.MatchRulesSuggestJob(**kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

result¶: Waits for the job to finish and returns the results.

rules¶: Depends on .result and may block

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.contextualization.PNIDConvertResults(job_id=None, model_id=None, status=None, error_message=None, created_time=None, start_time=None, status_time=None, status_path=None, cognite_client=None, **kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

image¶: Returns the result as an SVG image for output in jupyter

result¶: Waits for the job to finish and returns the results.

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.contextualization.PNIDDetectResults(*args, **kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

convert(ocr=False) → cognite.experimental.data_classes.contextualization.PNIDConvertResults¶

Convert a P&ID to an interactive SVG where the provided annotations are highlighted

Parameters:	ocr (bool) – show raw OCR results, rather than detected entities.

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

file_external_id¶

file_id¶

image¶: Returns the file as an image with bounding boxes for matches

matches¶: Returns detected items

ocr() → cognite.experimental.data_classes.contextualization.PNIDDetectionPageList¶: Retrieve raw OCR results, for example, to visualize

result¶: Waits for the job to finish and returns the results.

to_pandas(camel_case: bool = False)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.contextualization.PNIDDetection(text=None, type=None, confidence=None, bounding_box=None, entities=None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.PNIDDetectionList(resources: List[Any], cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResourceList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

dump(camel_case: bool = False) → List[Dict[str, Any]]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A list of dicts representing the instance.
Return type:	List[Dict[str, Any]]

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

get(id: int = None, external_id: str = None) → Optional[cognite.client.data_classes._base.CogniteResource]¶

Get an item from this list by id or exernal_id.

Parameters:	id (int) – The id of the item to get. external_id (str) – The external_id of the item to get.
Returns:	The requested item
Return type:	Optional[CogniteResource]

image_with_bounding_boxes(file_id: int) → PIL.Image¶: returns an image with bounding boxes on top of the pdf specified by file_id

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

to_pandas(camel_case=True) → pandas.DataFrame¶

Convert the instance into a pandas DataFrame.

Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.contextualization.PNIDDetectionPageList(data, file_id)¶

Bases: collections.UserList

append(item)¶: S.append(value) – append value to the end of the sequence

clear() → None -- remove all items from S¶

copy()¶

count(value) → integer -- return number of occurrences of value¶

extend(other)¶: S.extend(iterable) – extend sequence by appending elements from the iterable

image¶: Returns the file as an image with bounding boxes for detected items

index(value[, start[, stop]]) → integer -- return first index of value.¶

Raises ValueError if the value is not present.

Supporting start and stop arguments is optional, but recommended.

insert(i, item)¶: S.insert(index, value) – insert value before index

pop([index]) → item -- remove and return item at index (default last).¶: Raise IndexError if list is empty or index is out of range.

remove(item)¶: S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()¶: S.reverse() – reverse IN PLACE

sort(*args, **kwds)¶

Vision¶

The Vision API enable extraction of information from imagery data based on their visual content. For example, you can can extract features such as text, asset tags or industrial objects from images using this service.

Quickstart

Start an asynchronous job to extract information from image files stored in CDF:

>>> from cognite.experimental import CogniteClient
>>> from cognite.experimental.data_classes.vision import Feature
>>> c = CogniteClient()
>>> extract_job = c.vision.extract(
...     features=[Feature.ASSET_TAG_DETECTION, Feature.PEOPLE_DETECTION],
...     file_ids=[1, 2],
... )

The returned job object, extract_job, can be used to retrieve the status of the job and the prediction results once the job is completed.

Wait for job completion and get the parsed results:

>>> extract_job.wait_for_completion()
>>> for item in extract_job.items:
...     predictions = item.predictions
...     # do something with the predictions

Save the prediction results in CDF as Annotations:

>>> extract_job.save_predictions()

Note

Prediction results are stored in CDF as Annotations using the images.* annotation types. In particular, text detections are stored as images.TextRegion, asset tag detections are stored as images.AssetLink, while other detections are stored as images.ObjectDetection.

Tweaking the parameters of a feature extractor:

>>> from cognite.experimental.data_classes.vision import FeatureParameters, TextDetectionParameters
>>> extract_job = c.vision.extract(
...     features=Feature.TEXT_DETECTION,
...     file_ids=[1, 2],
...     parameters=FeatureParameters(TextDetectionParameters(threshold=0.9))
... )

Extract¶

VisionAPI.extract(features: Union[cognite.experimental.data_classes.vision.Feature, List[cognite.experimental.data_classes.vision.Feature]], file_ids: Optional[List[int]] = None, file_external_ids: Optional[List[str]] = None, parameters: Optional[cognite.experimental.data_classes.vision.FeatureParameters] = None) → cognite.experimental.data_classes.vision.VisionExtractJob¶

Start an asynchronous job to extract features from image files.

Parameters:	features (Union[Feature, List[Feature]]) – The feature(s) to extract from the provided image files. file_ids (List[int]) – IDs of the image files to analyze. The images must already be uploaded in the same CDF project. file_external_ids (List[str]) – The external file ids of the image files to analyze.
Returns:	Resulting queued job, which can be used to retrieve the status of the job or the prediction results if the job is finished. Note that .result property of this job will wait for the job to finish and returns the results.
Return type:	VisionExtractJob

Examples

Start a job, wait for completion and then get the parsed results:

>>> from cognite.experimental import CogniteClient
>>> from cognite.experimental.data_classes.vision import Feature
>>> c = CogniteClient()
>>> extract_job = c.vision.extract(features=Feature.ASSET_TAG_DETECTION, file_ids=[1])
>>> extract_job.wait_for_completion()
>>> for item in extract_job.items:
...     predictions = item.predictions
...     # do something with the predictions
>>> # Save predictions in CDF using Annotations API:
>>> extract_job.save_predictions()

Get vision extract job¶

VisionAPI.get_extract_job(job_id: int) → cognite.experimental.data_classes.vision.VisionExtractJob¶

Retrieve an existing extract job by ID.

Parameters:	job_id (InternalId) – ID of an existing feature extraction job.
Returns:	Vision extract job, which can be used to retrieve the status of the job or the prediction results if the job is finished. Note that .result property of this job will wait for the job to finish and returns the results.
Return type:	VisionExtractJob

Examples

Retrieve a vision extract job by ID:

>>> from cognite.experimental import CogniteClient
>>> c = CogniteClient()
>>> extract_job = c.vision.get_extract_job(job_id=1)
>>> extract_job.wait_for_completion()
>>> for item in extract_job.items:
...     predictions = item.predictions
...     # do something with the predictions

Data classes¶

Vision data classes¶

class cognite.experimental.data_classes.vision.AllOfFileId(file_id: int, file_external_id: Union[str, NoneType] = None)¶

Bases: cognite.experimental.data_classes.vision.InternalFileId

file_external_id = None¶

class cognite.experimental.data_classes.vision.AssetTagDetectionParameters(threshold: Union[float, NoneType] = None, partial_match: Union[bool, NoneType] = None, asset_subtree_ids: Union[List[int], NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource, cognite.experimental.data_classes.vision.ThresholdParameter

asset_subtree_ids = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

partial_match = None¶

threshold = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.CreatedDetectAssetsInFilesJob(status: cognite.client.data_classes.contextualization.JobStatus, created_time: int, status_time: int, job_id: int, items: Optional[List[cognite.experimental.data_classes.vision.AllOfFileId]] = None, use_cache: Optional[bool] = None, partial_match: Optional[bool] = None, asset_subtree_ids: Optional[List[int]] = None, start_time: Optional[int] = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.vision.DetectAssetsInFilesJob(status: cognite.client.data_classes.contextualization.JobStatus, created_time: int, status_time: int, job_id: int, use_cache: Optional[bool] = None, partial_match: Optional[bool] = None, asset_subtree_ids: Optional[List[int]] = None, start_time: Optional[int] = None, items: Optional[List[cognite.experimental.data_classes.vision.SuccessfulAssetDetectionInFiles]] = None, failed_items: Optional[List[cognite.experimental.data_classes.vision.FailedAssetDetectionInFiles]] = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.vision.ExternalFileId(file_external_id: str)¶: Bases: object

class cognite.experimental.data_classes.vision.FailedAssetDetectionInFiles(error_message: str, items: List[cognite.experimental.data_classes.vision.AllOfFileId])¶: Bases: object

class cognite.experimental.data_classes.vision.Feature¶

Bases: str, enum.Enum

An enumeration.

ASSET_TAG_DETECTION = 'AssetTagDetection'¶

INDUSTRIAL_OBJECT_DETECTION = 'IndustrialObjectDetection'¶

PEOPLE_DETECTION = 'PeopleDetection'¶

PERSONAL_PROTECTIVE_EQUIPMENT_DETECTION = 'PersonalProtectiveEquipmentDetection'¶

TEXT_DETECTION = 'TextDetection'¶

class cognite.experimental.data_classes.vision.FeatureParameters(text_detection_parameters: Union[cognite.experimental.data_classes.vision.TextDetectionParameters, NoneType] = None, asset_tag_detection_parameters: Union[cognite.experimental.data_classes.vision.AssetTagDetectionParameters, NoneType] = None, people_detection_parameters: Union[cognite.experimental.data_classes.vision.PeopleDetectionParameters, NoneType] = None, industrial_object_detection_parameters: Union[cognite.experimental.data_classes.vision.IndustrialObjectDetectionParameters, NoneType] = None, personal_protective_equipment_detection_parameters: Union[cognite.experimental.data_classes.vision.PersonalProtectiveEquipmentDetectionParameters, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

asset_tag_detection_parameters = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

industrial_object_detection_parameters = None¶

people_detection_parameters = None¶

personal_protective_equipment_detection_parameters = None¶

text_detection_parameters = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.IndustrialObjectDetectionParameters(threshold: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource, cognite.experimental.data_classes.vision.ThresholdParameter

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

threshold = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.InternalFileId(file_id: int)¶: Bases: object

class cognite.experimental.data_classes.vision.PeopleDetectionParameters(threshold: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource, cognite.experimental.data_classes.vision.ThresholdParameter

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

threshold = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.PersonalProtectiveEquipmentDetectionParameters(threshold: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource, cognite.experimental.data_classes.vision.ThresholdParameter

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

threshold = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.SuccessfulAssetDetectionInFiles(file_id: int, file_external_id: Union[str, NoneType] = None, width: Union[int, NoneType] = None, height: Union[int, NoneType] = None, annotations: Union[List[cognite.experimental.data_classes.vision.VisionTagDetectionAnnotation], NoneType] = None)¶

Bases: cognite.experimental.data_classes.vision.AllOfFileId

annotations = None¶

file_external_id = None¶

height = None¶

width = None¶

class cognite.experimental.data_classes.vision.TextDetectionParameters(threshold: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource, cognite.experimental.data_classes.vision.ThresholdParameter

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

threshold = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.ThresholdParameter(threshold: Union[float, NoneType] = None)¶

Bases: object

threshold = None¶

class cognite.experimental.data_classes.vision.VisionExtractItem(file_id: int = None, predictions: Dict[str, Any] = None, file_external_id: str = None, error_message: str = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

class cognite.experimental.data_classes.vision.VisionExtractJob(*args, **kwargs)¶

Bases: cognite.experimental.data_classes.vision.VisionJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

errors¶: Returns a list of all error messages across files

items¶: Returns a list of all predictions by file

result¶: Waits for the job to finish and returns the results.

save_predictions(creating_user: Optional[str] = None, creating_app: Optional[str] = None, creating_app_version: Optional[str] = None) → Union[cognite.experimental.data_classes.annotations.Annotation, cognite.experimental.data_classes.annotations.AnnotationList]¶

Saves all predictions made by the feature extractors in CDF using the Annotations API. See https://docs.cognite.com/api/v1/#tag/Annotations/operation/annotationsSuggest

Parameters:	creating_app (str, optional) – The name of the app from which this annotation was created. Defaults to ‘cognite-sdk-experimental’. creating_app_version (str, optional) – The version of the app that created this annotation. Must be a valid semantic versioning (SemVer) string. Defaults to client version. creating_user – (str, optional): A username, or email, or name. This is not checked nor enforced. If the value is None, it means the annotation was created by a service.
Returns:	(suggested) annotation(s) stored in CDF.
Return type:	Union[Annotation, AnnotationList]

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.vision.VisionExtractPredictions(text_predictions: Union[List[cognite.experimental.data_classes.annotation_types.images.TextRegion], NoneType] = None, asset_tag_predictions: Union[List[cognite.experimental.data_classes.annotation_types.images.AssetLink], NoneType] = None, industrial_object_predictions: Union[List[cognite.experimental.data_classes.annotation_types.images.ObjectDetection], NoneType] = None, people_predictions: Union[List[cognite.experimental.data_classes.annotation_types.images.ObjectDetection], NoneType] = None, personal_protective_equipment_predictions: Union[List[cognite.experimental.data_classes.annotation_types.images.ObjectDetection], NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

asset_tag_predictions = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

industrial_object_predictions = None¶

people_predictions = None¶

personal_protective_equipment_predictions = None¶

text_predictions = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.vision.VisionJob(job_id=None, model_id=None, status=None, error_message=None, created_time=None, start_time=None, status_time=None, status_path=None, cognite_client=None, **kwargs)¶

Bases: cognite.client.data_classes.contextualization.ContextualizationJob

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

result¶: Waits for the job to finish and returns the results.

to_pandas(expand: List[str] = ('metadata', ), ignore: List[str] = None, camel_case: bool = True)¶

Convert the instance into a pandas DataFrame.

Parameters:	expand (List[str]) – List of row keys to expand, only works if the value is a Dict. Will expand metadata by default. ignore (List[str]) – List of row keys to not include when converting to a data frame. camel_case (bool) – Convert column names to camel case (e.g. externalId instead of external_id)
Returns:	The dataframe.
Return type:	pandas.DataFrame

update_status() → str¶: Updates the model status and returns it

wait_for_completion(timeout=None, interval=1)¶: Waits for job completion, raising ModelFailedException if fit failed - generally not needed to call as it is called by result. :param timeout: Time out after this many seconds. (None means wait indefinitely) :param interval: Poll status every this many seconds.

class cognite.experimental.data_classes.vision.VisionRegion(shape: str, vertices: List[cognite.experimental.data_classes.vision.VisionVertex])¶: Bases: object

class cognite.experimental.data_classes.vision.VisionTagDetectionAnnotation(text: str, asset_ids: List[int], confidence: Union[float, NoneType] = None, region: Union[cognite.experimental.data_classes.vision.VisionRegion, NoneType] = None)¶

Bases: object

confidence = None¶

region = None¶

class cognite.experimental.data_classes.vision.VisionVertex(x: float, y: float)¶: Bases: object

Image type data classes¶

Minimal containers for the image annotations returned by the Annotations API.

class cognite.experimental.data_classes.annotation_types.images.AssetLink(text: str, text_region: cognite.experimental.data_classes.annotation_types.primitives.BoundingBox, asset_ref: cognite.experimental.data_classes.annotation_types.primitives.CdfResourceRef, confidence: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

confidence = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.images.ObjectDetection(label: str, confidence: Union[float, NoneType], bounding_box: Union[cognite.experimental.data_classes.annotation_types.primitives.BoundingBox, NoneType] = None, polygon: Union[cognite.experimental.data_classes.annotation_types.primitives.Polygon, NoneType] = None, polyline: Union[cognite.experimental.data_classes.annotation_types.primitives.PolyLine, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

bounding_box = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

polygon = None¶

polyline = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.images.TextRegion(text: str, text_region: cognite.experimental.data_classes.annotation_types.primitives.BoundingBox, confidence: Union[float, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

confidence = None¶

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

Primitive type data classes¶

Minimal containers for the primitive annotations returned by the Annotations API.

class cognite.experimental.data_classes.annotation_types.primitives.BoundingBox(x_min: float, x_max: float, y_min: float, y_max: float)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.primitives.CdfResourceRef(id: Union[int, NoneType] = None, external_id: Union[str, NoneType] = None)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

external_id = None¶

id = None¶

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.primitives.Point(x: float, y: float)¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.primitives.PolyLine(vertices: List[cognite.experimental.data_classes.annotation_types.primitives.Point])¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.primitives.Polygon(vertices: List[cognite.experimental.data_classes.annotation_types.primitives.Point])¶

Bases: cognite.experimental.data_classes.annotation_types.primitives.VisionResource

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

class cognite.experimental.data_classes.annotation_types.primitives.VisionResource¶

Bases: object

dump(camel_case: bool = False) → Dict[str, Any]¶

Dump the instance into a json serializable Python data type.

Parameters:	camel_case (bool) – Use camelCase for attribute names. Defaults to False.
Returns:	A dictionary representation of the instance.
Return type:	Dict[str, Any]

to_pandas(camel_case: bool = False) → Dict[str, Any]¶

Extensions for Templates¶

The main templates SDK is available through the main sdk.

Get suggestions for missing entries¶

TemplateCompletionAPI.complete(external_id: str, template_name: str, asset_property: str = None, version: int = None) → cognite.client.data_classes.contextualization.ContextualizationJob¶

Completes a schema uploaded in CDF as a domain.

Parameters:	external_id (str) – External ID of the template group to work on. template_name (str) – Name of the template to be completed within the template group asset_property (str) – Which field (with constant type) in the template defines the externalId of the parent asset in each entry. If ommitted, it is assumed the externalId of the template instances is the same as the parent asset’s externalId. version (int) – Version of the domain, can be ommitted to use the last one.
Returns:	Resulting queued job. Note that .results property of this job will block waiting for results.
Return type:	ContextualizationJob

Examples

Get template groups by external id:

>>> from cognite.experimental import CogniteClient
>>> c = CogniteClient()
>>> res = c.templates.completion.complete(external_id="abc",template_name="covid")

Geospatial¶

Note

Check https://github.com/cognitedata/geospatial-examples for some complete examples.

Rasters¶

Put Raster¶

ExperimentalGeospatialAPI.put_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str, raster_format: str, raster_srid: int, file: str, allow_crs_transformation: bool = False, raster_scale_x: Optional[float] = None, raster_scale_y: Optional[float] = None) → cognite.experimental.data_classes.geospatial.RasterMetadata¶

Put raster <https://pr-1632.specs.preview.cogniteapp.com/v1.json.html#operation/putRaster>

Parameters:	feature_type_external_id – Feature type definition for the features to create. feature_external_id – one feature or a list of features to create raster_property_name – the raster property name raster_format – the raster input format raster_srid – the associated SRID for the raster file – the path to the file of the raster allow_crs_transformation – When the parameter is false, requests with rasters in Coordinate Reference System different from the one defined in the feature type will result in bad request response code. raster_scale_x – the X component of the pixel width in units of coordinate reference system raster_scale_y – the Y component of the pixel height in units of coordinate reference system
Returns:	the raster metadata if it was ingested succesfully
Return type:	RasterMetadata

Examples

Put a raster in a feature raster property:

>>> from cognite.experimental import CogniteClient
>>> c = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> metadata = c.geospatial.put_raster(feature_type, feature, raster_property_name, "XYZ", 3857, file)

Delete Raster¶

ExperimentalGeospatialAPI.delete_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str) → None¶

Delete raster <https://pr-1632.specs.preview.cogniteapp.com/v1.json.html#operation/deleteRaster>

Parameters:	feature_type_external_id – Feature type definition for the features to create. feature_external_id – one feature or a list of features to create raster_property_name – the raster property name
Returns:	None

Examples

Delete a raster in a feature raster property:

>>> from cognite.experimental import CogniteClient
>>> c = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> c.geospatial.delete_raster(feature_type, feature, raster_property_name)

Get Raster¶

ExperimentalGeospatialAPI.get_raster(feature_type_external_id: str, feature_external_id: str, raster_property_name: str, raster_format: str, raster_options: Dict[str, Any] = None, raster_srid: Optional[int] = None, raster_scale_x: Optional[float] = None, raster_scale_y: Optional[float] = None, allow_crs_transformation: bool = False) → bytes¶

Get raster <https://pr-1632.specs.preview.cogniteapp.com/v1.json.html#operation/getRaster>

Parameters:	feature_type_external_id – Feature type definition for the features to create. feature_external_id – one feature or a list of features to create raster_property_name – the raster property name raster_format – the raster output format raster_options – GDAL raster creation key-value options raster_srid – the SRID for the output raster raster_scale_x – the X component of the output pixel width in units of coordinate reference system raster_scale_y – the Y component of the output pixel height in units of coordinate reference system allow_crs_transformation – When the parameter is false, requests with output rasters in Coordinate Reference System different from the one defined in the feature type will result in bad request response code.
Returns:	the raster data
Return type:	bytes

Examples

Get a raster from a feature raster property:

>>> from cognite.experimental import CogniteClient
>>> c = CogniteClient()
>>> feature_type = ...
>>> feature = ...
>>> raster_property_name = ...
>>> raster_data = c.geospatial.get_raster(feature_type, feature, raster_property_name,
>>>                                       "XYZ", {"SIGNIFICANT_DIGITS": "4"})

Mapbox Vector Tiles (MVTs)¶

Create MVT Mappings¶

ExperimentalGeospatialAPI.create_mvt_mappings_definitions(mappings_definitions: Union[cognite.experimental.data_classes.geospatial.MvpMappingsDefinition, cognite.experimental.data_classes.geospatial.MvpMappingsDefinitionList]) → cognite.experimental.data_classes.geospatial.MvpMappingsDefinitionList¶

Creates MVP mappings <https://pr-1653.specs.preview.cogniteapp.com/v1.json.html#operation/GeospatialCreateMvtMappings>

Parameters:	mappings_definitions – list of MVT mappings definitions
Returns:	list of created MVT mappings definitions
Return type:	Union[List[Dict[str, Any]]]

Examples

Create MVT mappings, assuming the feature types aggregated_seismic_surveys and seismic_surveys:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> mvp_mappings_def = MvpMappingsDefinition(
>>>                        external_id="surveys",
>>>                        mappings_definitions=[
...                            {
...                                "featureTypeExternalId": "aggregated_seismic_surveys",
...                                "levels": [0,1,2,3,4,5],
...                                "geometryProperty": "agg_geom",
...                                "featureProperties": ["survey_type"]
...                            },
...                            {
...                                "featureTypeExternalId": "seismic_surveys",
...                                "levels": [6,7,8,9,10,11,12,13,14,15],
...                                "geometryProperty": "geom",
...                                "featureProperties": ["survey_type", "sample_rate"]
...                            ),
...                        ]
...                    )
>>> res = c.geospatial.create_mvt_mappings_definitions(mvp_mappings_def)

Delete MVT Mappings¶

ExperimentalGeospatialAPI.delete_mvt_mappings_definitions(external_id: Union[str, List[str]] = None) → None¶

Deletes MVP mappings definitions <https://pr-1653.specs.preview.cogniteapp.com/v1.json.html#operation/GeospatialDeleteMvtMappings>

Parameters:	external_id (Union[str, List[str]]) – the mappings external ids
Returns:	None

Examples

Deletes MVT mappings definitions:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.geospatial.delete_mvt_mappings_definitions(external_id="surveys")

Retrieve MVT Mappings¶

ExperimentalGeospatialAPI.retrieve_mvt_mappings_definitions(external_id: Union[str, List[str]] = None) → cognite.experimental.data_classes.geospatial.MvpMappingsDefinitionList¶

Retrieve MVP mappings definitions <https://pr-1653.specs.preview.cogniteapp.com/v1.json.html#operation/GeospatialGetByIdsMvtMappings>

Parameters:	external_id (Union[str, List[str]]) – the mappings external ids external_id – External ID or list of external ids
Returns:	the requested mappings or None if it does not exist.
Return type:	MvpMappingsDefinitionList

Examples

Retrieve one MVT mapping by its external id:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> c.geospatial.retrieve_mvt_mappings_definitions(external_id="surveys")

List MVT Mappings¶

ExperimentalGeospatialAPI.list_mvt_mappings_definitions() → cognite.experimental.data_classes.geospatial.MvpMappingsDefinitionList¶

List MVP mappings definitions <https://pr-1653.specs.preview.cogniteapp.com/v1.json.html#operation/GeospatialListMvtMappings>

Returns:	the requested mappings or EmptyList if it does not exist.
Return type:	MvpMappingsDefinitionList

Examples

List MVT mappings:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> c.geospatial.list_mvt_mappings_definitions()

Compute¶

ExperimentalGeospatialAPI.compute(sub_computes: Dict[str, Any] = None, from_feature_type: str = None, filter: Dict[str, Any] = None, output: Dict[str, Any] = None, binary_output: Dict[str, Any] = None) → Union[bytes, cognite.experimental.data_classes.geospatial.ComputedItemList]¶

Compute something <https://pr-1717.specs.preview.cogniteapp.com/v1.json.html#operation/compute>

Parameters:	sub_computes (Dict[str, Any]) – the sub-computed data for the main compute from_feature_type (str) – the main feature type external id to compute from filter (Dict[str, Any]) – the filter for the main feature type output (Dict[str, Any]) – the output json spec binary_output (Dict[str, Any]) – the binary output computation to execute
Returns:	Union[bytes,List[ComputedItem]]

Examples

Compute the area and the perimeter of a direct geometry value:

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.geospatial.compute(
...     sub_computes={"geom": { "ewkt": "SRID=4326;POLYGON((0 0,0 10,10 10,10 0, 0 0))"}},
...     output={
...         "geomArea": {"stArea": {"geometry": {"ref": "geom"}}}
...         "geomPerimeter": {"stPerimeter": {"geometry": {"ref": "geom"}}}
...     },
>>> )

Compute the geotiff image of the union of clipped selection of rasters

>>> from cognite.client import CogniteClient
>>> c = CogniteClient()
>>> res = c.geospatial.compute(
...     from_feature_type="windspeed",
...     filter={"equals": {"property": "tag", "value": "SWE"}},
...     binary_output={
...         "stAsGeotiff": {
...             "raster": {
...                 "stUnion": {
...                     "raster": {
...                         "stClip": {
...                             "raster": {"property": "rast"},
...                             "geometry": {"ewkt": "SRID=4326;POLYGON((17.410 64.966,17.698 64.653,18.016 65.107,17.410 64.966))"}
...                         }
...                     }
...                 }
...             }
...         }
...     }
>>> )

Compute the transformed geometry of a direct geometry value

>>> client.geospatial.compute(
...     output={
...         "from4326to3857": {
...             "stTransform": {
...                 "geometry": {"ewkt": "SRID=4326;POINT(2.353295 48.850908)"},
...                 "srid": 3857
...             }
...         }
...     }
... )

Compute multiple transformed geometries of a direct “sub_compute” geometry value

>>> client.geospatial.compute(
...     sub_computes={"paris": {"ewkt": "SRID=4326;POINT(2.353295 48.850908)"}},
...     output={
...         "from4326to3857": {"stTransform": {"geometry": {"ref": "paris"}, "srid": 3857}},
...         "from4326to102016": {"stTransform": {"geometry": {"ref": "paris"}, "srid": 102016}},
...     }
... )

Data classes¶

class cognite.experimental.data_classes.geospatial.ComputedItem(cognite_client=None, **properties)¶

Bases: cognite.client.data_classes._base.CogniteResource

A representation of a computed item by the geospatial api.

class cognite.experimental.data_classes.geospatial.ComputedItemList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.geospatial.MvpMappingsDefinition(external_id: str = None, mappings: List[Dict[str, Any]] = None, cognite_client=None)¶

Bases: cognite.client.data_classes._base.CogniteResource

MVT mappings definition

class cognite.experimental.data_classes.geospatial.MvpMappingsDefinitionList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.geospatial.RasterMetadata(**properties)¶

Bases: object

Raster metadata

Alerting¶

Channels¶

A Channel is a bus to which Subscribers can make a Subscription and that Alerts can be sent to. Upon the receival of an Alert, a notification is sent on all registered providers of its Subscribers. A Channel can have a Parent, Alerts are propagated recursively from a Channel to its Parent and all of their Parents.

List channels¶

AlertChannelsAPI.list(external_ids: List[str] = None, ids: List[int] = None, parent_ids: List[str] = None, metadata: Dict[str, str] = None, limit=100) → cognite.experimental.data_classes.alerts.AlertChannelList¶

List alert channels

Parameters:	ids – channel ids external_ids – channel external ids parent_ids – channel parent ids metadata – strict metadata filtering
Returns:	list of channels
Return type:	AlertChannelList

Create channels¶

AlertChannelsAPI.create(channels: Union[cognite.experimental.data_classes.alerts.AlertChannel, List[cognite.experimental.data_classes.alerts.AlertChannel]]) → Union[cognite.experimental.data_classes.alerts.AlertChannel, cognite.experimental.data_classes.alerts.AlertChannelList]¶

Create channels

Parameters:	channels (Union[AlertChannel, List[AlertChannel]]) – channel(s) to create
Returns:	created channel(s)
Return type:	Union[AlertChannel, AlertChannelList]

Update channels¶

AlertChannelsAPI.update(items: Union[cognite.experimental.data_classes.alerts.AlertChannel, cognite.experimental.data_classes.alerts.AlertChannelUpdate, List[Union[cognite.experimental.data_classes.alerts.AlertChannel, cognite.experimental.data_classes.alerts.AlertChannelUpdate]]]) → Union[cognite.experimental.data_classes.alerts.AlertChannel, cognite.experimental.data_classes.alerts.AlertChannelList]¶

Update alerting channels

Parameters:	items – Union[AlertChannel, AlertChannelUpdate, List[Union[AlertChannel, AlertChannelUpdate]]]: channel(s) to be updated
Returns:	updated items
Return type:	Union[AlertChannel, AlertChannelList]

Delete channels¶

AlertChannelsAPI.delete(ids: List[int] = None, external_ids: List[str] = None) → None¶

Alerts¶

An Alert is an event detected by a monitoring system, raised to trigger a notification. The Alert is linked to a channel, and upon Alert creation, a Notification sent to all subscribers of the Channel and the Channels’ parents

List alerts¶

AlertsAPI.list(ids: List[int] = None, external_ids: List[str] = None, channel_ids: List[int] = None, channel_external_ids: List[int] = None, closed: bool = None, start_time: str = None, end_time: str = None, limit=100) → cognite.experimental.data_classes.alerts.AlertList¶

List alerts

Parameters:	ids – alert ids to filter on external_ids – alert external_ids to filter on channel_ids – alert channel_ids to filter on channel_external_ids – alert channel_external_ids to filter on closed – filter on whether alerts are closed or not start_time – filter alerts based on timestamp end_time – filter alerts based on timestamp
Returns:	list of alerts
Return type:	AlertsList

Create alerts¶

AlertsAPI.create(alerts: Union[cognite.experimental.data_classes.alerts.Alert, List[cognite.experimental.data_classes.alerts.Alert]]) → Union[cognite.experimental.data_classes.alerts.Alert, cognite.experimental.data_classes.alerts.AlertList]¶

Close alerts¶

AlertsAPI.close(ids: List[int] = None, external_ids: List[str] = None) → None¶

Close alerts

Parameters:	ids – alert(s) ids to close external_ids – alert(s) external_ids to close
Returns:	None

Subscribers¶

Subscribers are the people or groups thereof that should be notified when an Alert is fired. Subscribers can subscribe to multiple Channels

Create subscribers¶

AlertSubscribersAPI.create(subscribers: Union[cognite.experimental.data_classes.alerts.AlertSubscriber, List[cognite.experimental.data_classes.alerts.AlertSubscriber]]) → Union[cognite.experimental.data_classes.alerts.AlertSubscriber, cognite.experimental.data_classes.alerts.AlertSubscriberList]¶

Subscriptions¶

Subscriptions link subscribers to channels, subscribing them to Alerts sent to the channel or channels that are children of that channel

Create subscriptions¶

AlertSubscriptionsAPI.create(subscriptions: Union[cognite.experimental.data_classes.alerts.AlertSubscription, List[cognite.experimental.data_classes.alerts.AlertSubscriptionList]]) → Union[cognite.experimental.data_classes.alerts.AlertSubscription, cognite.experimental.data_classes.alerts.AlertSubscriptionList]¶

Delete subscriptions¶

AlertSubscriptionsAPI.delete(cmds: List[cognite.experimental.data_classes.alerts.AlertSubscriptionDelete]) → None¶

Data classes¶

class cognite.experimental.data_classes.alerts.Alert(id: int = None, external_id: str = None, timestamp: int = None, channel_id: int = None, channel_external_id: int = None, source: str = None, value: str = None, level: str = None, metadata: Dict[str, str] = None, acknowledged: bool = None, closed: bool = None, cognite_client: CogniteClient = None)¶: Bases: cognite.client.data_classes._base.CogniteResource

class cognite.experimental.data_classes.alerts.AlertChannel(external_id: str = None, id: int = None, name: str = None, parent_id: int = None, parent_external_id: str = None, description: str = None, metadata: Dict[str, str] = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

Alert channel

class cognite.experimental.data_classes.alerts.AlertChannelFilter(external_ids: List[str] = None, ids: List[int] = None, parent_ids: List[str] = None, metadata: Dict[str, str] = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on alert channels with strict matching.

class cognite.experimental.data_classes.alerts.AlertChannelList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.alerts.AlertChannelUpdate(id: int = None, external_id: str = None)¶

Bases: cognite.client.data_classes._base.CogniteUpdate

Changes will be applied to alerting channel.

Parameters:	id (int) – A server-generated ID for the object. external_id (str) – The external ID provided by the client. Must be unique for the resource type.

class cognite.experimental.data_classes.alerts.AlertFilter(ids: List[int] = None, external_ids: List[str] = None, channel_ids: List[int] = None, channel_external_ids: List[int] = None, closed: bool = None, start_time: int = None, end_time: int = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteFilter

Filter on alerts with strict matching.

class cognite.experimental.data_classes.alerts.AlertList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.alerts.AlertSubscriber(id: int = None, external_id: str = None, metadata: Dict[str, str] = None, email: str = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

Alert subscriber

class cognite.experimental.data_classes.alerts.AlertSubscriberList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList

class cognite.experimental.data_classes.alerts.AlertSubscription(id: int = None, external_id: str = None, channel_id: int = None, channel_external_id: str = None, subscriber_id: int = None, subscriber_external_id: str = None, metadata: Dict[str, str] = None, cognite_client: CogniteClient = None)¶

Bases: cognite.client.data_classes._base.CogniteResource

Alert subscription

class cognite.experimental.data_classes.alerts.AlertSubscriptionList(resources: List[Any], cognite_client=None)¶: Bases: cognite.client.data_classes._base.CogniteResourceList