From 166e7fa733f46672182b1fbdf664681beb78900d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Torbj=C3=B8rn?= <53564704+torbjornopheim@users.noreply.github.com> Date: Thu, 7 Dec 2023 12:44:37 +0100 Subject: [PATCH] [Documentation] Added examples to entity matching (#1123) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: Ola Liabøtrø Co-authored-by: olacognite <31041282+olacognite@users.noreply.github.com> --- cognite/client/_api/entity_matching.py | 102 +++++++++++++++++++++---- 1 file changed, 87 insertions(+), 15 deletions(-) diff --git a/cognite/client/_api/entity_matching.py b/cognite/client/_api/entity_matching.py index 8ae28a3bf7..24d87cab3f 100644 --- a/cognite/client/_api/entity_matching.py +++ b/cognite/client/_api/entity_matching.py @@ -41,14 +41,20 @@ def _run_job( ) def retrieve(self, id: int | None = None, external_id: str | None = None) -> EntityMatchingModel | None: - """Retrieve model - + """`Retrieve model `_ Args: id (int | None): id of the model to retrieve. external_id (str | None): external id of the model to retrieve. Returns: - EntityMatchingModel | None: Model requested.""" + EntityMatchingModel | None: Model requested. + + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> retrieved_model = client.entity_matching.retrieve(id=1) + """ + identifiers = IdentifierSequence.load(ids=id, external_ids=external_id).as_singleton() return self._retrieve_multiple( list_cls=EntityMatchingModelList, resource_cls=EntityMatchingModel, identifiers=identifiers @@ -57,14 +63,21 @@ def retrieve(self, id: int | None = None, external_id: str | None = None) -> Ent def retrieve_multiple( self, ids: Sequence[int] | None = None, external_ids: Sequence[str] | None = None ) -> EntityMatchingModelList: - """Retrieve models + """`Retrieve models `_ Args: ids (Sequence[int] | None): ids of the model to retrieve. external_ids (Sequence[str] | None): external ids of the model to retrieve. Returns: - EntityMatchingModelList: Models requested.""" + EntityMatchingModelList: Models requested. + + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> retrieved_models = client.entity_matching.retrieve_multiple([1,2,3]) + + """ identifiers = IdentifierSequence.load(ids=ids, external_ids=external_ids) return self._retrieve_multiple( list_cls=EntityMatchingModelList, resource_cls=EntityMatchingModel, identifiers=identifiers @@ -76,13 +89,20 @@ def update( | EntityMatchingModelUpdate | Sequence[EntityMatchingModel | EntityMatchingModelUpdate], ) -> EntityMatchingModelList | EntityMatchingModel: - """Update model + """`Update model `_ Args: item (EntityMatchingModel | EntityMatchingModelUpdate | Sequence[EntityMatchingModel | EntityMatchingModelUpdate]): Model(s) to update Returns: - EntityMatchingModelList | EntityMatchingModel: No description.""" + EntityMatchingModelList | EntityMatchingModel: No description. + + Examples: + >>> from cognite.client.data_classes.contextualization import EntityMatchingModelUpdate + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> client.entity_matching.update(EntityMatchingModelUpdate(id=1).name.set("New name")) + """ return self._update_multiple( list_cls=EntityMatchingModelList, resource_cls=EntityMatchingModel, @@ -99,7 +119,7 @@ def list( classifier: str | None = None, limit: int | None = DEFAULT_LIMIT_READ, ) -> EntityMatchingModelList: - """List models + """`List models `_ Args: name (str | None): Optional user-defined name of model. @@ -111,6 +131,11 @@ def list( Returns: EntityMatchingModelList: List of models. + + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> client.entity_matching.list(limit=1, name="test") """ if is_unlimited(limit): limit = 1_000_000_000 # currently no pagination @@ -127,8 +152,8 @@ def list( return EntityMatchingModelList.load(models, cognite_client=self._cognite_client) def list_jobs(self) -> ContextualizationJobList: + # TODO: Not in service contract """List jobs, typically model fit and predict runs. - Returns: ContextualizationJobList: List of jobs.""" return ContextualizationJobList.load( @@ -136,11 +161,18 @@ def list_jobs(self) -> ContextualizationJobList: ) def delete(self, id: int | Sequence[int] | None = None, external_id: str | Sequence[str] | None = None) -> None: - """Delete models + """`Delete models `_ + + https://api-docs.cognite.com/20230101/tag/Entity-matching/operation/entityMatchingDelete + Args: id (int | Sequence[int] | None): Id or list of ids external_id (str | Sequence[str] | None): External ID or list of external ids + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> client.entity_matching.delete(id=1) """ self._delete_multiple(identifiers=IdentifierSequence.load(ids=id, external_ids=external_id), wrap_ids=True) @@ -158,6 +190,8 @@ def fit( description: str | None = None, external_id: str | None = None, ) -> EntityMatchingModel: + # TODO: Not in service contract + """Fit entity matching model. Note: @@ -176,7 +210,21 @@ def fit( description (str | None): Optional user-defined description of model. external_id (str | None): Optional external id. Must be unique within the project. Returns: - EntityMatchingModel: Resulting queued model.""" + EntityMatchingModel: Resulting queued model. + + Example: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> sources = [{'id': 101, 'name': 'ChildAsset1', 'description': 'Child of ParentAsset1'}] + >>> targets = [{'id': 1, 'name': 'ParentAsset1', 'description': 'Parent to ChildAsset1'}] + >>> true_matches = [(1, 101)] + >>> model = client.entity_matching.fit( + ... sources=sources, + ... targets=targets, + ... true_matches=true_matches, + ... description="AssetMatchingJob1" + ... ) + """ if match_fields: match_fields_processed = [ @@ -212,7 +260,7 @@ def predict( id: int | None = None, external_id: str | None = None, ) -> ContextualizationJob: - """Predict entity matching. + """`Predict entity matching. `_ Warning: Blocks and waits for the model to be ready if it has been recently created. @@ -230,8 +278,23 @@ def predict( external_id (str | None): external ids of the model to use. Returns: - ContextualizationJob: Object which can be used to wait for and retrieve results. + ContextualizationJob: object which can be used to wait for and retrieve results. + + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> sources = {'id': 101, 'name': 'ChildAsset1', 'description': 'Child of ParentAsset1'} + >>> targets = {'id': 1, 'name': 'ParentAsset1', 'description': 'Parent to ChildAsset1'} + >>> true_matches = [(1, 101)] + >>> model = client.entity_matching.predict( + ... sources = sources, + ... targets = targets, + ... num_matches = 1, + ... score_threshold = 0.6, + ... id=1 + ... ) """ + model = self.retrieve(id=id, external_id=external_id) assert model return model.predict( # could call predict directly but this is friendlier @@ -247,7 +310,7 @@ def refit( id: int | None = None, external_id: str | None = None, ) -> EntityMatchingModel: - """Re-fits an entity matching model, using the combination of the old and new true matches. + """`Re-fits an entity matching model, using the combination of the old and new true matches. `_ Note: All users on this CDF subscription with assets read-all and entitymatching read-all and write-all @@ -258,7 +321,16 @@ def refit( id (int | None): ids of the model to use. external_id (str | None): external ids of the model to use. Returns: - EntityMatchingModel: new model refitted to true_matches.""" + EntityMatchingModel: new model refitted to true_matches. + + Examples: + >>> from cognite.client import CogniteClient + >>> client = CogniteClient() + >>> sources = [{'id': 101, 'name': 'ChildAsset1', 'description': 'Child of ParentAsset1'}] + >>> targets = [{'id': 1, 'name': 'ParentAsset1', 'description': 'Parent to ChildAsset1'}] + >>> true_matches = [(1, 101)] + >>> model = client.entity_matching.refit(true_matches = true_matches, description="AssetMatchingJob1", id=1) + """ model = self.retrieve(id=id, external_id=external_id) assert model return model.refit(true_matches=true_matches)