cognite-neat 0.101.0__py3-none-any.whl → 0.103.0__py3-none-any.whl

cognite/neat/_rules/models/mapping/_classic2core.yaml

@@ -2,10 +2,12 @@ enum:
 - collection: timeseriesType
   description: Time series with double floating point data points.
   name: numeric
+  neatId: http://purl.org/cognite/neat/neatId_d4e42064_7c60_4bfc_b629_a873345f0ee2
   value: numeric
 - collection: timeseriesType
   description: Time series with string data points.
   name: string
+  neatId: http://purl.org/cognite/neat/neatId_8bb46fae_572d_464a_bc61_1055b0aa6c5d
   value: string
 metadata:
   created: '2024-08-29T13:49:56.696000'
@@ -23,6 +25,7 @@ properties:
   description: Description of the instance
   immutable: false
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_d887305d_af9d_4843_af6e_4115a7217d90
   nullable: true
   value_type: text
   view: ClassicAsset
@@ -32,6 +35,7 @@ properties:
   description: Text based labels for generic use, limited to 1000
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_105a0fee_3942_4a6b_9d25_74d46d09c209
   nullable: true
   value_type: text
   view: ClassicAsset
@@ -42,6 +46,7 @@ properties:
   immutable: false
   index: name
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_9559ecd6_a585_4fb9_90b7_7301da5f2170
   nullable: true
   value_type: text
   view: ClassicAsset
@@ -53,6 +58,7 @@ properties:
   immutable: false
   is_list: false
   name: Parent
+  neatId: http://purl.org/cognite/neat/neatId_fdc3280b_0d11_4e66_b2b5_8f37a398bed9
   nullable: true
   value_type: ClassicAsset
   view: ClassicAsset
@@ -64,8 +70,9 @@ properties:
   immutable: false
   index: source
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_247e5b5d_4caf_4312_bd5b_341ed3fc3a03
   nullable: true
-  value_type: cdf_cdm:CogniteSourceSystem(version=v1)
+  value_type: ClassicSourceSystem
   view: ClassicAsset
   view_property: source
 - container: cdf_cdm:CogniteDescribable
@@ -73,6 +80,7 @@ properties:
   description: Alternative names for the node
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_7412eae6_e77c_41b7_92ca_737798f5844a
   nullable: true
   value_type: text
   view: ClassicEvent
@@ -84,6 +92,7 @@ properties:
   immutable: false
   is_list: true
   name: Assets
+  neatId: http://purl.org/cognite/neat/neatId_439538ba_610d_4300_a8cd_aa51dbbf5c1a
   nullable: true
   value_type: ClassicAsset
   view: ClassicEvent
@@ -93,6 +102,7 @@ properties:
   description: Description of the instance
   immutable: false
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_8ab69b21_b84e_4374_a2bd_6b7e6321f22d
   nullable: true
   value_type: text
   view: ClassicEvent
@@ -103,6 +113,7 @@ properties:
   immutable: false
   index: endTime
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_fce69deb_af37_4c49_b1cf_caf569563ba7
   nullable: true
   value_type: timestamp
   view: ClassicEvent
@@ -112,6 +123,7 @@ properties:
   description: Text based labels for generic use, limited to 1000
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_0ed58b00_11ab_4774_9c66_d2eabc5f8f42
   nullable: true
   value_type: text
   view: ClassicEvent
@@ -123,8 +135,9 @@ properties:
   immutable: false
   index: source
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_b0c7d726_6504_4189_896d_1b978d9ef5b2
   nullable: true
-  value_type: cdf_cdm:CogniteSourceSystem(version=v1)
+  value_type: ClassicSourceSystem
   view: ClassicEvent
   view_property: source
 - container: cdf_cdm:CogniteSchedulable
@@ -133,6 +146,7 @@ properties:
   immutable: false
   index: startTime
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_2304763f_d0f3_4723_a4c5_2e879069195d
   nullable: true
   value_type: timestamp
   view: ClassicEvent
@@ -144,6 +158,7 @@ properties:
   immutable: false
   is_list: true
   name: Assets
+  neatId: http://purl.org/cognite/neat/neatId_77ec0da0_839b_4b52_9f64_35382213dac6
   nullable: true
   value_type: ClassicAsset
   view: ClassicFile
@@ -155,6 +170,7 @@ properties:
   immutable: false
   is_list: false
   name: Directory
+  neatId: http://purl.org/cognite/neat/neatId_f06ff883_4f00_4a5d_b9c3_83664b62b573
   nullable: true
   value_type: text
   view: ClassicFile
@@ -164,6 +180,7 @@ properties:
   description: Text based labels for generic use, limited to 1000
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_5d721016_c99e_4f73_8e9d_bdd27b4472c3
   nullable: true
   value_type: text
   view: ClassicFile
@@ -174,6 +191,7 @@ properties:
   immutable: false
   is_list: false
   name: MIME type
+  neatId: http://purl.org/cognite/neat/neatId_d65bd20a_bcb9_4243_b3e9_06188378c4cc
   nullable: true
   value_type: text
   view: ClassicFile
@@ -184,6 +202,7 @@ properties:
   immutable: false
   index: name
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_793d1480_2fba_4dde_8325_c11ef7e57de5
   nullable: true
   value_type: text
   view: ClassicFile
@@ -195,8 +214,9 @@ properties:
   immutable: false
   index: source
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_87aa809b_a7cc_4136_885c_276844ed6b38
   nullable: true
-  value_type: cdf_cdm:CogniteSourceSystem(version=v1)
+  value_type: ClassicSourceSystem
   view: ClassicFile
   view_property: source
 - container: cdf_cdm:CogniteSourceable
@@ -205,6 +225,7 @@ properties:
   immutable: false
   index: sourceCreatedTime
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_26b7346d_3d5f_43a5_894e_96707e89227c
   nullable: true
   value_type: timestamp
   view: ClassicFile
@@ -215,10 +236,20 @@ properties:
   immutable: false
   index: sourceUpdatedTime
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_4b6be7c8_8b26_4f11_9ad5_283123a54c91
   nullable: true
   value_type: timestamp
   view: ClassicFile
   view_property: sourceModifiedTime
+- container: cdf_cdm:CogniteDescribable
+  container_property: name
+  immutable: false
+  is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_7d7c614a_43ea_4fc2_abb0_3f3fdddaa239
+  nullable: true
+  value_type: text
+  view: ClassicSourceSystem
+  view_property: name
 - connection: direct
   container: cdf_cdm:CogniteTimeSeries
   container_property: assets
@@ -226,6 +257,7 @@ properties:
   immutable: false
   is_list: true
   name: Assets
+  neatId: http://purl.org/cognite/neat/neatId_bc4e12b0_82bd_4859_995d_d219181f9b52
   nullable: true
   value_type: ClassicAsset
   view: ClassicTimeSeries
@@ -235,6 +267,7 @@ properties:
   description: Description of the instance
   immutable: false
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_73372a76_aa52_47c1_bdae_34bfbd80f572
   nullable: true
   value_type: text
   view: ClassicTimeSeries
@@ -246,6 +279,7 @@ properties:
   immutable: false
   is_list: false
   name: Is step
+  neatId: http://purl.org/cognite/neat/neatId_cfa476ae_125b_4e6a_8caf_152f44095037
   nullable: false
   value_type: boolean
   view: ClassicTimeSeries
@@ -256,6 +290,7 @@ properties:
   immutable: true
   is_list: false
   name: Type
+  neatId: http://purl.org/cognite/neat/neatId_7943437b_6138_47e6_889a_f414280df48e
   nullable: false
   value_type: enum(collection=timeseriesType)
   view: ClassicTimeSeries
@@ -265,6 +300,7 @@ properties:
   description: Alternative names for the node
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_15cfc454_8fc0_443b_8af6_9db5368d6fd4
   nullable: true
   value_type: text
   view: ClassicTimeSeries
@@ -275,6 +311,7 @@ properties:
   immutable: false
   index: name
   is_list: false
+  neatId: http://purl.org/cognite/neat/neatId_01370dd7_3371_40a1_b4eb_ddfcbbac63c8
   nullable: true
   value_type: text
   view: ClassicTimeSeries
@@ -284,6 +321,7 @@ properties:
   description: Text based labels for generic use, limited to 1000
   immutable: false
   is_list: true
+  neatId: http://purl.org/cognite/neat/neatId_d7e122ee_421a_490f_9bec_b0f9f5ececfd
   nullable: true
   value_type: text
   view: ClassicTimeSeries
@@ -294,6 +332,7 @@ properties:
   immutable: false
   is_list: false
   name: Source unit
+  neatId: http://purl.org/cognite/neat/neatId_3bfc11e0_9d27_47ea_841e_de1e4363dbed
   nullable: true
   value_type: text
   view: ClassicTimeSeries
@@ -305,39 +344,46 @@ properties:
   immutable: false
   is_list: false
   name: Unit
+  neatId: http://purl.org/cognite/neat/neatId_33b75362_e127_4a5a_9690_2df55501250c
   nullable: true
   value_type: cdf_cdm:CogniteUnit(version=v1)
   view: ClassicTimeSeries
   view_property: unitExternalId
 views:
-- description: The CogniteSourceSystem core concept is used to standardize the way
-    source system is stored.
-  implements: cdf_cdm:CogniteDescribable(version=v1)
-  in_model: true
-  view: cdf_cdm:CogniteSourceSystem(version=v1)
 - description: Represents a single unit of measurement
   implements: cdf_cdm:CogniteDescribable(version=v1)
   in_model: true
+  neatId: http://purl.org/cognite/neat/neatId_f3397b4c_b6e0_4701_8ea3_7edbf72bf50d
   view: cdf_cdm:CogniteUnit(version=v1)
 - description: Assets represent systems that support industrial functions or processes.
     Assets are often called 'functional location'.
   implements: cdf_cdm:CogniteAsset(version=v1)
   in_model: true
   name: Asset
+  neatId: http://purl.org/cognite/neat/neatId_23380192_0c8a_4870_9684_cb91e5e5d67d
   view: ClassicAsset
 - description: Represents activities. Activities typically happen over a period and
     have a start and end time.
   implements: cdf_cdm:CogniteActivity(version=v1)
   in_model: true
   name: Activity
+  neatId: http://purl.org/cognite/neat/neatId_3c0bda0e_9af0_4c75_9f1c_d76a6eae2e44
   view: ClassicEvent
 - description: Represents files.
   implements: cdf_cdm:CogniteFile(version=v1)
   in_model: true
   name: File
+  neatId: http://purl.org/cognite/neat/neatId_4a92bfcc_a259_4ec6_b58b_bdb386ba9ce2
   view: ClassicFile
+- description: The CogniteSourceSystem core concept is used to standardize the way
+    source system is stored.
+  implements: cdf_cdm:CogniteSourceSystem(version=v1)
+  in_model: true
+  neatId: http://purl.org/cognite/neat/neatId_280264e2_a809_4feb_81e3_454adc00fdde
+  view: ClassicSourceSystem
 - description: Represents a series of data points in time order.
   implements: cdf_cdm:CogniteTimeSeries(version=v1)
   in_model: true
   name: Time series
+  neatId: http://purl.org/cognite/neat/neatId_0730d4f7_51ce_40de_a8af_b9efff498b06
   view: ClassicTimeSeries

cognite/neat/_rules/transformers/__init__.py

@@ -14,21 +14,21 @@ from ._pipelines import ImporterPipeline
 from ._verification import VerifyAnyRules, VerifyDMSRules, VerifyInformationRules
 
 __all__ = [
-    "ImporterPipeline",
-    "RulesTransformer",
-    "RulesPipeline",
-    "InformationToDMS",
+    "AsParentPropertyId",
     "ConvertToRules",
-    "PrefixEntities",
     "DMSToInformation",
-    "VerifyDMSRules",
-    "VerifyInformationRules",
-    "VerifyAnyRules",
+    "ImporterPipeline",
+    "InformationToDMS",
     "MapOneToOne",
-    "ToCompliantEntities",
-    "RuleMapper",
-    "ToExtension",
+    "PrefixEntities",
     "ReduceCogniteModel",
+    "RuleMapper",
+    "RulesPipeline",
+    "RulesTransformer",
     "SetIDDMSModel",
-    "AsParentPropertyId",
+    "ToCompliantEntities",
+    "ToExtension",
+    "VerifyAnyRules",
+    "VerifyDMSRules",
+    "VerifyInformationRules",
 ]

cognite/neat/_rules/transformers/_pipelines.py

@@ -1,28 +1,33 @@
 from collections.abc import Iterable
+from typing import TYPE_CHECKING
 
 from cognite.neat._issues.errors import NeatValueError
 from cognite.neat._rules._shared import InputRules, MaybeRules, VerifiedRules
-from cognite.neat._rules.importers import BaseImporter
 from cognite.neat._rules.models import VERIFIED_RULES_BY_ROLE, RoleTypes
 
 from ._base import RulesPipeline, RulesTransformer
 from ._converters import ConvertToRules
 from ._verification import VerifyAnyRules
 
+if TYPE_CHECKING:
+    from cognite.neat._rules.importers import BaseImporter
+
 
 class ImporterPipeline(RulesPipeline[InputRules, VerifiedRules]):
     """This is a standard pipeline that verifies, convert and return the rules from the importer."""
 
     def __init__(
         self,
-        importer: BaseImporter[InputRules],
+        importer: "BaseImporter[InputRules]",
         items: Iterable[RulesTransformer[InputRules, VerifiedRules]] | None = None,
     ) -> None:
         super().__init__(items or [])
         self._importer = importer
 
     @classmethod
-    def _create_pipeline(cls, importer: BaseImporter[InputRules], role: RoleTypes | None = None) -> "ImporterPipeline":
+    def _create_pipeline(
+        cls, importer: "BaseImporter[InputRules]", role: RoleTypes | None = None
+    ) -> "ImporterPipeline":
         items: list[RulesTransformer] = [VerifyAnyRules(errors="continue", validate=True)]
         if role is not None:
             out_cls = VERIFIED_RULES_BY_ROLE[role]
@@ -30,7 +35,7 @@ class ImporterPipeline(RulesPipeline[InputRules, VerifiedRules]):
         return cls(importer, items)
 
     @classmethod
-    def try_verify(cls, importer: BaseImporter, role: RoleTypes | None = None) -> MaybeRules[VerifiedRules]:
+    def try_verify(cls, importer: "BaseImporter", role: RoleTypes | None = None) -> MaybeRules[VerifiedRules]:
         """This is a standard pipeline that verifies, convert and return the rules from the importer.
 
         Args:
@@ -43,7 +48,7 @@ class ImporterPipeline(RulesPipeline[InputRules, VerifiedRules]):
         return cls._create_pipeline(importer, role).try_execute()
 
     @classmethod
-    def verify(cls, importer: BaseImporter, role: RoleTypes | None = None) -> VerifiedRules:
+    def verify(cls, importer: "BaseImporter", role: RoleTypes | None = None) -> VerifiedRules:
         """Verify the rules."""
         return cls._create_pipeline(importer, role).execute()
 

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