cognite-neat 0.102.0__py3-none-any.whl → 0.103.1__py3-none-any.whl

cognite/neat/_session/_base.py

@@ -54,6 +54,26 @@ class NeatSession:
         load_engine: Whether to load the Neat Engine. Can be "newest", "cache", or "skip". "newest" will always
             check for the newest version of the engine. "cache" will load the engine if it has been downloaded before.
             "skip" will not load the engine.
+
+    Example:
+        Instantiate a NeatSession outside CDF jupyter notebook (needs instantiation of a CogniteClient)
+        ```python
+        from cognite.neat import get_cognite_client
+        from cognite.neat import NeatSession
+
+        client = get_cognite_client(env_file_name=".env")
+        neat = NeatSession(client)
+        ```
+
+    Example:
+        Instantiate a NeatSession inside a CDF jupyter notebook (use your user's CogniteClient directly)
+        ```python
+        from cognite.client import CogniteClient
+        from cognite.neat import NeatSession
+
+        client = CogniteClient()
+        neat = NeatSession(client)
+        ```
     """
 
     def __init__(
@@ -81,9 +101,33 @@ class NeatSession:
 
     @property
     def version(self) -> str:
+        """Get the current version of neat.
+
+        Returns:
+            The current version of neat used in the session.
+
+        Example:
+            ```python
+            neat.version
+            ```
+        """
         return _version.__version__
 
     def verify(self) -> IssueList:
+        """
+        Verify the Data Model schema before the model can be written to CDF. If verification was unsuccessful, use
+        `.inspect.issues()` to see what went wrong.
+
+        Example:
+            Verify a data model after reading a source file and inferring the data model
+            ```python
+            # From an active NeatSession
+            ...
+            neat.read.xml.dexpi("url_or_path_to_dexpi_file")
+            neat.infer()
+            neat.verify()
+            ```
+        """
         source_id, last_unverified_rule = self._state.data_model.last_unverified_rule
         transformer = VerifyAnyRules("continue", validate=False)
         start = datetime.now(timezone.utc)
@@ -135,6 +179,18 @@ class NeatSession:
             target: The target type to convert the data model to.
             mode: If the target is "dms", the mode to use for the conversion. None is used for default conversion.
                 "edge_properties" treas classes that implements Edge as edge properties.
+
+        Example:
+            Convert to DMS rules
+            ```python
+            neat.convert(target="dms")
+            ```
+
+        Example:
+            Convert to Information rules
+            ```python
+            neat.convert(target="information")
+            ```
         """
         start = datetime.now(timezone.utc)
         issues = IssueList()
@@ -196,6 +252,15 @@ class NeatSession:
         Args:
             model_id: The ID of the inferred data model.
             max_number_of_instance: The maximum number of instances to use for inference.
+
+        Example:
+            Infer a data model after reading a source file
+            ```python
+            # From an active NeatSession
+            ...
+            neat.read.xml.dexpi("url_or_path_to_dexpi_file")
+            neat.infer()
+            ```
         """
         model_id = dm.DataModelId.load(model_id)
 
@@ -254,6 +319,10 @@ class NeatSession:
 
 @session_class_wrapper
 class OptAPI:
+    """For the user to decide if they want their usage of neat to be collected or not. We do not collect personal
+    information like name etc. only usage.
+    """
+
     def __init__(self, collector: Collector | None = None) -> None:
         self._collector = collector or _COLLECTOR
 
@@ -268,9 +337,11 @@ class OptAPI:
         )
 
     def in_(self) -> None:
+        """Consent to collection of neat user insights."""
         self._collector.enable()
         print("You have successfully opted in to data collection.")
 
     def out(self) -> None:
+        """Opt out of allowing usage of neat to be collected from current user."""
         self._collector.disable()
         print("You have successfully opted out of data collection.")

cognite/neat/_session/_collector.py

@@ -60,7 +60,7 @@ class Collector:
         if len(args) > 1:
             # The first argument is self.
             for i, arg in enumerate(args[1:]):
-                event_information[f"arg{i}"] = arg
+                event_information[f"arg{i}"] = self._serialize_value(arg)[:500]
 
         if kwargs:
             for key, value in kwargs.items():
@@ -73,6 +73,8 @@ class Collector:
             return str(value)
         if isinstance(value, list | tuple | dict):
             return str(value)
+        if callable(value):
+            return value.__name__
         return str(type(value))
 
     def _track(self, event_name: str, event_information: dict[str, Any]) -> bool:

cognite/neat/_session/_drop.py

@@ -11,6 +11,10 @@ except ImportError:
 
 @session_class_wrapper
 class DropAPI:
+    """
+    Drop instances from the session. Check out `.instances()` for performing the operation.
+    """
+
     def __init__(self, state: SessionState):
         self._state = state
 
@@ -19,6 +23,12 @@ class DropAPI:
 
         Args:
             type: The type of instances to drop.
+
+        Example:
+            ```python
+            node_type_to_drop = "Pump"
+            neat.drop.instances(node_type_to_drop)
+            ```
         """
         type_list = type if isinstance(type, list) else [type]
         uri_type_type = dict((v, k) for k, v in self._state.instances.store.queries.types.items())

cognite/neat/_session/_inspect.py

@@ -21,6 +21,28 @@ except ImportError:
 
 @session_class_wrapper
 class InspectAPI:
+    """Inspect issues or outcomes after performing operations with NeatSession.
+    To inspect properties of the current data model, try out `.properties()`.
+
+    Example:
+        Inspect issues
+        ```python
+        neat.inspect.issues()
+        ```
+
+    Example:
+        Inspect outcome after writing a data model
+        ```python
+        neat.inspect.outcome.data_model()
+        ```
+
+    Example:
+        Inspect outcome after writing instances
+        ```python
+        neat.inspect.outcome.instances()
+        ```
+    """
+
     def __init__(self, state: SessionState) -> None:
         self._state = state
         self.issues = InspectIssues(state)
@@ -28,7 +50,15 @@ class InspectAPI:
 
     @property
     def properties(self) -> pd.DataFrame:
-        """Returns the properties of the current data model."""
+        """Returns the properties of the current data model.
+
+        Example:
+            Inspect properties of the current data model
+            ```python
+            # From an active NeatSession
+            neat.inspect.properties
+            ```
+        """
         return self._state.data_model.last_verified_rule[1].properties.to_pandas()
 
 
@@ -106,6 +136,10 @@ class InspectIssues:
 
 @session_class_wrapper
 class InspectOutcome:
+    """
+    Inspect the outcome after writing a Data Model and Instances to CDF.
+    """
+
     def __init__(self, state: SessionState) -> None:
         self.data_model = InspectUploadOutcome(lambda: state.data_model.last_outcome)
         self.instances = InspectUploadOutcome(lambda: state.instances.last_outcome)

cognite/neat/_session/_mapping.py

@@ -38,6 +38,11 @@ class DataModelMappingAPI:
         If you extend CogniteAsset, with for example, ClassicAsset. You will map the property `parentId` to `parent`.
         If you set `user_parent_property_name` to True, the `parentId` will be renamed to `parent` after the
         mapping is done. If you set it to False, the property will remain `parentId`.
+
+        Example:
+            ```python
+            neat.mapping.classic_to_core(company_prefix="WindFarmX", use_parent_property_name=True)
+            ```
         """
         source_id, rules = self._state.data_model.last_verified_dms_rules
 

cognite/neat/_session/_prepare.py

@@ -1,7 +1,7 @@
 import copy
-from collections.abc import Collection
+from collections.abc import Callable, Collection
 from datetime import datetime, timezone
-from typing import Literal, cast
+from typing import Any, Literal, cast
 
 from cognite.client.data_classes.data_modeling import DataModelIdentifier
 from rdflib import URIRef
@@ -13,6 +13,8 @@ from cognite.neat._constants import (
 )
 from cognite.neat._graph.transformers import (
     AttachPropertyFromTargetToSource,
+    ConvertLiteral,
+    LiteralToEntity,
     PruneDeadEndEdges,
     PruneInstancesOfUnknownType,
     PruneTypes,
@@ -47,6 +49,10 @@ except ImportError:
 
 @session_class_wrapper
 class PrepareAPI:
+    """Apply various operations on the knowledge graph as a necessary preprocessing step before for instance
+    inferring a data model or exporting the knowledge graph to a desired destination.
+    """
+
     def __init__(self, client: NeatClient | None, state: SessionState, verbose: bool) -> None:
         self._state = state
         self._verbose = verbose
@@ -56,6 +62,8 @@ class PrepareAPI:
 
 @session_class_wrapper
 class InstancePrepareAPI:
+    """Operations to perform on instances of data in the knowledge graph."""
+
     def __init__(self, state: SessionState, verbose: bool) -> None:
         self._state = state
         self._verbose = verbose
@@ -63,14 +71,20 @@ class InstancePrepareAPI:
     def dexpi(self) -> None:
         """Prepares extracted DEXPI graph for further usage in CDF
 
-        This method bundles several graph transformers which:
-        - attach values of generic attributes to nodes
-        - create associations between nodes
-        - remove unused generic attributes
-        - remove associations between nodes that do not exist in the extracted graph
-        - remove edges to nodes that do not exist in the extracted graph
+        !!! note "This method bundles several graph transformers which"
+            - attach values of generic attributes to nodes
+            - create associations between nodes
+            - remove unused generic attributes
+            - remove associations between nodes that do not exist in the extracted graph
+            - remove edges to nodes that do not exist in the extracted graph
 
         and therefore safeguard CDF from a bad graph
+
+        Example:
+            Apply Dexpi specific transformations:
+            ```python
+            neat.prepare.instances.dexpi()
+            ```
         """
 
         DEXPI = get_default_prefixes_and_namespaces()["dexpi"]
@@ -104,12 +118,18 @@ class InstancePrepareAPI:
     def aml(self) -> None:
         """Prepares extracted AutomationML graph for further usage in CDF
 
-        This method bundles several graph transformers which:
-        - attach values of attributes to nodes
-        - remove unused attributes
-        - remove edges to nodes that do not exist in the extracted graph
+        !!! note "This method bundles several graph transformers which"
+            - attach values of attributes to nodes
+            - remove unused attributes
+            - remove edges to nodes that do not exist in the extracted graph
 
         and therefore safeguard CDF from a bad graph
+
+        Example:
+            Apply AML specific transformations:
+            ```python
+            neat.prepare.instances.aml()
+            ```
         """
 
         AML = get_default_prefixes_and_namespaces()["aml"]
@@ -162,7 +182,32 @@ class InstancePrepareAPI:
             target value, as follows:
             (SourceType)-[connection]->(TargetType)
 
+        Example:
+            Make connection on exact match:
+            ```python
+            # From an active NeatSession
+            neat.read.csv("workitem.Table.csv",
+                          type = "Activity",
+                          primary_key="sourceId")
+
+            neat.read.csv("assets.Table.csv",
+                          type="Asset",
+                          primary_key="WMT_TAG_GLOBALID")
+
+            # Here we specify what column from the source table we should use when we link it with a column in the
+            # target table. In this case, it is the "workorderItemname" column in the source table
+            source = ("Activity", "workorderItemname")
+
+            # Here we give a name to the new property that is created when a match between the source and target is
+            # found
+            connection = "asset"
+
+            # Here we specify what column from the target table we should use when searching for a match.
+            # In this case, it is the "wmtTagName" column in the target table
+            target = ("Asset", "wmtTagName")
 
+            neat.prepare.instances.make_connection_on_exact_match(source, target, connection)
+            ```
         """
 
         subject_type, subject_predicate = self._get_type_and_property_uris(*source)
@@ -216,9 +261,67 @@ class InstancePrepareAPI:
         transformer = RelationshipAsEdgeTransformer(min_relationship_types, limit_per_type)
         self._state.instances.store.transform(transformer)
 
+    def convert_data_type(self, source: tuple[str, str], *, convert: Callable[[Any], Any] | None = None) -> None:
+        """Convert the data type of the given property.
+
+        This is, for example, useful when you have a boolean property that you want to convert to an enum.
+
+        Args:
+            source: The source of the conversion. A tuple of (type, property)
+                    where property is the property that should be converted.
+            convert: The function to use for the conversion. The function should take the value of the property
+                    as input and return the converted value. Default to assume you have a string that should be
+                    converted to int, float, bool, or datetime.
+
+        Example:
+            Convert a boolean property to a string:
+            ```python
+            neat.prepare.instances.convert_data_type(
+                ("TimeSeries", "isString"),
+                convert=lambda is_string: "string" if is_string else "numeric"
+            )
+            ```
+
+        """
+        subject_type, subject_predicate = self._get_type_and_property_uris(*source)
+
+        transformer = ConvertLiteral(subject_type, subject_predicate, convert)
+        self._state.instances.store.transform(transformer)
+
+    def property_to_type(self, source: tuple[str | None, str], type: str, new_property: str | None = None) -> None:
+        """Convert a property to a new type.
+
+        Args:
+            source: The source of the conversion. A tuple of (type, property)
+                    where property is the property that should be converted.
+                    You can pass (None, property) to covert all properties with the given name.
+            type: The new type of the property.
+            new_property: Add the identifier as a new property. If None, the new entity will not have a property.
+
+        Example:
+            Convert the property 'source' to SourceSystem
+            ```python
+            neat.prepare.instances.property_to_type(
+                (None, "source"), "SourceSystem"
+            )
+            ```
+        """
+        subject_type: URIRef | None = None
+        if source[0] is not None:
+            subject_type, subject_predicate = self._get_type_and_property_uris(*source)  # type: ignore[arg-type, assignment]
+        else:
+            subject_predicate = self._state.instances.store.queries.property_uri(source[1])[0]
+
+        transformer = LiteralToEntity(subject_type, subject_predicate, type, new_property)
+        self._state.instances.store.transform(transformer)
+
 
 @session_class_wrapper
 class DataModelPrepareAPI:
+    """Operations to perform on a data model as part of a workflow before writing the data model
+    to a desired destination.
+    """
+
     def __init__(self, client: NeatClient | None, state: SessionState, verbose: bool) -> None:
         self._client = client
         self._state = state
@@ -288,13 +391,15 @@ class DataModelPrepareAPI:
             move_connections: If True, the connections will be moved to the new data model.
 
         !!! note "Enterprise Data Model Creation"
+
             Always create an enterprise data model from a Cognite Data Model as this will
             assure all the Cognite Data Fusion applications to run smoothly, such as
-            - Search
-            - Atlas AI
-            - ...
+                - Search
+                - Atlas AI
+                - ...
 
         !!! note "Move Connections"
+
             If you want to move the connections to the new data model, set the move_connections
             to True. This will move the connections to the new data model and use new model
             views as the source and target views.
@@ -345,6 +450,7 @@ class DataModelPrepareAPI:
             dummy_property: The dummy property to use as placeholder for the views in the new data model.
 
         !!! note "Solution Data Model Mode"
+
             The read-only solution model will only be able to read from the existing containers
             from the enterprise data model, therefore the solution data model will not have
             containers in the solution data model space. Meaning the solution data model views