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:

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.

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

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