diff --git a/doc/rtd/conf.py b/doc/rtd/conf.py index eea0a55f6..79fca461c 100644 --- a/doc/rtd/conf.py +++ b/doc/rtd/conf.py @@ -23,7 +23,7 @@ author = "blueAIC" # The full version, including alpha/beta/rc tags -release = "2.2.1" +release = "2.3.0" # -- General configuration --------------------------------------------------- diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/01_event_handling.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/01_event_handling.rst index 141c0d6f6..2ddbf7924 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/01_event_handling.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/01_event_handling.rst @@ -3,18 +3,138 @@ Event handling ============== -Event handling is a widely used standard technique in software development. And that's how it found its way into MLPro. -The mechanism is inherited by higher classes in the form of the property class **EventHandler**. This class allows -event handler methods to be registered and events to be triggered, which in turn call registered handlers. An object of -type **Event** is passed to each handler. This contains further information about the context of the event. +Event handling is a fundamental mechanism in MLPro. It decouples the object that detects a state +transition from the objects that react to it. The generic implementation is provided by +``mlpro.bf.events`` and is reused by higher layers such as multitasking, stream processing, and +machine learning. -The event handling functionality is used extensively in MLPro. A large number of higher classes use this mechanism. -Based on this, even an event-oriented adaptation mechanism is cultivated in -:ref:`Layer 4 - Machine Learning `. +The central classes are ``Event``, ``EventManager``, ``EventConfig``, and ``EventMode``. +Event identifiers use the type alias ``EventId`` and are represented by strings. + +Event ids and handlers +---------------------- + +An event-capable class derives from ``EventManager`` and raises events under a unique event id. +Handlers can register for a particular id and are called whenever the event is dispatched. + +.. code-block:: python + + from mlpro.bf.events import Event, EventId, EventManager + + + class Producer(EventManager): + + C_EVENT_CHANGED: EventId = 'CHANGED' + + def change(self): + event = Event(p_raising_object=self) + self._raise_event( + p_event_id=self.C_EVENT_CHANGED, + p_event_object=event, + ) + + + def handler(p_event_id, p_event_object): + print(p_event_id, p_event_object.get_raising_object()) + + + producer = Producer() + producer.register_event_handler( + p_event_id=Producer.C_EVENT_CHANGED, + p_event_handler=handler, + ) + producer.change() + +The ``Event`` object transports the raising object, a time stamp, and optional event-specific +keyword data to all registered handlers. + +Configurable events +------------------- + +Event generation can be configured with ``EventConfig``. Concrete event-capable implementations +define their own child class and add one attribute per configurable event. + +By convention, event ids and their corresponding configuration attributes are written in **upper +case** and are **identical**. This keeps the relationship transparent and allows an implementation +to query a mode directly by event id. + +.. code-block:: python + + from dataclasses import dataclass + + from mlpro.bf.events import EventConfig, EventMode + + + @dataclass + class ProducerEvents(EventConfig): + + CHANGED: EventMode = EventMode.EVENT + + + config = ProducerEvents( + CHANGED=EventMode.OFF, + ) + +The generic modes are: + +``EventMode.OFF`` + The event is disabled. + +``EventMode.EVENT`` + The event is enabled and may be raised. + +The configuration is optional. If no ``EventConfig`` object is supplied, MLPro preserves the +historic behavior and ``_get_event_mode()`` returns ``EventMode.EVENT`` for every queried event id. + +If a configuration object is supplied, every queried event id must have a matching attribute. +A mismatch indicates an implementation error and raises ``ImplementationError``. The concrete +event-capable implementation is responsible for maintaining the convention between event ids and +configuration attributes. + +Efficient event creation +------------------------ + +The event mode should be queried **before** creating the ``Event`` object. This is important for +events that may occur at high frequency: a disabled event should cause virtually no runtime overhead. + +.. code-block:: python + + class Producer(EventManager): + + C_EVENT_CHANGED: EventId = 'CHANGED' + + def change(self): + + if self._get_event_mode(self.C_EVENT_CHANGED) == EventMode.OFF: + return + + self._raise_event( + p_event_id=self.C_EVENT_CHANGED, + p_event_object=Event(p_raising_object=self), + ) + +``_raise_event()`` deliberately does not evaluate the event configuration. At that point the event +object already exists. Its task is only to look up the registered handlers and dispatch the event. + +The dispatcher is intentionally lightweight and silent. Event handling itself does not perform +routine logging. + +Higher-level event modes +------------------------ + +Higher MLPro layers may extend the event-mode semantics without changing the generic event +infrastructure. In :ref:`Layer 4 - Machine Learning `, for example, +``EventModeML`` adds the mode ``ADAPTATION``. This allows a concrete ML implementation to +distinguish between a normal event and an event that shall additionally count as a model adaptation. + +The interpretation of such higher-level modes remains the responsibility of the concrete +implementation. ``EventManager`` itself only provides the generic event configuration, handler +registration, and event dispatch mechanisms. **Cross reference** - :ref:`Howto BF-EH-001: Event handling ` +- :ref:`BF-MT - Multitasking ` +- :ref:`Layer 4 - Machine Learning ` - :ref:`API reference BF-EVENTS - Event handling ` - diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/02_multitasking.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/02_multitasking.rst index 312b8c378..ec7f918a7 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/02_multitasking.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer1_computation/02_multitasking.rst @@ -47,6 +47,8 @@ relationships. Successor tasks are informed about the termination of their prede consistently reused in higher functions through inheritance. Some examples are :ref:`Stream Processing ` and the :ref:`Adaptive Workflows `. +``Task`` integrates ``EventManager`` and therefore accepts the optional parameter ``p_event_config``. This provides a common configuration channel for event-capable task subclasses. Such subclasses can query ``_get_event_mode()`` before constructing an event object and thereby suppress disabled events without unnecessary object creation. The built-in ``C_EVENT_FINISHED`` event continues to coordinate predecessor/successor execution in workflows. + **Gap under MacOS** diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer2_mathematics/01_normalizers.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer2_mathematics/01_normalizers.rst index 468c15df9..07109f565 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer2_mathematics/01_normalizers.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer2_mathematics/01_normalizers.rst @@ -8,13 +8,21 @@ Why normalization? Many algorithms become easier to combine and numerically more stable when their input features live on comparable scales. A temperature in degrees, a position in meters, and a probability may all describe the same sample, but their numerical ranges can differ by orders of magnitude. -MLPro treats normalization as a reversible mapping rather than as a one-way preprocessing step. The common abstraction is **Normalizer**, which builds on :class:`Scaler` and therefore supports normalization, denormalization, and renormalization with a consistent parameter model. +MLPro treats normalization as a reversible mapping rather than as a one-way preprocessing step. The abstract **NormalizerAPI** defines the common interface for normalization, denormalization, and renormalization. The base class **Normalizer** implements this interface and extends :class:`Scaler` with a consistent linear parameter model. + +**NormalizerAPI** declares three abstract operations: + +* ``normalize(p_data, p_dim=None, p_param=None)`` maps data into normalized coordinates, +* ``denormalize(p_data, p_dim=None, p_param=None)`` maps normalized data back to their original coordinates, +* ``renormalize(p_data, p_dim=None, p_param_old=None, p_param_new=None)`` transforms normalized data from one parameter set to another. + +The interface is independent of the normalization strategy. Concrete implementations provide the normalization behavior and parameter management. The optional ``p_dim`` argument selects a single dimension; parameter arguments allow explicit parameter sets where supported. The basic lifecycle is: ``raw data -> determine parameters -> normalize -> parameters change -> renormalize`` -All normalizers use linear parameters per dimension. Internally, each dimension has a scale factor and an offset. This common representation enables the same operations for different normalization strategies: +The supplied MLPro normalizers use linear parameters per dimension. Internally, each dimension has a scale factor and an offset. This common representation enables the same operations for different normalization strategies: * ``normalize()`` maps original data into normalized coordinates, * ``denormalize()`` reconstructs data in the original coordinates, diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/02_stream_processing.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/02_stream_processing.rst index 458aaba63..97e53c763 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/02_stream_processing.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/02_stream_processing.rst @@ -23,6 +23,8 @@ The instance dictionary carried through a workflow does not only contain data ob A StreamWorkflow builds on MLPro's multitasking layer. Independent branches can therefore be executed according to their predecessor dependencies and configured range of asynchronicity, while the shared object provides task-specific results and instance sets. +``StreamTask`` also inherits MLPro's event-management infrastructure and forwards the optional ``p_event_config`` parameter to its underlying ``Task``. Stream-processing implementations can therefore expose their own configurable events without introducing a separate callback mechanism. As elsewhere in MLPro, the event mode should be queried before creating the corresponding event object. + The detailed page shows how to implement own StreamTasks, connect them to workflows, and orchestrate them with StreamScenario. diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/stream_processing/stream_processing.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/stream_processing/stream_processing.rst index b234b6685..a8764c4ff 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/stream_processing/stream_processing.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer3_application_support/streams/stream_processing/stream_processing.rst @@ -34,6 +34,8 @@ A custom task usually only needs to specialize ``_run()``: ``StreamTask.run()`` handles integration with the shared workflow state. If ``p_duplicate_data=True`` is configured, the incoming instances are copied before processing; otherwise a task works on the objects forwarded by its predecessors. +**Event configuration.** ``StreamTask`` inherits ``EventManager`` through ``Task`` and accepts an optional ``p_event_config``. A concrete stream task can therefore define implementation-specific events using an ``EventConfig`` child class. The task should call ``_get_event_mode()`` before constructing an ``Event`` object. This is especially useful for stream events that may occur once per instance, because disabled events can then be skipped without object-creation overhead. + **Shared processing state.** After a task has run, its resulting instance dictionary is stored in the workflow's **StreamShared** object under the task id. A dependent task retrieves the instance sets of its predecessor tasks from this shared object. This gives every task a well-defined input while still allowing the workflow to coordinate parallel branches. Stream workflows diff --git a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer4_machine_learning/01_model.rst b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer4_machine_learning/01_model.rst index f4c3c436f..5c9aa284e 100644 --- a/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer4_machine_learning/01_model.rst +++ b/doc/rtd/content/02_basic_functions/mlpro_bf/sub/layer4_machine_learning/01_model.rst @@ -33,6 +33,17 @@ Core capabilities distinguishes regular forward adaptation from event-triggered adaptation. Other ML objects can register handlers and react to these events, enabling adaptation chains between cooperating models. +**Configurable model events** + ``Model`` accepts the optional ``p_event_config`` parameter inherited from ``EventManager``. Concrete model implementations + can define their own ``EventConfig`` child classes and use ``EventModeML`` for the individual switches. ``EventModeML`` + extends the generic modes ``OFF`` and ``EVENT`` by ``ADAPTATION``. The latter expresses that the concrete event shall be + emitted and shall additionally count as a model adaptation. The concrete model is responsible for evaluating this mode and + integrating it into its adaptation logic; the generic ``EventManager`` does not interpret ML-specific modes. + + As in the generic event layer, event ids and their matching configuration attributes are written in upper case and are + expected to be identical. The mode should be queried before an ``Event`` object is created, so that disabled high-frequency + events do not cause avoidable runtime overhead. + **Execution and multitasking** Because ``Model`` is a ``Task``, a model can execute synchronously or within MLPro's asynchronous task infrastructure. Range, autorun, shared-object, and visualization concepts therefore apply to ML models as they do to other BF tasks. diff --git a/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/01_overview.rst b/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/01_overview.rst index bf0ebcb55..07e34ec49 100644 --- a/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/01_overview.rst +++ b/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/01_overview.rst @@ -64,6 +64,10 @@ may change the observed data range, an adaptive normalizer can react to the new renormalize buffered state. Adaptation therefore becomes a property of the complete processing chain rather than an isolated method call inside one algorithm. +``OAStreamTask`` also receives the optional ``p_event_config`` parameter through its ``Model`` and ``StreamTask`` parents. Concrete online-adaptive algorithms can therefore expose implementation-specific events and configure them with ``EventModeML``. The modes ``OFF`` and ``EVENT`` control event emission, while ``ADAPTATION`` allows an implementation to treat a specific event additionally as a model adaptation. MLPro deliberately leaves the interpretation of this third mode to the concrete algorithm. + +For efficient online processing, an implementation should query the configured mode before creating the event object. This makes it practical to offer even high-frequency events, such as per-instance state transitions, without imposing the same overhead when the event is disabled. + OA workflows are intentionally hybrid. A workflow may contain adaptive OA tasks and ordinary BF stream tasks side by side. This is useful because not every processing step needs to learn. Rearranging dimensions, buffering a window, deriving features, or other deterministic processing can remain in BF-Streams while only selected stages adapt online. diff --git a/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/20_cluster_analysis.rst b/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/20_cluster_analysis.rst index c0165c977..0164fd139 100644 --- a/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/20_cluster_analysis.rst +++ b/doc/rtd/content/03_machine_learning/mlpro_oa/sub/streams/20_cluster_analysis.rst @@ -11,19 +11,22 @@ observations may disappear from the active context. In its current development s **standardized framework and templates for implementing custom online cluster analyzers** rather than a broad collection of ready-to-use clustering algorithms. -The current architecture separates the cluster-analysis contract, reusable cluster-management infrastructure, and integration -into an online-adaptive stream task. Three classes are central: +The cluster-analysis architecture is deliberately split into a lightweight core and optional standard MLPro infrastructure. This +allows high-performance implementations to reuse the common clustering contract without depending on MLPro's generic property +model. -- ``ClusterActions`` defines the common public API through which cluster-based functionality can access a current cluster model. -- ``ClusterInfrastructure`` implements reusable, task-internal handling of clusters, properties, memberships, influences, and - cluster lifecycle operations. -- ``ClusterAnalyzer`` combines that infrastructure with ``OAStreamTask`` and thereby turns a concrete clustering algorithm into - an online-adaptive stream-processing task. +Four classes are central: -This separation is important for custom implementations. A component that only needs to consume cluster results can depend on -``ClusterActions`` instead of a particular analyzer implementation, while analyzer developers can reuse -``ClusterInfrastructure`` for the common mechanics of cluster handling and concentrate their own implementation on the actual -clustering algorithm. +- ``ClusterActions`` defines the common public API for access to a current cluster model. +- ``ClusterAnalyzer`` combines this contract with ``OAStreamTask`` and provides the lightweight online-adaptive task layer. +- ``ClusterInfrastructure`` provides reusable standard MLPro mechanics for cluster storage, ids, limits, properties, memberships, + influences, and cluster lifecycle operations. +- ``ClusterAnalyzerExt`` combines ``ClusterAnalyzer`` and ``ClusterInfrastructure`` and therefore represents the convenient + standard MLPro implementation. + +This separation is intentional. Specialized analyzers may derive directly from ``ClusterAnalyzer`` and provide their own cluster +representation and management, while conventional MLPro implementations can use ``ClusterAnalyzerExt`` and the generic property +infrastructure. ClusterActions: common cluster-analysis API @@ -40,15 +43,30 @@ The two principal operations are: Both operations use the common ``ResultItem`` representation consisting of a cluster id, a result value, and the corresponding cluster object. Result scopes allow callers either to inspect all applicable clusters or to request only the strongest result. -For integrations, this class is therefore the preferred API boundary whenever a consumer needs cluster information without -requiring the full adaptive task interface of ``ClusterAnalyzer``. +For integrations, this class is the preferred API boundary whenever a consumer needs cluster information without requiring the +full adaptive task interface. -ClusterInfrastructure: reusable cluster handling +ClusterAnalyzer: lightweight adaptive task layer ------------------------------------------------ -``ClusterInfrastructure`` implements the common mechanics behind cluster-based tasks. It derives from ``ClusterActions`` and -provides the standardized internal machinery needed by cluster analyzers and potentially other cluster-oriented components. +``ClusterAnalyzer`` combines ``OAStreamTask`` and ``ClusterActions``. It deliberately does **not** prescribe how clusters are +implemented, stored, created, or removed. + +A specialized analyzer can therefore reuse MLPro-OA's stream-task lifecycle, adaptivity, event handling, visualization hooks, +workflow integration, and forward/reverse adaptation while implementing its own cluster-management strategy. This is particularly +important for high-performance implementations where the generic MLPro property infrastructure would introduce unnecessary +runtime overhead. + +``ClusterAnalyzer`` forwards incoming stream data to the adaptive model and integrates cluster visualization and renormalization +at task level. The concrete cluster implementation remains responsible for supporting the corresponding operations. + + +ClusterInfrastructure: reusable standard MLPro mechanics +-------------------------------------------------------- + +``ClusterInfrastructure`` is a task-independent mixin that implements the standard MLPro mechanics behind conventional cluster +analyzers. It derives from ``ClusterActions`` but does not itself introduce ``Task``, ``StreamTask``, or ``OAStreamTask`` semantics. Its responsibilities include: @@ -60,48 +78,65 @@ Its responsibilities include: - result scopes and optional influence thresholds; - access to the configured cluster class. -The architectural intention is to keep these recurring concerns out of the concrete clustering algorithm. An implementation can -therefore focus on *when* and *how* its model changes, while ``ClusterInfrastructure`` standardizes *how clusters are represented, -managed, and queried* inside the task. +The infrastructure can therefore be combined with a compatible task layer where these generic mechanisms are desired, but it is +not mandatory for every cluster analyzer. -ClusterAnalyzer: adaptive stream-task integration -------------------------------------------------- +ClusterAnalyzerExt: standard MLPro combination +---------------------------------------------- -``ClusterAnalyzer`` combines ``OAStreamTask`` and ``ClusterInfrastructure``. It is the common adaptive template for online -clustering in an ``OAStreamWorkflow``. +``ClusterAnalyzerExt`` combines the lightweight ``ClusterAnalyzer`` with ``ClusterInfrastructure``. It is the convenient base +class for conventional MLPro cluster analyzers that use the standard cluster model and property infrastructure. -A concrete analyzer supplies the algorithm-specific adaptation behavior for newly arriving and obsolete instances. The inherited -infrastructure provides the cluster model and cluster operations, while ``OAStreamTask`` contributes the common OA lifecycle, -execution model, adaptivity switch, workflow integration, and event-driven interaction with other stream tasks. - -``ClusterAnalyzer`` additionally integrates cluster visualization and renormalization. If an upstream adaptive normalizer changes -its parameters, the maintained cluster model can be renormalized so that its geometric representation remains consistent with the -new coordinate system. - -The resulting responsibility split can be summarized as:: +The responsibility split can be summarized as:: consumer / downstream component | v ClusterActions common query API - ^ - | - ClusterInfrastructure - common cluster mechanics - ^ - | - ClusterAnalyzer - OAStreamTask integration - ^ - | - concrete algorithm - _adapt() / _adapt_reverse() + ^ ^ + | | + | ClusterInfrastructure + | standard MLPro mechanics + | ^ + | | + ClusterAnalyzer + OA task layer + ^ ^ + | | + specialized ClusterAnalyzerExt + high-speed standard MLPro stack + analyzer + +This structure keeps the core clustering contract reusable while preserving the richer MLPro implementation as an optional layer. -``ClusterAnalyzer`` therefore does not solve the clustering problem by itself. It defines the standardized environment in which -application-specific or third-party online clustering algorithms can be implemented consistently. +Event configuration +------------------- + +Cluster analyzers use ``EventConfigCA`` as their specific event configuration. It extends the generic MLPro event configuration by +the two cluster-lifecycle events ``CLUSTER_ADDED`` and ``CLUSTER_REMOVED``. Both are disabled by default and can be enabled +individually by the embedding application. + +The event configuration belongs to the analyzer layer and can be extended by specialized implementations with additional +domain-specific events. + + +Cluster model +------------- + +The cluster model follows the same lightweight-versus-rich separation. + +``ClusterAPI`` is the minimal abstract cluster API. It provides cluster identity, optional plot support, and the two +generic relation operations ``get_membership()`` and ``get_influence()``. It is deliberately independent of MLPro's generic +``Properties`` model. + +``Cluster`` extends ``ClusterAPI`` with ``Properties`` and ``KWArgs`` and remains the standard MLPro cluster template. Further +specializations such as ``ClusterCentroid`` and ``ClusterBody`` build on this richer model. + +This gives specialized high-performance analyzers a clean option to implement or derive directly from ``ClusterAPI`` while conventional MLPro +algorithms can continue to use the property-based ``Cluster`` hierarchy. Benchmarking with native BF-Streams ----------------------------------- @@ -112,7 +147,7 @@ They can generate known static or dynamic cluster structures in configurable dim This creates a useful separation between **benchmark definition** and **analyzer implementation**: BF-Streams defines controlled input scenarios, while OA-Streams standardizes how an online cluster analyzer represents, updates, and exposes its cluster model. -A custom ``ClusterAnalyzer`` can therefore be tested repeatedly against the same benchmark stream and compared with alternative +A custom cluster analyzer can therefore be tested repeatedly against the same benchmark stream and compared with alternative implementations under equivalent conditions. Single-cluster scenarios are useful for validating basic model behavior, membership semantics, and adaptation to movement or size @@ -150,16 +185,13 @@ A few representative benchmark scenarios are shown below. The complete visual be Cluster model and properties ---------------------------- -Clusters are first-class objects rather than anonymous labels. The cluster-analysis package defines a reusable cluster model with -``Cluster``, cluster identifiers, centroid- and body-oriented specializations, and extensible cluster properties. - -Algorithms declare the properties they maintain through ``C_CLUSTER_PROPERTIES``. New clusters can receive those definitions, -and property settings can be aligned with external consumers. The native property pool includes reusable concepts around cluster -centroids and bodies as well as derived properties such as **density** and **deformation index**. - -Because the property mechanism builds on the generic BF-Math property abstractions, cluster metadata can be extended without -changing the common ``ClusterActions`` API or the fundamental analyzer lifecycle. +The standard MLPro cluster hierarchy remains property-based. Algorithms using ``ClusterInfrastructure`` can declare the +properties they maintain through ``C_CLUSTER_PROPERTIES``. New clusters can receive those definitions, and property settings +can be aligned with external consumers. The native property pool includes reusable concepts around cluster centroids and bodies +as well as derived properties such as **density** and **deformation index**. +This property layer is optional: lightweight implementations can derive their cluster objects directly from ``ClusterAPI`` +without carrying the generic property machinery. Forward and reverse adaptation ------------------------------ @@ -186,15 +218,14 @@ current cluster model can program against ``ClusterActions`` instead of dependin A typical architecture is:: - Stream -> adaptive preprocessing -> ClusterAnalyzer -> cluster-based consumer - | | - | +-> ClusterActions API - +-> cluster model / properties - -This makes clustering a reusable adaptive model inside a larger processing chain while keeping the actual clustering algorithm -replaceable. Cluster-based change detection is still under development and should therefore be regarded as an evolving -integration area rather than mature ready-to-use functionality. + Stream -> adaptive preprocessing -> ClusterAnalyzer-based task -> cluster-based consumer + | | + | +-> ClusterActions API + +-> lightweight or standard cluster model +This makes clustering a reusable adaptive model inside a larger processing chain while keeping both the clustering algorithm and +its internal cluster representation replaceable. Cluster-based change detection is still under development and should therefore +be regarded as an evolving integration area rather than mature ready-to-use functionality. **Cross reference** diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/.$MLPro-BF-MT_class_diagram.drawio.bkp b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/.$MLPro-BF-MT_class_diagram.drawio.bkp new file mode 100644 index 000000000..9c6837c9c --- /dev/null +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/.$MLPro-BF-MT_class_diagram.drawio.bkp @@ -0,0 +1 @@ +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 \ No newline at end of file diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio index d5331cd27..509936ef5 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio @@ -1,104 +1,129 @@ - + - + - + - - - + + + + + + - - + + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - + + + + - - + + + - - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio.png index 674b7f212..8ebeca281 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-Events_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio index 9c6837c9c..c3ff04c03 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio @@ -1 +1,390 @@ -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 \ No newline at end of file + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio.png index 42a7f3dc5..0379dba78 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer1_computation/images/MLPro-BF-MT_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio index 981ea0802..c8b1e3972 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio @@ -1,144 +1,158 @@ - + - + - - - - + + - - + + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - + + + + - - + + + - - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio.png index f44d60cb5..2961720b2 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer2_mathematics/images/MLPro-BF-Math-Normalizers_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/.$MLPro-BF-Streams_class_diagram.drawio.bkp b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/.$MLPro-BF-Streams_class_diagram.drawio.bkp new file mode 100644 index 000000000..e20d1c1f1 --- /dev/null +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/.$MLPro-BF-Streams_class_diagram.drawio.bkp @@ -0,0 +1,658 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio index e20d1c1f1..5ddb5240b 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio @@ -1,63 +1,63 @@ - + - + - - + + - - + + - - - - + + + + - - + + + - - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + - + - + - + @@ -65,332 +65,332 @@ - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - + + + - - + + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + @@ -398,259 +398,259 @@ - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio.png index 47c5e2297..7e645744b 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer3_application_support/images/MLPro-BF-Streams_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/.$MLPro-BF-ML_class_diagram.drawio.bkp b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/.$MLPro-BF-ML_class_diagram.drawio.bkp new file mode 100644 index 000000000..b94e49237 --- /dev/null +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/.$MLPro-BF-ML_class_diagram.drawio.bkp @@ -0,0 +1,609 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio index bc2275801..275324cc1 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio @@ -1,607 +1,609 @@ - + - + - - - + + + - - + + - - - - + - - - + + + - - - - + - - - + + + - - - - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - + - - + + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - + - + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - - - - - + + + + - - + + + - - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + - - - + + + - - - - - + + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - - + + + - - + + + + + + + + - - + + - - + + + + + + + - - + + - - - + + + + + + - - + + + + + - - + + - - + + - - + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio.png index 3daf7870c..72d28d8d7 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_bf/layer4_machine_learning/images/MLPro-BF-ML_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio index a7640326a..cd6f18923 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio @@ -1,217 +1,217 @@ - + - + - + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - - + + - + - - + + - - - + + + - - + + - - + + - - + + - - + + - + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - - - + + + + - - + + + - - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + - - - + + + - - + + - + - - - + + + - - + + - - + + - - + + - - + + - - + + - - + + - - - + + + - - + + - - + + - - + + - - + + - - + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio.png index 3518c5615..f0919fe61 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/00_basics/images/MLPro-OA-Stream-Processing_class_diagram.drawio.png differ diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis.rst b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis.rst index 63e533f59..5dbae14ec 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis.rst +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis.rst @@ -2,10 +2,15 @@ Cluster analysis ================ -The cluster-analysis API is organized in three layers: ``ClusterActions`` defines the common consumer-facing cluster API, -``ClusterInfrastructure`` provides reusable internal cluster-management functionality, and ``ClusterAnalyzer`` combines this -infrastructure with ``OAStreamTask`` for online-adaptive stream processing. +The cluster-analysis API is organized as a lightweight core with optional standard MLPro infrastructure. +``ClusterActions`` defines the common cluster-facing API. ``ClusterAnalyzer`` combines this contract with ``OAStreamTask`` but +deliberately leaves the concrete cluster representation and management open. ``ClusterInfrastructure`` provides the reusable +standard MLPro mechanics, and ``ClusterAnalyzerExt`` combines both layers for conventional property-based implementations. + +On cluster level, ``ClusterAPI`` provides the minimal abstract cluster API independent of MLPro's property model, while +``Cluster`` adds the standard ``Properties`` and ``KWArgs`` infrastructure. ``EventConfigCA`` provides the cluster-specific event +switches ``CLUSTER_ADDED`` and ``CLUSTER_REMOVED``. .. image:: 20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio.png :scale: 50% diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio index c7abe73c0..f9f59b3b6 100644 --- a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio +++ b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio @@ -1,93 +1,72 @@ - + - - - - - + + + + + + + + - - + + - + - - - - - + + - - + + - - + + - + - - + + - + - - + + - - + + - - + + - + - - + + + + + - - - - - - - - + + - - - - - - - - - - - - - - - - - - - - + + @@ -96,7 +75,7 @@ - + @@ -113,7 +92,7 @@ - + @@ -168,7 +147,7 @@ - + @@ -191,7 +170,7 @@ - + @@ -242,8 +221,11 @@ + + + - + @@ -260,7 +242,7 @@ - + @@ -268,15 +250,18 @@ - + + + + - + @@ -286,7 +271,7 @@ - + @@ -301,15 +286,15 @@ - + - + - + @@ -318,16 +303,16 @@ - + - + - + - + @@ -342,12 +327,83 @@ - + - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio.png b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio.png index 14d65c036..824916fcf 100644 Binary files a/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio.png and b/doc/rtd/content/99_appendices/appendix2/sub/mlpro_oa/streams/20_cluster_analysis/images/MLPro-OA-Cluster_Analyzers_class_diagram.drawio.png differ diff --git a/setup.cfg b/setup.cfg index 2e8d9abf9..9eb26dc8d 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,6 +1,6 @@ [metadata] name = mlpro -version = 2.2.1 +version = 2.3.0 author = blueAIC author_email = mlpro@blueaic.com description = MLPro - The integrative middleware framework for standardized machine learning diff --git a/src/mlpro/bf/control/basics.py b/src/mlpro/bf/control/basics.py index 52d7a209f..639119bc8 100644 --- a/src/mlpro/bf/control/basics.py +++ b/src/mlpro/bf/control/basics.py @@ -33,10 +33,11 @@ ## -- 2025-06-02 1.0.1 DA Implemented method ControlledSystem._reset() ## -- 2025-06-11 1.1.0 DA Refactoring ## -- 2025-07-18 1.2.0 DA Refactoring +## -- 2026-10-05 1.3.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.2.0 (2025-07-18) +Ver. 1.3.0 (2026-10-05) This module provides basic classes around the topic closed-loop control. @@ -638,9 +639,10 @@ def remove_plot(self, p_refresh : bool = True): + ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class ControlPanel (EventManager): +class ControlPanel (Log, EventManager): """ Enables external control of a closed-loop control. """ @@ -650,6 +652,11 @@ class ControlPanel (EventManager): C_EVENT_ID_SETPOINT_CHG = 'SETPOINT_CHG' +## ------------------------------------------------------------------------------------------------- + def __init__(self, p_logging = Log.C_LOG_ALL): + Log.__init__(self, p_logging = p_logging) + EventManager.__init__(self) + ## ------------------------------------------------------------------------------------------------- def start(self): @@ -725,7 +732,7 @@ def _set_setpoint( self, p_values: Iterable ): ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class ControlShared (StreamShared, ControlPanel, Log): +class ControlShared (StreamShared, ControlPanel): """ ... """ @@ -736,7 +743,7 @@ class ControlShared (StreamShared, ControlPanel, Log): def __init__(self, p_range: int = Range.C_RANGE_PROCESS): StreamShared.__init__(self, p_range=p_range) - Log.__init__(self, p_logging = Log.C_LOG_NOTHING) + ControlPanel.__init__(self, p_logging=Log.C_LOG_NOTHING) self._next_inst_id = 0 self._superior_so : ControlShared = None diff --git a/src/mlpro/bf/events.py b/src/mlpro/bf/events.py index 47d0d9a53..4bbd0c55f 100644 --- a/src/mlpro/bf/events.py +++ b/src/mlpro/bf/events.py @@ -14,27 +14,98 @@ ## -- 2024-05-23 1.3.0 DA Method EventManger._raise_event(): reduction to TypeError ## -- 2025-05-27 1.4.0 DA Class Event: new parent class KWArgs ## -- 2025-07-18 1.5.0 DA Refactoring +## -- 2026-10-05 2.0.0 DA Refactoring: +## -- - logging removed from EventManager +## -- - tuned method EventManager._raise_event +## -- - new type EventId +## -- - new classes EventMode, EventConfig ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.5.0 (2025-07-18) +Ver. 2.0.0 (2026-10-05) -This module provides classes for event handling. To this regard, the property class Eventmanager is -provided to add event functionality to child classes by inheritence. +This module provides generic building blocks for event handling. Event identifiers are represented +by the type alias EventId. EventMode and EventConfig provide a lightweight configuration mechanism +that allows event-capable classes to enable or disable individual events. + +The property class EventManager adds event handling functionality to child classes by inheritance. +It manages event-handler registration and dispatch. Concrete EventConfig child classes may define +arbitrary event switches. By convention, event ids and the names of their corresponding switches +are written in upper case and must be identical. This convention is implemented and documented by +the concrete event-capable class; it is not enforced automatically by EventManager. """ from datetime import datetime -from mlpro.bf.various import Log, TStamp, TStampType, KWArgs -from mlpro.bf.exceptions import * +from typing import TypeAlias +from dataclasses import dataclass +from enum import IntEnum + +from mlpro.bf.various import TStamp, TStampType, KWArgs +from mlpro.bf.exceptions import ImplementationError # Export list for public API -__all__ = [ 'Event', +__all__ = [ 'EventId', + 'EventMode', + 'EventConfig', + 'Event', 'EventManager' ] +EventId: TypeAlias = str + + + +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class EventMode(IntEnum): + """ + Defines the generic operating modes of an event. + + The mode is typically queried by an event-capable implementation before an :class:`Event` + object is created. This allows disabled events to be skipped with minimal runtime overhead. + + Attributes + ---------- + OFF : int + Event is disabled. + EVENT : int + Event is enabled and may be raised. + """ + + OFF = 0 + EVENT = 1 + + + + +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +@dataclass +class EventConfig: + """ + Root class for event configurations. + + Concrete child classes define implementation-specific event switches as dataclass attributes. + The type of a switch is typically :class:`EventMode` or a specialized derivative introduced + by a higher-level MLPro package. + + By convention, event ids and the names of their corresponding event switches are written in + upper case and must be identical. The concrete event-capable implementation is responsible for + maintaining this relation; it is deliberately not enforced automatically by MLPro. + + Notes + ----- + The root class itself does not define any event switches. + """ + + pass + + + + ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- @@ -46,13 +117,16 @@ class Event (TStamp, KWArgs): Parameters ---------- p_raising_object - Reference to object that raised the event. - **p_kwargs - List of named parameters + Reference to the object that raises the event. + p_tstamp : TStampType, optional + Time stamp of the event. If omitted, the current date and time are used. + **p_kwargs + Additional event-specific data passed to registered handlers. """ ## ------------------------------------------------------------------------------------------------- def __init__(self, p_raising_object, p_tstamp:TStampType = None, **p_kwargs): + self._raising_object = p_raising_object if p_tstamp is None: @@ -65,11 +139,29 @@ def __init__(self, p_raising_object, p_tstamp:TStampType = None, **p_kwargs): ## ------------------------------------------------------------------------------------------------- def get_raising_object(self): + """ + Returns the object that raised the event. + + Returns + ------- + object + Raising object. + """ + return self._raising_object ## ------------------------------------------------------------------------------------------------- def get_data(self): + """ + Returns the event-specific key/value data. + + Returns + ------- + dict + Dictionary with event-specific data supplied at event creation. + """ + return self.kwargs @@ -78,37 +170,51 @@ def get_data(self): ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class EventManager (Log): +class EventManager: """ - This property class provides universal event management functionalities to be inherited to child - classes. + Property class providing universal event management functionality. + + EventManager manages handler registration and dispatch for string-based :class:`EventId` + values. An optional :class:`EventConfig` can be supplied to configure individual events. + + For backward compatibility, :meth:`_get_event_mode` returns :attr:`EventMode.EVENT` if no + event configuration is supplied. If a configuration is supplied, every queried event id must + have a matching attribute in that configuration. A mismatch is treated as an implementation + error. Parameters ---------- - p_logging - Log level (see constants of class Log). Default: Log.C_LOG_ALL - + p_event_config : EventConfig, optional + Optional event configuration used by the concrete event-capable implementation. If omitted, + :meth:`_get_event_mode` returns :attr:`EventMode.EVENT` for every event id. + + Notes + ----- + Event configuration is intentionally evaluated through :meth:`_get_event_mode` by the concrete + event-capable implementation before creating the corresponding :class:`Event` object. + :meth:`_raise_event` only dispatches an already created event and does not evaluate the + configuration itself. """ - C_TYPE = 'EventManager' - ## ------------------------------------------------------------------------------------------------- - def __init__(self, p_logging=Log.C_LOG_ALL): - Log.__init__(self, p_logging=p_logging) + def __init__(self, p_event_config : EventConfig = None): + self._registered_handlers = {} + self._event_config = p_event_config ## ------------------------------------------------------------------------------------------------- - def register_event_handler(self, p_event_id:str, p_event_handler): + def register_event_handler(self, p_event_id : EventId, p_event_handler): """ Registers an event handler. Parameters ---------- - p_event_id : str - Unique event id + p_event_id : EventId + Unique event identifier. p_event_handler - Reference to an event handler method with parameters p_event_id and p_event_object:Event + Reference to an event handler callable accepting the named parameters `p_event_id` + and `p_event_object`. """ try: @@ -118,16 +224,16 @@ def register_event_handler(self, p_event_id:str, p_event_handler): ## ------------------------------------------------------------------------------------------------- - def remove_event_handler(self, p_event_id:str, p_event_handler): + def remove_event_handler(self, p_event_id : EventId, p_event_handler): """ Removes an already registered event handler. Parameters ---------- - p_event_id - Unique event id + p_event_id : EventId + Unique event identifier. p_event_handler - Reference to an event handler method. + Reference to the registered event handler to be removed. """ try: @@ -137,38 +243,83 @@ def remove_event_handler(self, p_event_id:str, p_event_handler): ## ------------------------------------------------------------------------------------------------- - def _raise_event(self, p_event_id:str, p_event_object:Event): + def _get_event_mode(self, p_event_id : EventId) -> EventMode: """ - Raises an event and calls all registered handlers. To be used inside an event manager class. + Returns the configured mode of an event. + + This internal service method is intended to be called by the concrete event-capable + implementation before creating an :class:`Event` object. This allows disabled events to be + rejected early and avoids unnecessary event-object creation. Parameters ---------- - p_event_id : str - Unique event id - p_event_object : Event - Event object with further context informations + p_event_id : EventId + Unique event identifier. By convention, the identifier is written in upper case and + exactly matches the corresponding attribute name in the concrete + :class:`EventConfig` child class. + + Returns + ------- + EventMode + Configured event mode. :attr:`EventMode.EVENT` is returned if no event configuration + is supplied. + + Raises + ------ + ImplementationError + If an event configuration is supplied but does not provide an attribute matching the + given event id. + + Notes + ----- + The fallback to :attr:`EventMode.EVENT` in the absence of an event configuration preserves + the behaviour of existing MLPro event implementations. If a configuration is supplied, the + concrete implementation must ensure that each queried event id has a matching attribute. """ - # 0 Intro - self.log(Log.C_LOG_TYPE_S, 'Event "' + p_event_id + '" fired') - + if self._event_config is None: + return EventMode.EVENT - # 1 Get list of registered handlers for given event id try: - handlers = self._registered_handlers[p_event_id] - except: - handlers = [] + return getattr( + self._event_config, + p_event_id, + ) + except AttributeError: + raise ImplementationError( + 'Event configuration of type "' + + type(self._event_config).__name__ + + '" does not provide an attribute for event id "' + + p_event_id + + '". Check the event implementation and its EventConfig class.' + ) + + +## ------------------------------------------------------------------------------------------------- + def _raise_event(self, p_event_id : EventId, p_event_object:Event): + """ + Raises an event and calls all registered handlers. To be used inside an event manager class. + + Parameters + ---------- + p_event_id : EventId + Unique event identifier. + p_event_object : Event + Event object carrying the event context. + + Notes + ----- + This method does not evaluate the event configuration. The concrete implementation should + call :meth:`_get_event_mode` before creating the event object and invoke this method only + for events that are to be dispatched. + """ - if len(handlers) == 0: - self.log(Log.C_LOG_TYPE_I, 'No handlers registered for event "' + p_event_id + '"') - return + # 1 Check for registered event handlers + handlers = self._registered_handlers.get(p_event_id) + if not handlers: return # 2 Call all registered handlers - for i, handler in enumerate(handlers): - try: - self.log(Log.C_LOG_TYPE_I, 'Calling handler', i) - handler( p_event_id=p_event_id, p_event_object=p_event_object ) - except TypeError: - self.log(Log.C_LOG_TYPE_E, 'Handler not compatible! Check your code!') - raise TypeError \ No newline at end of file + for handler in handlers: + handler( p_event_id=p_event_id, + p_event_object=p_event_object ) \ No newline at end of file diff --git a/src/mlpro/bf/exceptions.py b/src/mlpro/bf/exceptions.py index d1cb000a3..7f9e41666 100644 --- a/src/mlpro/bf/exceptions.py +++ b/src/mlpro/bf/exceptions.py @@ -9,10 +9,11 @@ ## -- 2021-11-10 1.0.1 DA Added new exception ImplementationError ## -- 2021-12-12 1.0.2 DA Added new exception Error ## -- 2025-07-18 1.1.0 DA Refactoring +## -- 2026-11-12 1.2.0 DA New exception FunctionDisabled ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.1.0 (2025-07-18) +Ver. 1.2.0 (2026-11-12) This module provides exception classes. """ @@ -21,11 +22,11 @@ # Export list for public API __all__ = [ 'ParamError', 'ImplementationError', + 'FunctionDisabled', 'Error' ] - ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class ParamError(Exception): @@ -44,6 +45,16 @@ class ImplementationError(Exception): pass +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class FunctionDisabled(Exception): + """ + To be raised on an error... + """ + pass + + + ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class Error(Exception): diff --git a/src/mlpro/bf/math/basics.py b/src/mlpro/bf/math/basics.py index 994c831dc..d899a6b2b 100644 --- a/src/mlpro/bf/math/basics.py +++ b/src/mlpro/bf/math/basics.py @@ -45,10 +45,13 @@ ## -- 2025-07-11 3.0.1 DA Bugfix in method Scaler.rescale() ## -- 2025-10-02 3.1.0 DA Refactoring: removed try/except from Function.map() ## -- 2026-08-18 3.2.0 DA Class Element: alignment with higher numpy versions +## -- 2026-10-05 3.3.0 DA Refactoring +## -- 2026-11-10 3.4.0 DA Class Scaler: renamed attributes ._param* to ._scaler_param* +## -- 2026-11-11 3.5.0 DA Class Scaler: optimized rescaling ## ------------------------------------------------------------------------------------------------- """ -Ver. 3.2.0 (2026-08-18) +Ver. 3.5.0 (2026-11-11) This module provides basic mathematical classes. """ @@ -80,11 +83,9 @@ - - ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class Dimension (EventManager, KWArgs): +class Dimension (EventManager, Log, KWArgs): """ Objects of this type specify properties of a dimension of a set. @@ -134,11 +135,12 @@ def __init__( self, p_boundaries:list=[], p_description='', p_symmetrical:bool=False, - p_logging=Log.C_LOG_NOTHING, + p_logging = Log.C_LOG_ALL, **p_kwargs ): KWArgs.__init__(self, **p_kwargs) - EventManager.__init__(self, p_logging=p_logging) + EventManager.__init__(self) + Log.__init__(self, p_logging=p_logging) self._id = str(uuid.uuid4()) self._name_short = self.C_NAME = p_name_short @@ -979,10 +981,10 @@ def _map_inverse_ndarray( self, ## ------------------------------------------------------------------------------------------------- class Scaler (Function): """ - Template for scaler algorithms scaling, unscaling, rescaling data. This class introduces a - parameter handling based on the three attributes _param, _param_old, and _param_new. All custom - methods inherited from the class Function shall apply the parameters stored in _param, which is - a reference to eigther _param_old or _param_new. + Template for scaler algorithms scaling, unscaling, and rescaling data. Parameter sets + are managed via _scaler_param, _scaler_param_old, and _scaler_param_new. An optional + _scaler_param_re enables direct rescaling using precomputed parameters. Custom methods + inherited from Function use the active parameter set stored in _scaler_param. Parameters ---------- @@ -990,12 +992,14 @@ class Scaler (Function): Attributes ---------- - _param + _scaler_param Internal reference to the active set of function parameters applied to the next scaler action. - _param_old + _scaler_param_old Previous parameter set. - _param_new - Current parameter set. + _scaler_param_new + Current parameter set. + _scaler_param_re + Optional precomputed parameters for direct rescaling. None disables this optimization. """ ## ------------------------------------------------------------------------------------------------- @@ -1016,9 +1020,10 @@ def __init__( self, p_autocreate_elements = p_autocreate_elements, **p_kwargs ) - self._param = None - self._param_old = None - self._param_new = None + self._scaler_param = None + self._scaler_param_old = None + self._scaler_param_new = None + self._scaler_param_re = None # Optional precomputed parameters for direct rescaling ## ------------------------------------------------------------------------------------------------- @@ -1037,7 +1042,7 @@ def scale( self, Optional index of the dimension to be scaled. p_param = None Optional parameter set to be applied to the scaling operation. If None the set stored in - self._param_new is used. + self._scaler_param_new is used. Returns ------- @@ -1048,7 +1053,7 @@ def scale( self, if p_param is not None: self._set_parameters( p_param = p_param ) else: - self._set_parameters( p_param = self._param_new ) + self._set_parameters( p_param = self._scaler_param_new ) return self.map( p_input = p_data, p_dim = p_dim ) @@ -1069,7 +1074,7 @@ def unscale( self, Optional index of the dimension to be unscaled. p_param = None Optional parameter set to be applied to the unscaling operation. If None the set stored in - self._param_new is used. + self._scaler_param_new is used. Returns ------- @@ -1080,20 +1085,23 @@ def unscale( self, if p_param is not None: self._set_parameters( p_param = p_param ) else: - self._set_parameters( p_param = self._param_new ) + self._set_parameters( p_param = self._scaler_param_new ) return self.map_inverse( p_input = p_data, p_dim = p_dim ) ## ------------------------------------------------------------------------------------------------- - def rescale( self, - p_data : Data, + def rescale( self, + p_data : Data, p_dim : int = None, p_param_old = None, p_param_new = None ) -> Data: """ - Rescales the specified data by unscaling them with previous parameters stored in _param_old and - scaling them with the current parameters in _param_new. + Rescales data from an old parameter set to a new one. + + If no parameter set is explicitly provided and _scaler_param_re is available, + rescaling uses a single mapping with these precomputed parameters. Otherwise, + the original two-step unscaling and scaling procedure is used. Parameters ---------- @@ -1102,26 +1110,34 @@ def rescale( self, p_dim : int = None Optional index of the dimension to be rescaled. p_param_old = None - Optional parameter set to be applied to the unscaling operation. If None the set stored in - self._param_old is used. + Optional previous parameters for unscaling. Defaults to _scaler_param_old. p_param_new = None - Optional parameter set to be applied to the scaling operation. If None the set stored in - self._param_new is used. + Optional current parameters for scaling. Defaults to _scaler_param_new. Returns ------- Data - The rescaled data. + Rescaled data, or unchanged data if no previous parameters exist. """ - if ( self._param_old is None ) and ( p_param_old is None ): return p_data + # 0 if no parameters are available at all the data stay untouched + if ( self._scaler_param_old is None ) and ( p_param_old is None ): return p_data - param_old = p_param_old if p_param_old is not None else self._param_old - param_new = p_param_new if p_param_new is not None else self._param_new - - return self.scale( p_data = self.unscale( p_data = p_data, - p_dim = p_dim, - p_param = param_old ), + + # 1 Optional precomputed rescaling parameters have priority + if ( self._scaler_param_re is not None ) and ( p_param_old is None ) and ( p_param_new is None ): + result = self.scale( p_data = p_data, p_dim = p_dim, p_param = self._scaler_param_re ) + self._set_parameters( p_param = self._scaler_param_new ) + return result + + + # 2 Fall back to the original two-step transformation + param_old = p_param_old if p_param_old is not None else self._scaler_param_old + param_new = p_param_new if p_param_new is not None else self._scaler_param_new + + return self.scale( p_data = self.unscale( p_data = p_data, + p_dim = p_dim, + p_param = param_old ), p_dim = p_dim, p_param = param_new ) @@ -1137,24 +1153,25 @@ def _set_parameters( self, p_param ): Parameter set to be activated. """ - self._param = p_param + self._scaler_param = p_param ## ------------------------------------------------------------------------------------------------- def update_parameters( self, **p_kwargs ) -> bool: """ - Method to update the parameters of the scaler. It calls the custom method _update_parameters(), - which specifies the actual parameters needed by the particular algorithm. + Updates the scaler parameters through the custom method _update_parameters(). + Implementations that use _scaler_param_re must keep it consistent with the + old and new parameter sets. Parameters ---------- - p_data : Data - Data needed to update the parameters of the scaler. + **p_kwargs + Algorithm-specific arguments for updating scaler parameters. Returns ------- bool - True, if the parameters were changed. False otherwise. + True if the parameters changed, otherwise False. """ return self._update_parameters( **p_kwargs ) @@ -1163,19 +1180,18 @@ def update_parameters( self, **p_kwargs ) -> bool: ## ------------------------------------------------------------------------------------------------- def _update_parameters( self, **p_kwargs ) -> bool: """ - Custom method to update the parameters of the scaler based on data specific to the particular - algorithm. Please set the internal attribute p_param_new with new values and backup the previous content in - p_param_old before. + Custom method to update the scaler parameters. Implementations maintain + _scaler_param_old and _scaler_param_new and optionally _scaler_param_re. Parameters ---------- - p_data : Data - Data needed to update the parameters of the scaler. + **p_kwargs + Algorithm-specific arguments for updating scaler parameters. Returns ------- bool - True, if the parameters were changed. False otherwise. + True if the parameters changed, otherwise False. """ raise NotImplementedError \ No newline at end of file diff --git a/src/mlpro/bf/math/normalizers/basics.py b/src/mlpro/bf/math/normalizers/basics.py index 07e3960cf..cd9408ae5 100644 --- a/src/mlpro/bf/math/normalizers/basics.py +++ b/src/mlpro/bf/math/normalizers/basics.py @@ -28,15 +28,20 @@ ## -- 2025-06-25 1.4.0 DA Method Normalizer.renormalize(): tuning of dim-wise renormalization ## -- 2025-06-30 2.0.0 DA Class Normalizer: new parent class Scaler ## -- 2025-07-07 2.0.1 DA Refactoring +## -- 2026-11-10 2.1.0 DA Refactoring +## -- 2026-11-11 2.2.0 DA New class NormalizerAPI +## -- 2026-11-11 2.3.0 DA Optimized renormalization using combined affine parameters +## -- 2026-11-11 2.4.0 DA Precompute affine rescaling parameters on update ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.0.1 (2025-07-07) +Ver. 2.4.0 (2026-11-11) This module provides base class for Normalizers and normalizer objects including MinMax normalization and normalization by Z transformation. """ +from abc import ABC, abstractmethod import numpy as np @@ -46,26 +51,125 @@ # Export list for public API -__all__ = [ 'Normalizer', +__all__ = [ 'NormalizerAPI', + 'Normalizer', 'Renormalizable' ] +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class NormalizerAPI (ABC): + """ + API class for normalizers. + """ + +## ------------------------------------------------------------------------------------------------- + @abstractmethod + def normalize( self, + p_data : Data, + p_dim : int = None, + p_param = None ) -> Data: + """ + Normalizes the specified data. + + Parameters + ---------- + p_data : Data + Data to be normalized. + p_dim : int = None + Optional index of the dimension to be normalized. + p_param = None + Optional parameter set to be applied to the normalization. If None the set stored in + self._scaler_param_new is used. + + Returns + ------- + Data + The normalized data. + """ + + ... + + +## ------------------------------------------------------------------------------------------------- + @abstractmethod + def denormalize( self, + p_data : Data, + p_dim : int = None, + p_param = None ) -> Data: + """ + Denormalizes the specified data. + + Parameters + ---------- + p_data : Data + Data to be denormalized. + p_dim : int = None + Optional index of the dimension to be denormalized. + p_param = None + Optional parameter set to be applied to the denormalization. If None the set stored in + self._scaler_param_old is used. + + Returns + ------- + Data + The normalized data. + """ + + ... + + +## ------------------------------------------------------------------------------------------------- + @abstractmethod + def renormalize( self, + p_data : Data, + p_dim : int = None, + p_param_old = None, + p_param_new = None ) -> Data: + """ + Renormalizes the specified data by denormalizing them with previous parameters stored in + _param_old and normalize them with the current parameters in _param_new. + + Parameters + ---------- + p_data : Data + Data to be renormalized. + p_dim : int = None + Optional index of the dimension to be renormalized. + p_param_old = None + Optional parameter set to be applied to the denormalization. If None the set stored in + self._scaler_param_old is used. + p_param_new = None + Optional parameter set to be applied to the normalizaion. If None the set stored in + self._scaler_param_new is used. + + Returns + ------- + Data + The renormalized data. + """ + + ... + + + + ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class Normalizer (Scaler): +class Normalizer (Scaler, NormalizerAPI): """ Base class for normalizers. A normalizer in MLPro is a linear scaler with a fixed parameter structure providing the following basic operations: - Normalization (= scaling): scaled_data = unscaled_data * self._param[0] + self._param[1] - Denormalization (= unscaling): unscaled_data = ( scaled_data - self._param[1] ) / self._param[0] - Renormalization (= unscaling with old params and scaling with new params) + Normalization (= scaling): scaled_data = unscaled_data * self._scaler_param[0] + self._scaler_param[1] + Denormalization (= unscaling): unscaled_data = ( scaled_data - self._scaler_param[1] ) / self._scaler_param[0] + Renormalization (= rescaling from previous to current parameters; uses a precomputed\n affine mapping when available) - self._param_old and self._param_new are Numpy arrays of shape (2, n_dims) where n_dims is the number of dimensions + self._scaler_param_old and self._scaler_param_new are Numpy arrays of shape (2, n_dims) where n_dims is the number of dimensions of the data to be normalized. The first row contains the scaling factors and the second row - contains the offsets for each dimension. + contains the offsets for each dimension. After parameter updates, the combined affine\n parameters for direct renormalization are stored in _scaler_param_re. Parameters ---------- @@ -88,7 +192,7 @@ def normalize( self, Optional index of the dimension to be normalized. p_param = None Optional parameter set to be applied to the normalization. If None the set stored in - self._param_new is used. + self._scaler_param_new is used. Returns ------- @@ -117,7 +221,7 @@ def denormalize( self, Optional index of the dimension to be denormalized. p_param = None Optional parameter set to be applied to the denormalization. If None the set stored in - self._param_old is used. + self._scaler_param_old is used. Returns ------- @@ -131,14 +235,16 @@ def denormalize( self, ## ------------------------------------------------------------------------------------------------- - def renormalize( self, - p_data : Data, + def renormalize( self, + p_data : Data, p_dim : int = None, p_param_old = None, p_param_new = None ) -> Data: """ - Renormalizes the specified data by denormalizing them with previous parameters stored in - _param_old and normalize them with the current parameters in _param_new. + Renormalizes data from previous to current normalization parameters. + + Uses precomputed parameters if available and no explicit parameter sets + are supplied. Otherwise, uses the two-step Scaler.rescale() fallback. Parameters ---------- @@ -147,11 +253,9 @@ def renormalize( self, p_dim : int = None Optional index of the dimension to be renormalized. p_param_old = None - Optional parameter set to be applied to the denormalization. If None the set stored in - self._param_old is used. + Optional previous parameter set. Defaults to _scaler_param_old. p_param_new = None - Optional parameter set to be applied to the normalizaion. If None the set stored in - self._param_new is used. + Optional current parameter set. Defaults to _scaler_param_new. Returns ------- @@ -159,16 +263,52 @@ def renormalize( self, The renormalized data. """ - if ( self._param_old is None ) and ( p_param_old is None ): return p_data - - if ( p_dim is not None ) and np.array_equal(self._param_new[:,p_dim], self._param_old[:,p_dim] ): - return p_data - - return self.rescale( p_data = p_data, + return self.rescale( p_data = p_data, p_dim = p_dim, p_param_old = p_param_old, p_param_new = p_param_new ) - + + +## ------------------------------------------------------------------------------------------------- + def update_parameters( self, **p_kwargs ) -> bool: + """ + Updates the normalization parameters and prepares direct renormalization. + + Calls the custom parameter update through Scaler.update_parameters(). If the + parameters change and both the previous and current parameter sets exist, + the combined affine parameters are stored in _scaler_param_re. Otherwise, + precomputed renormalization is disabled. + + Parameters + ---------- + **p_kwargs + Algorithm-specific arguments forwarded to _update_parameters(). + + Returns + ------- + bool + True if the parameters changed, otherwise False. + """ + + updated = super().update_parameters( **p_kwargs ) + if not updated: + return False + + param_old = self._scaler_param_old + param_new = self._scaler_param_new + + if param_old is None or param_new is None: + self._scaler_param_re = None + return True + + # Combine old inverse and new forward affine transformations + param_re = np.empty_like(param_new, dtype=np.float64) + np.divide(param_new[0], param_old[0], out=param_re[0]) + np.multiply(param_re[0], param_old[1], out=param_re[1]) + np.subtract(param_new[1], param_re[1], out=param_re[1]) + self._scaler_param_re = param_re + return True + ## ------------------------------------------------------------------------------------------------- def _map( self, @@ -176,7 +316,7 @@ def _map( self, p_output : Element = None, p_dim : int = None ) -> Element: - scale, offset = self._param + scale, offset = self._scaler_param output = p_input if p_output is None else p_output values = p_input.get_values() @@ -195,15 +335,15 @@ def _map_ndarray( self, p_output : np.ndarray = None, p_dim = None ) -> np.ndarray: - scale, offset = self._param[0], self._param[1] + scale, offset = self._scaler_param[0], self._scaler_param[1] output = p_input if p_output is None else p_output if p_dim is None: np.multiply(p_input, scale, out=output) np.add(output, offset, out=output) else: - np.multiply(p_input[:,p_dim], scale, out=output[:,p_dim]) - np.add(output[:,p_dim], offset, out=output[:,p_dim]) + np.multiply(p_input[:,p_dim], scale[p_dim], out=output[:,p_dim]) + np.add(output[:,p_dim], offset[p_dim], out=output[:,p_dim]) return output @@ -217,7 +357,7 @@ def _map_list( self, if p_dim is None: raise ParamError('Method Normalizer._map_list() needs a valid p_dim') - scale, offset = self._param + scale, offset = self._scaler_param output = p_input if p_output is None else p_output input = np.array(p_input) @@ -234,7 +374,7 @@ def _map_inverse( self, p_output : Element = None, p_dim : int = None ) -> Element: - scale, offset = self._param + scale, offset = self._scaler_param output = p_input if p_output is None else p_output values = p_input.get_values() @@ -253,15 +393,15 @@ def _map_inverse_ndarray( self, p_output : np.ndarray = None, p_dim = None ) -> np.ndarray: - scale, offset = self._param[0], self._param[1] + scale, offset = self._scaler_param[0], self._scaler_param[1] output = p_input if p_output is None else p_output if p_dim is None: np.subtract(p_input, offset, out=output) np.divide(output, scale, out=output) else: - np.subtract(p_input[:,p_dim], offset, out=output[:,p_dim]) - np.divide(output[:,p_dim], scale, out=output[:,p_dim]) + np.subtract(p_input[:,p_dim], offset[p_dim], out=output[:,p_dim]) + np.divide(output[:,p_dim], scale[p_dim], out=output[:,p_dim]) return output @@ -275,7 +415,7 @@ def _map_inverse_list( self, if p_dim is None: raise ParamError('Method Normalizer._map_inverse_list() needs a valid p_dim') - scale, offset = self._param + scale, offset = self._scaler_param output = p_input if p_output is None else p_output input = np.array(p_input) diff --git a/src/mlpro/bf/math/normalizers/minmax.py b/src/mlpro/bf/math/normalizers/minmax.py index 61afc1cf1..2124decfd 100644 --- a/src/mlpro/bf/math/normalizers/minmax.py +++ b/src/mlpro/bf/math/normalizers/minmax.py @@ -28,10 +28,12 @@ ## -- - Refactoring of method update_parameters() ## -- 2025-06-28 2.1.0 DA Class NormalizerMinMax: new numerical stabilizer C_EPSILON ## -- 2025-06-30 2.2.0 DA Refactoring +## -- 2026-11-10 2.3.0 DA Refactoring +## -- 2026-11-16 2.4.0 DA Method NormalizerMinMax._update_parameters() tuned ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.2.0 (2025-06-30) +Ver. 2.4.0 (2026-11-16) This module provides a class for MinMax normalization. """ @@ -97,15 +99,82 @@ def __init__( self, # ------------------------------------------------------------------------------------------------- - def _update_parameters(self, p_set: Set = None, p_boundaries: Union[list, np.ndarray] = None) -> bool: + # def _update_parameters(self, p_set: Set = None, p_boundaries: Union[list, np.ndarray] = None) -> bool: + # """ + # Update the normalization parameters using MinMax strategy. + + # Parameters + # ---------- + # p_set : Set, optional + # A set object providing dimensional boundaries per feature. + + # p_boundaries : list or np.ndarray, optional + # Explicit array of (low, high) boundaries for each dimension. + + # Raises + # ------ + # ParamError + # Raised if neither p_set nor p_boundaries is provided. + # """ + + # # 1 Determine normalization boundaries + # if p_set is not None: + # dim_ids = p_set.get_dim_ids() + # boundaries = [p_set.get_dim(i).get_boundaries() for i in dim_ids] + # elif p_boundaries is not None: + # boundaries = np.asarray(p_boundaries).reshape(-1, 2) + # else: + # raise ParamError("Either p_set or p_boundaries must be provided.") + + # n_dims = len(boundaries) + + + # # 2 Initialize or update _param_old + # if self._scaler_param_new is not None: + # if self._scaler_param_old is None or self._scaler_param_old.shape != self._scaler_param_new.shape: + # self._scaler_param_old = self._scaler_param_new.copy() + # else: + # np.copyto(self._scaler_param_old, self._scaler_param_new) + + + # # 3 Allocate or reuse _param_new + # if self._scaler_param_new is None or self._scaler_param_new.shape != (2, n_dims): + # self._scaler_param_new = np.zeros((2, n_dims), dtype=np.float64) + # else: + # self._scaler_param_new[:] = 0.0 # optional in-place reset + + + # # 4 Compute new parameters into _param_new + # for i, (low, high) in enumerate(boundaries): + # if high == low: + # high += 1 + # low -= 1 + + # diff = high - low + # if diff < self.C_EPSILON: + # diff = self.C_EPSILON + + # p0 = self._dst_diff / diff + # p1 = self._dst_boundaries[0] - low * p0 + # self._scaler_param_new[:, i] = p0, p1 + + + # # 5 Activate _param_new by reference + # self._set_parameters( p_param = self._scaler_param_new ) + # return True + + +# ------------------------------------------------------------------------------------------------- + def _update_parameters( self, + p_set: Set = None, + p_boundaries: Union[list, np.ndarray] = None) -> bool: """ - Update the normalization parameters using MinMax strategy. + Update the normalization parameters using the MinMax strategy. Parameters ---------- p_set : Set, optional A set object providing dimensional boundaries per feature. - p_boundaries : list or np.ndarray, optional Explicit array of (low, high) boundaries for each dimension. @@ -118,7 +187,9 @@ def _update_parameters(self, p_set: Set = None, p_boundaries: Union[list, np.nda # 1 Determine normalization boundaries if p_set is not None: dim_ids = p_set.get_dim_ids() - boundaries = [p_set.get_dim(i).get_boundaries() for i in dim_ids] + boundaries = np.asarray( + [p_set.get_dim(i).get_boundaries() for i in dim_ids] + ) elif p_boundaries is not None: boundaries = np.asarray(p_boundaries).reshape(-1, 2) else: @@ -128,35 +199,40 @@ def _update_parameters(self, p_set: Set = None, p_boundaries: Union[list, np.nda # 2 Initialize or update _param_old - if self._param_new is not None: - if self._param_old is None or self._param_old.shape != self._param_new.shape: - self._param_old = self._param_new.copy() + if self._scaler_param_new is not None: + if self._scaler_param_old is None or self._scaler_param_old.shape != self._scaler_param_new.shape: + self._scaler_param_old = self._scaler_param_new.copy() else: - np.copyto(self._param_old, self._param_new) + np.copyto(self._scaler_param_old, self._scaler_param_new) # 3 Allocate or reuse _param_new - if self._param_new is None or self._param_new.shape != (2, n_dims): - self._param_new = np.zeros((2, n_dims), dtype=np.float64) - else: - self._param_new[:] = 0.0 # optional in-place reset + if self._scaler_param_new is None or self._scaler_param_new.shape != (2, n_dims): + self._scaler_param_new = np.zeros((2, n_dims), dtype=np.float64) + + # 4 Compute new normalization parameters + low = boundaries[:, 0].astype(np.float64) + high = boundaries[:, 1].astype(np.float64) - # 4 Compute new parameters into _param_new - for i, (low, high) in enumerate(boundaries): - if high == low: - high += 1 - low -= 1 + # 4.1 Handle dimensions with identical boundaries + equal = high == low + low[equal] -= 1.0 + high[equal] += 1.0 - diff = high - low - if diff < self.C_EPSILON: - diff = self.C_EPSILON + # 4.2 Compute scaling factors + diff = np.maximum(high - low, self.C_EPSILON) - p0 = self._dst_diff / diff - p1 = self._dst_boundaries[0] - low * p0 - self._param_new[:, i] = p0, p1 + # 4.3 Compute scale and offset + p0 = self._dst_diff / diff + p1 = self._dst_boundaries[0] - low * p0 + + # 4.4 Store parameters + self._scaler_param_new[0] = p0 + self._scaler_param_new[1] = p1 # 5 Activate _param_new by reference - self._set_parameters( p_param = self._param_new ) - return True + self._set_parameters(p_param=self._scaler_param_new) + + return True diff --git a/src/mlpro/bf/math/normalizers/ztrans.py b/src/mlpro/bf/math/normalizers/ztrans.py index 37bbac0b0..700e60e92 100644 --- a/src/mlpro/bf/math/normalizers/ztrans.py +++ b/src/mlpro/bf/math/normalizers/ztrans.py @@ -27,10 +27,11 @@ ## -- 2024-05-27 1.2.2 LSB Scientific Reference added ## -- 2024-12-09 1.3.0 DA Method NormalizerZTrans.update_parameters(): review/optimization ## -- 2025-07-05 2.0.0 DA Refactoring +## -- 2026-11-10 2.1.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.0.0 (2025-07-05) +Ver. 2.1.0 (2026-11-10) This module provides a class for Z transformation. """ @@ -111,11 +112,11 @@ def _update_parameters(self, """ # 0 Backup current parameters - if self._param_new is not None: - if self._param_old is None: - self._param_old = self._param_new.copy() + if self._scaler_param_new is not None: + if self._scaler_param_old is None: + self._scaler_param_old = self._scaler_param_new.copy() else: - np.copyto(self._param_old, self._param_new) + np.copyto(self._scaler_param_old, self._scaler_param_new) # 1 Update on dataset (full reset) @@ -132,8 +133,8 @@ def _update_parameters(self, np.copyto(self._std, np.std(p_dataset, axis=0, dtype=np.float64)) np.copyto(self._s, np.square(self._std) * self._n) - if self._param_new is None: - self._param_new = np.zeros([2, self._std.shape[-1]]) + if self._scaler_param_new is None: + self._scaler_param_new = np.zeros([2, self._std.shape[-1]]) else: # 2 Update on new data @@ -151,13 +152,13 @@ def _update_parameters(self, self._std = np.ones_like(data_new, dtype=np.float64) self._mean_old = np.zeros_like(data_new, dtype=np.float64) - if self._param_new is None: - self._param_new = np.zeros([2, data_new.shape[-1]]) + if self._scaler_param_new is None: + self._scaler_param_new = np.zeros([2, data_new.shape[-1]]) - np.copyto(self._param_new[0], 1.0) - np.copyto(self._param_new[1], -self._mean) + np.copyto(self._scaler_param_new[0], 1.0) + np.copyto(self._scaler_param_new[1], -self._mean) - self._set_parameters(p_param=self._param_new) + self._set_parameters(p_param=self._scaler_param_new) return True # 2.2 Incremental update @@ -188,17 +189,17 @@ def _update_parameters(self, np.copyto(self._s, 0.0) np.copyto(self._std, 1.0) - np.copyto(self._param_new[0], 1.0) - np.copyto(self._param_new[1], -self._mean) + np.copyto(self._scaler_param_new[0], 1.0) + np.copyto(self._scaler_param_new[1], -self._mean) - self._set_parameters(p_param=self._param_new) + self._set_parameters(p_param=self._scaler_param_new) return True # 4 Update of parameters with epsilon safeguard safe_std = np.maximum(self._std, self.C_EPSILON) - np.copyto(self._param_new[0], np.divide(1, safe_std, out=np.zeros_like(safe_std), where=safe_std != 0)) - np.copyto(self._param_new[1], -np.divide(self._mean, safe_std, out=np.zeros_like(safe_std), where=safe_std != 0)) + np.copyto(self._scaler_param_new[0], np.divide(1, safe_std, out=np.zeros_like(safe_std), where=safe_std != 0)) + np.copyto(self._scaler_param_new[1], -np.divide(self._mean, safe_std, out=np.zeros_like(safe_std), where=safe_std != 0)) - self._set_parameters(p_param=self._param_new) + self._set_parameters(p_param=self._scaler_param_new) return True diff --git a/src/mlpro/bf/math/statistics/boundaries.py b/src/mlpro/bf/math/statistics/boundaries.py index 87fade5f7..7363db3e7 100644 --- a/src/mlpro/bf/math/statistics/boundaries.py +++ b/src/mlpro/bf/math/statistics/boundaries.py @@ -7,16 +7,18 @@ ## -- yyyy-mm-dd Ver. Auth. Description ## -- 2025-06-01 0.1.0 DA Creation ## -- 2025-06-04 0.2.0 DA New methods create_boundaries(), _create_boundaries() +## -- 2026-10-06 0.3.0 DA Turned BoundaryProvider into an abstract class ## ------------------------------------------------------------------------------------------------- """ -Ver. 0.2.0 (2025-06-04) +Ver. 0.3.0 (2026-10-06) This module provides classes for the standardized use of value boundaries. """ from typing import Union from enum import IntEnum +from abc import ABC, abstractmethod import numpy as np from numpy.typing import NDArray @@ -47,7 +49,7 @@ class BoundarySide(IntEnum): ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class BoundaryProvider: +class BoundaryProvider (ABC): """ Standardizes the provision/computation of boundaries. """ @@ -72,6 +74,7 @@ def _create_boundaries( self, p_num_dim : int ) -> Boundaries: ## ------------------------------------------------------------------------------------------------- + @abstractmethod def get_boundaries( self, p_dim : int = None, p_side : BoundarySide = None, @@ -103,4 +106,4 @@ def get_boundaries( self, - If both `p_side` and `p_dim` are specified: returns a single float value. """ - raise NotImplementedError + ... diff --git a/src/mlpro/bf/ml/basics.py b/src/mlpro/bf/ml/basics.py index d0c2514a3..cb4f6c16f 100644 --- a/src/mlpro/bf/ml/basics.py +++ b/src/mlpro/bf/ml/basics.py @@ -76,10 +76,12 @@ ## -- - Incorporation of new class Adaptation ## -- 2025-06-02 2.5.0 DA New class AdaptationType ## -- 2025-07-15 2.5.1 DA Class AdaptationType: replaced parent class StrEnum by str +## -- 2026-10-05 2.6.0 DA - New class EventModeML +## -- - Classes Model, AdaptiveFunction: new parameter p_event_config ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.5.1 (2025-07-15) +Ver. 2.6.0 (2026-10-05) This module provides the fundamental templates and processes for machine learning in MLPro. @@ -87,10 +89,11 @@ import random from datetime import datetime +from enum import IntEnum import os from mlpro.bf.various import * -from mlpro.bf.events import Event +from mlpro.bf.events import * from mlpro.bf.exceptions import * from mlpro.bf.plot import PlotSettings from mlpro.bf.math import * @@ -103,18 +106,19 @@ class Figure: pass # Export list for public API -__all__ = [ 'Model', - 'AWorkflow', - 'Adaptation', - 'AdaptationType', - 'HyperParam', +__all__ = [ 'HyperParam', 'HyperParamSpace', 'HyperParamTuple', 'HyperParamDispatcher', + 'AdaptationType', + 'Adaptation', + 'EventModeML', + 'Model', + 'AWorkflow', 'Scenario', - 'Training', 'TrainingResults', 'HyperParamTuner', + 'Training', 'AdaptiveFunction' ] @@ -261,6 +265,32 @@ def __init__( self, +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class EventModeML(IntEnum): + """ + Extends :class:`mlpro.bf.events.EventMode` with ML-specific adaptation semantics. + + Attributes + ---------- + OFF : int + Event is disabled. + EVENT : int + Event is enabled and may be raised without implying model adaptation. + ADAPTATION : int + Event is enabled and additionally represents a model adaptation. Concrete ML + implementations are responsible for evaluating this mode and integrating it into their + adaptation logic. + """ + + OFF = EventMode.OFF + EVENT = EventMode.EVENT + ADAPTATION = 2 + + + + + ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class Model (Task, ScientificObject): @@ -292,6 +322,10 @@ class Model (Task, ScientificObject): actions. p_class_shared Optional class for a shared object (class Shared or a child class of it) + p_event_config : EventConfig, optional + Optional event configuration passed to the inherited event manager. ML-specific event + switches may use :class:`EventModeML`. If omitted, queried events default to + :attr:`EventMode.EVENT`. p_visualize : bool Boolean switch for visualisation. Default = False. p_logging @@ -319,6 +353,7 @@ def __init__( self, p_range_max: int = Async.C_RANGE_PROCESS, p_autorun = Task.C_AUTORUN_NONE, p_class_shared=None, + p_event_config : EventConfig = None, p_visualize: bool = False, p_logging=Log.C_LOG_ALL, **p_par ): @@ -329,6 +364,7 @@ def __init__( self, p_range_max = p_range_max, p_autorun = p_autorun, p_class_shared = p_class_shared, + p_event_config = p_event_config, p_visualize = p_visualize, p_logging = p_logging ) @@ -446,12 +482,14 @@ def _set_adapted( self, p_tstamp : TStampType = None, **p_kwargs ): """ - Sets the adapted flag and raises an adaptation event. + Updates the internal adaptation state and, if applicable, raises the model's adaptation + event. Parameters ---------- p_adapted : bool - Adaptation flag. If True and event handlers are registered an adaptation event is raised. + Adaptation flag. If True and at least one event handler is registered, an adaptation + event of type :attr:`C_EVENT_CLS` is dispatched under :attr:`C_EVENT_ADAPTED`. p_subtype : AdaptationType Subtype of adaptation. See class AdaptationType for further details. p_tstamp : TStampType = None @@ -530,17 +568,19 @@ def _adapt(self, **p_kwargs) -> bool: ## ------------------------------------------------------------------------------------------------- - def adapt_on_event(self, p_event_id:str, p_event_object:Event): + def adapt_on_event(self, p_event_id: EventId, p_event_object: Event): """ - Method to be used as event handler for event-based adaptations. Calls custom method - _adapt_on_event() and updates the internal adaptation state. + Handles an incoming event by triggering an event-based model adaptation. + + The concrete adaptation logic is delegated to :meth:`_adapt_on_event`. Its return value is + forwarded to :meth:`_set_adapted` using :attr:`AdaptationType.EVENT`. Parameters ---------- - p_event_id : str - Event id. + p_event_id : EventId + Unique identifier of the triggering event. p_event_object : Event - Object with further context informations about the event. + Event object carrying the event context. """ self._set_adapted( p_adapted = self._adapt_on_event( p_event_id=p_event_id, @@ -549,21 +589,21 @@ def adapt_on_event(self, p_event_id:str, p_event_object:Event): ## ------------------------------------------------------------------------------------------------- - def _adapt_on_event(self, p_event_id:str, p_event_object:Event) -> bool: + def _adapt_on_event(self, p_event_id: EventId, p_event_object: Event) -> bool: """ - Custom method to be used for event-based adaptation. See method adapt_on_event(). + Custom method implementing an event-based adaptation. Parameters ---------- - p_event_id : str - Event id. + p_event_id : EventId + Unique identifier of the triggering event. p_event_object : Event - Object with further context informations about the event. + Event object carrying the event context. Returns ------- adapted : bool - True, if something was adapted. False otherwise. + True if the model was adapted, otherwise False. """ raise NotImplementedError @@ -1530,6 +1570,10 @@ class AdaptiveFunction (Function, Model): actions. p_class_shared Optional class for a shared object (class Shared or a child class of it) + p_event_config : EventConfig, optional + Optional event configuration passed to the inherited event manager. ML-specific event + switches may use :class:`EventModeML`. If omitted, queried events default to + :attr:`EventMode.EVENT`. p_visualize : bool Boolean switch for visualisation. Default = False. p_logging @@ -1552,6 +1596,7 @@ def __init__( self, p_range_max: int = Async.C_RANGE_PROCESS, p_autorun = Task.C_AUTORUN_NONE, p_class_shared=None, + p_event_config : EventConfig = None, p_visualize: bool = False, p_logging=Log.C_LOG_ALL, **p_par ): @@ -1568,6 +1613,7 @@ def __init__( self, p_range_max = p_range_max, p_autorun = p_autorun, p_class_shared = p_class_shared, + p_event_config = p_event_config, p_visualize = p_visualize, p_logging = p_logging, **p_par ) diff --git a/src/mlpro/bf/mt.py b/src/mlpro/bf/mt.py index 4111e2fbc..e882fa222 100644 --- a/src/mlpro/bf/mt.py +++ b/src/mlpro/bf/mt.py @@ -46,10 +46,12 @@ ## -- 2024-12-11 2.4.0 DA New method Workflow.remove_plot() ## -- 2025-07-18 2.5.0 DA Refactoring ## -- 2025-10-09 2.6.0 DA Method Async._create_so(): additional parameter p_kwargs +## -- 2026-09-29 2.7.0 DA Method Async.__init__(): additional parameter p_kwargs +## -- 2026-10-05 2.8.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.6.0 (2025-10-09) +Ver. 2.8.0 (2026-10-05) This module provides classes for multitasking with optional interprocess communication (IPC) based on shared objects. Multitasking in MLPro combines multrithreading and multiprocessing and simplifies @@ -67,15 +69,10 @@ import multiprocess as mp from multiprocess.managers import BaseManager -try: - from matplotlib.figure import Figure -except: - class Figure : pass - from mlpro.bf.exceptions import * from mlpro.bf.various import * -from mlpro.bf.events import EventManager, Event -from mlpro.bf.plot import PlotSettings, Plottable +from mlpro.bf.events import * +from mlpro.bf.plot import Figure, PlotSettings, Plottable @@ -88,7 +85,6 @@ class Figure : pass - ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class Range: @@ -324,13 +320,16 @@ class Async (Range, Log): Optional class for a shared object (class Shared or a child class of Shared) p_logging Log level (see constants of class Log). Default: Log.C_LOG_ALL + p_kwargs : dict + Optional parameters for a shared object. """ ## ------------------------------------------------------------------------------------------------- def __init__( self, p_range_max:int=Range.C_RANGE_PROCESS, p_class_shared=None, - p_logging=Log.C_LOG_ALL ): + p_logging=Log.C_LOG_ALL, + **p_kwargs ): Log.__init__(self, p_logging=p_logging) Range.__init__(self, p_range=p_range_max) @@ -339,7 +338,9 @@ def __init__( self, self._mpmanager = None self._class_shared = p_class_shared - self._so : Shared = self._create_so(p_range=p_range_max, p_class_shared=p_class_shared) + self._so : Shared = self._create_so( p_range = p_range_max, + p_class_shared = p_class_shared, + **p_kwargs ) ## ------------------------------------------------------------------------------------------------- @@ -522,6 +523,10 @@ class Task (Async, EventManager, Plottable, Persistent, KWArgs): actions. p_class_shared Optional class for a shared object (class Shared or a child class of Shared) + p_event_config : EventConfig, optional + Optional event configuration passed to :class:`EventManager`. Concrete event-capable + implementations can query it through :meth:`EventManager._get_event_mode`. If omitted, + queried events default to :attr:`EventMode.EVENT`. p_visualize : bool Boolean switch for env/agent visualisation. Default = False. p_logging @@ -545,6 +550,7 @@ def __init__( self, p_range_max : int = Async.C_RANGE_THREAD, p_autorun = C_AUTORUN_NONE, p_class_shared = None, + p_event_config : EventConfig = None, p_visualize : bool = False, p_logging = Log.C_LOG_ALL, **p_kwargs ): @@ -564,7 +570,7 @@ def __init__( self, self.set_name(str(self.get_id())) Async.__init__(self, p_range_max=p_range_max, p_class_shared=p_class_shared, p_logging=p_logging) - EventManager.__init__(self, p_logging=p_logging) + EventManager.__init__(self, p_event_config=p_event_config) Plottable.__init__(self, p_visualize=p_visualize) Persistent.__init__(self, p_id=p_id, p_logging=p_logging) @@ -736,7 +742,21 @@ def set_predecessors(self, p_predecessor_tasks:list ): ## ------------------------------------------------------------------------------------------------- - def _raise_event(self, p_event_id: str, p_event_object: Event): + def _raise_event(self, p_event_id: EventId, p_event_object: Event): + """ + Raises a task event and forwards it to all registered handlers. + + Before dispatching :attr:`C_EVENT_FINISHED`, the task-specific hook + :meth:`_on_finished` is executed. + + Parameters + ---------- + p_event_id : EventId + Unique event identifier. + p_event_object : Event + Event object carrying the event context. + """ + if p_event_id == self.C_EVENT_FINISHED: self._on_finished() EventManager._raise_event(self, p_event_id, p_event_object) @@ -744,24 +764,25 @@ def _raise_event(self, p_event_id: str, p_event_object: Event): ## ------------------------------------------------------------------------------------------------- def _on_finished(self): """ - Custom method that is called before an event C_EVENT_FINISHED is raised. + Custom hook that is called immediately before :attr:`C_EVENT_FINISHED` is dispatched. """ pass ## ------------------------------------------------------------------------------------------------- - def run_on_event(self, p_event_id, p_event_object:Event): + def run_on_event(self, p_event_id: EventId, p_event_object: Event): """ - Can be used as event handler - in particular for other tasks in a workflow in combination - with event C_EVENT_FINISHED. Method self.run() is called if the last predecessor task in a - workflow has raised event C_EVENT_FINISHED. + Event handler that starts the task after predecessor events. + + In a workflow this handler is typically registered for :attr:`C_EVENT_FINISHED` of all + predecessor tasks. The task is started after the last predecessor has reported completion. Parameters ---------- - p_event_id - Event id. + p_event_id : EventId + Unique event identifier. p_event_object : Event - Event object with further context informations. + Event object carrying the event context and optional parameters for :meth:`run`. """ if p_event_id == self.C_EVENT_FINISHED: diff --git a/src/mlpro/bf/streams/basics.py b/src/mlpro/bf/streams/basics.py index 00e855db9..e2c55a4f6 100644 --- a/src/mlpro/bf/streams/basics.py +++ b/src/mlpro/bf/streams/basics.py @@ -95,10 +95,11 @@ ## -- 2025-09-21 3.4.0 DA Class Stream, MultiStream: adjustments and bugfixes ## -- 2025-10-23 3.4.1 DA Bugfix in StreamTask._update_plot_3d() ## -- 2025-10-24 3.5.0 DA Refactoring of plot legend handling in StreamTask._update_plot_nd() +## -- 2026-10-05 3.6.0 DA Class StreamTask: new parameter p_event_config ## ------------------------------------------------------------------------------------------------- """ -Ver. 3.5.0 (2025-10-24) +Ver. 3.6.0 (2026-10-05) This module provides classes for standardized data stream processing. @@ -111,17 +112,12 @@ import time from datetime import timedelta, datetime -try: - from matplotlib.figure import Figure -except: - class Figure : pass - from mlpro.bf.various import Id, TStampType, TStamp, KWArgs, ScientificObject, Log from mlpro.bf.exceptions import Error, ImplementationError, ParamError -from mlpro.bf.events import Event +from mlpro.bf.events import EventConfig, Event from mlpro.bf.ops import Mode, ScenarioBase from mlpro.bf.mt import Range, Shared, Task, Workflow -from mlpro.bf.plot import Plottable, PlotSettings +from mlpro.bf.plot import Figure, Plottable, PlotSettings from mlpro.bf.math import Dimension, Element, MSpace @@ -1124,6 +1120,11 @@ class StreamTask (Task): Maximum range of asynchonicity. See class Range. Default is Range.C_RANGE_PROCESS. p_duplicate_data : bool If True, instances will be duplicated before processing. Default = False. + p_event_config : EventConfig, optional + Optional event configuration passed to the inherited event manager. Concrete event-capable + stream tasks can query it through + :meth:`mlpro.bf.events.EventManager._get_event_mode`. If omitted, queried events default + to :attr:`mlpro.bf.events.EventMode.EVENT`. p_visualize : bool Boolean switch for visualisation. Default = False. p_logging @@ -1149,6 +1150,7 @@ def __init__( self, p_name: str = None, p_range_max = Task.C_RANGE_THREAD, p_duplicate_data : bool = False, + p_event_config : EventConfig = None, p_visualize : bool = False, p_logging = Log.C_LOG_ALL, **p_kwargs ): @@ -1158,6 +1160,7 @@ def __init__( self, p_range_max=p_range_max, p_autorun=Task.C_AUTORUN_NONE, p_class_shared=None, + p_event_config=p_event_config, p_visualize=p_visualize, p_logging=p_logging, **p_kwargs ) diff --git a/src/mlpro/bf/streams/streams/deprecated/clusters.py b/src/mlpro/bf/streams/streams/deprecated/clusters.py index 2d24d7c5d..3150e85bc 100644 --- a/src/mlpro/bf/streams/streams/deprecated/clusters.py +++ b/src/mlpro/bf/streams/streams/deprecated/clusters.py @@ -335,7 +335,7 @@ def __init__( self, p_logging=p_logging, **p_kwargs) - EventManager.__init__(self, p_logging=p_logging) + EventManager.__init__(self) # 4 Initialize seeding diff --git a/src/mlpro/bf/streams/streams/generators/basics.py b/src/mlpro/bf/streams/streams/generators/basics.py index fd89f870a..26807a2ae 100644 --- a/src/mlpro/bf/streams/streams/generators/basics.py +++ b/src/mlpro/bf/streams/streams/generators/basics.py @@ -7,10 +7,11 @@ ## -- yyyy-mm-dd Ver. Auth. Description ## -- 2025-09-21 1.0.0 DA Creation ## -- 2025-11-06 1.0.1 DA Bugfix in StreamGenerator.__next__() +## -- 2026-10-05 1.1.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.0.1 (2025-11-06) +Ver. 1.1.0 (2026-10-05) This module provides template classes for single and multi-stream data generation in a d-dimensional feature space. @@ -115,7 +116,7 @@ def __init__( self, self.num_outliers = 0 - EventManager.__init__( self, p_logging = Log.C_LOG_NOTHING) + EventManager.__init__( self ) Stream.__init__( self, p_id = p_id, diff --git a/src/mlpro/bf/streams/streams/point_outliers.py b/src/mlpro/bf/streams/streams/point_outliers.py index 7aad03a89..d1c8ea42a 100644 --- a/src/mlpro/bf/streams/streams/point_outliers.py +++ b/src/mlpro/bf/streams/streams/point_outliers.py @@ -12,10 +12,11 @@ ## -- 2024-06-04 1.1.1 DA Bugfix: ESpace instead of MSpace ## -- 2025-06-22 1.2.0 DA Code cleanup and refactoring# ## -- 2025-07-22 1.3.0 DA Outliers are raised as events now +## -- 2026-10-05 1.4.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.3.0 (2025-07-22) +Ver. 1.4.0 (2026-10-05) This module provides a multivariate benchmark stream with configurable baselines per feature and additional random point outliers. @@ -39,7 +40,6 @@ - ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class StreamMLProPOutliers (StreamMLProBase, EventManager): @@ -93,7 +93,7 @@ def __init__( self, p_logging=p_logging, **p_kwargs) - EventManager.__init__(self, p_logging=p_logging) + EventManager.__init__(self) ## ------------------------------------------------------------------------------------------------- diff --git a/src/mlpro/bf/systems/basics.py b/src/mlpro/bf/systems/basics.py index 57fe3b432..b62b9fc7d 100644 --- a/src/mlpro/bf/systems/basics.py +++ b/src/mlpro/bf/systems/basics.py @@ -54,10 +54,11 @@ ## -- 2024-10-06 2.5.0 DA New property attribute State.value ## -- 2024-12-11 2.5.0 DA New method DemoScenario.init_plot() ## -- 2025-07-18 2.6.0 DA Refactoring +## -- 2026-10-05 2.7.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.6.0 (2025-07-18) +Ver. 2.7.0 (2026-10-05) This module provides models and templates for state based systems. """ @@ -548,7 +549,7 @@ class Actuator (Dimension): ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class SAGateway (EventManager): +class SAGateway (EventManager, Log): """ Template for a gateway implementation that enables access to sensors and actuators. @@ -584,7 +585,8 @@ def __init__(self, p_id, p_name:str = '', p_logging : bool = Log.C_LOG_ALL, **p_ self._sensors = Set() self._actuators = Set() - EventManager.__init__(self, p_logging=p_logging) + EventManager.__init__(self) + Log.__init__(self, p_logging=p_logging) ## ------------------------------------------------------------------------------------------------- diff --git a/src/mlpro/oa/streams/basics.py b/src/mlpro/oa/streams/basics.py index 4e4a1c9a4..a54d3c028 100644 --- a/src/mlpro/oa/streams/basics.py +++ b/src/mlpro/oa/streams/basics.py @@ -36,16 +36,20 @@ ## -- - setup() and _setup() ## -- 2025-07-15 1.4.2 DA Class OAStreamAdaptationType: new parent class AdaptationType ## -- 2025-07-16 1.4.3 DA Refactoring +## -- 2026-10-05 1.5.0 DA Class OAStreamTask: new parameter p_event_config +## -- 2026-10-08 1.6.0 DA Class OAStreamTask: optimization of adaptation +## -- - removed logging +## -- - removed expensive try/except statements ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.4.3 (2025-07-16) +Ver. 1.6.0 (2026-10-08) Core classes for online-adaptive data stream processing (OADSP). """ -from mlpro.bf.mt import Event +from mlpro.bf.events import * from mlpro.bf.various import Log, TStampType from mlpro.bf.plot import PlotSettings from mlpro.bf.mt import Task @@ -55,6 +59,7 @@ from mlpro.bf.ml import AdaptationType, Adaptation, Model, AWorkflow + # Export list for public API __all__ = [ 'OAStreamShared', 'OAStreamAdaptationType', @@ -106,6 +111,8 @@ class OAStreamAdaptation (Adaptation): Type of adaptation. p_tstamp : TStampType = None Time stamp of adaptation. + p_num_inst : int + Number of stream instances related to the adaptation. Default = 1. **p_kwargs Further keyword arguments to be transported by the event. """ @@ -147,6 +154,10 @@ class OAStreamTask (StreamTask, Model): Initial size of internal data buffer. Defaut = 0 (no buffering). p_duplicate_data : bool If True, instances will be duplicated before processing. Default = False. + p_event_config : EventConfig, optional + Optional event configuration passed to the inherited event manager. ML-specific event + switches may use :class:`mlpro.bf.ml.EventModeML`. If omitted, queried events default to + :attr:`mlpro.bf.events.EventMode.EVENT`. p_visualize : bool Boolean switch for visualisation. Default = False. p_logging @@ -171,6 +182,7 @@ def __init__( self, p_ada : bool = True, p_buffer_size : int = 0, p_duplicate_data : bool = False, + p_event_config : EventConfig = None, p_visualize : bool = False, p_logging = Log.C_LOG_ALL, **p_kwargs ): @@ -182,6 +194,7 @@ def __init__( self, p_autorun = Task.C_AUTORUN_NONE, p_class_shared = None, p_buffer_size = p_buffer_size, + p_event_config = p_event_config, p_visualize = p_visualize, p_logging = p_logging ) @@ -189,6 +202,7 @@ def __init__( self, p_name = p_name, p_range_max = p_range_max, p_duplicate_data = p_duplicate_data, + p_event_config = p_event_config, p_visualize = p_visualize, p_logging = p_logging, **p_kwargs ) @@ -202,7 +216,21 @@ def _set_adapted( self, p_num_inst = 1, **p_kwargs ): """ - + Updates the adaptation state using an online-adaptive stream adaptation event. + + Parameters + ---------- + p_adapted : bool + Adaptation flag. + p_subtype : OAStreamAdaptationType + Type of online-adaptive stream adaptation. + p_tstamp : TStampType, optional + Optional explicit time stamp. If omitted, the current stream time stamp is used if + available. + p_num_inst : int + Number of stream instances related to the adaptation. Default = 1. + **p_kwargs + Additional event-specific data forwarded to the adaptation event. """ if p_tstamp is None: @@ -222,10 +250,27 @@ def _set_adapted( self, ## ------------------------------------------------------------------------------------------------- def adapt(self, p_instances : InstDict) -> bool: + """ + Adapts the task to new and obsolete stream instances. + + New instances are processed by :meth:`_adapt`, obsolete instances by + :meth:`_adapt_reverse`. Optional pre- and postprocessing hooks may report additional + adaptation types. If adaptations occur, corresponding adaptation events are generated via + :meth:`_set_adapted`. + + Parameters + ---------- + p_instances : InstDict + Dictionary of new and obsolete stream instances to be processed. + + Returns + ------- + bool + True if at least one forward or reverse adaptation was performed, otherwise False. + """ # 0 Intro if not self._adaptivity: return False - self.log(self.C_LOG_TYPE_S, 'Adaptation started') adapted_forward = False adapted_reverse = False @@ -234,17 +279,11 @@ def adapt(self, p_instances : InstDict) -> bool: # 1 Preprocessing - try: - atype_pre = self._adapt_pre() + atype_pre = self._adapt_pre() - if atype_pre != OAStreamAdaptationType.NONE: - if atype_pre == OAStreamAdaptationType.FORWARD: adapted_forward = True - elif atype_pre == OAStreamAdaptationType.REVERSE: adapted_reverse = True - - self.log(self.C_LOG_TYPE_S, 'Preprocessing done') - - except NotImplementedError: - pass + if atype_pre != OAStreamAdaptationType.NONE: + if atype_pre == OAStreamAdaptationType.FORWARD: adapted_forward = True + elif atype_pre == OAStreamAdaptationType.REVERSE: adapted_reverse = True # 2 Main adaptation loop @@ -252,45 +291,28 @@ def adapt(self, p_instances : InstDict) -> bool: if inst_type == InstTypeNew: # 2.1 Adaptation on a new stream instance - self.log(self.C_LOG_TYPE_S, 'Adaptation on new instance', inst_id) if self._adapt( p_instance_new=inst): adapted_forward = True num_inst_forward += 1 - self.log(self.C_LOG_TYPE_S, 'Policy adapted') - else: - self.log(self.C_LOG_TYPE_S, 'Policy not adapted') else: # 2.2 Reverse adaptation on an obsolete stream instance - self.log(self.C_LOG_TYPE_S, 'Reverse adaptation on obsolete instance', inst_id) - try: - if self._adapt_reverse( p_instance_del=inst ): - adapted_reverse = True - num_inst_reverse += 1 - self.log(self.C_LOG_TYPE_S, 'Policy adapted') - else: - self.log(self.C_LOG_TYPE_S, 'Policy not adapted') - except NotImplementedError: - self.log(self.C_LOG_TYPE_W, 'Reverse adaptation not implemented', inst_id) + if self._adapt_reverse( p_instance_del=inst ): + adapted_reverse = True + num_inst_reverse += 1 # 3 Postprocessing - try: - atype_post = self._adapt_post() - - if atype_post != OAStreamAdaptationType.NONE: - if atype_post == OAStreamAdaptationType.FORWARD: adapted_forward = True - elif atype_post == OAStreamAdaptationType.REVERSE: adapted_reverse = True + atype_post = self._adapt_post() - self.log(self.C_LOG_TYPE_S, 'Postprocessing done') + if atype_post != OAStreamAdaptationType.NONE: + if atype_post == OAStreamAdaptationType.FORWARD: adapted_forward = True + elif atype_post == OAStreamAdaptationType.REVERSE: adapted_reverse = True - except NotImplementedError: - pass # 4 Outro: Logging and adaptation events if adapted_forward or adapted_reverse: - self.log(self.C_LOG_TYPE_S, 'Adaptation done with changes') tstamp = self.get_so().tstamp if adapted_reverse: @@ -308,7 +330,6 @@ def adapt(self, p_instances : InstDict) -> bool: return True else: - self.log(self.C_LOG_TYPE_S, 'Adaptation done without changes') self._set_adapted( p_adapted = False ) return False @@ -324,7 +345,7 @@ def _adapt_pre(self) -> OAStreamAdaptationType: Type of adaptation carried out. """ - raise NotImplementedError + return OAStreamAdaptationType.NONE ## ------------------------------------------------------------------------------------------------- @@ -343,7 +364,7 @@ def _adapt(self, p_instance_new:Instance) -> bool: True, if something has been adapted. False otherwise. """ - raise NotImplementedError + pass ## ------------------------------------------------------------------------------------------------- @@ -362,7 +383,7 @@ def _adapt_reverse(self, p_instance_del:Instance) -> bool: True, if something has been adapted. False otherwise. """ - raise NotImplementedError + pass ## ------------------------------------------------------------------------------------------------- @@ -376,7 +397,7 @@ def _adapt_post(self) -> OAStreamAdaptationType: Type of adaptation carried out. """ - raise NotImplementedError + return OAStreamAdaptationType.NONE ## ------------------------------------------------------------------------------------------------- @@ -392,22 +413,24 @@ def _renormalize(self, p_normalizer:Normalizer): Normalizer object to be applied on task-specific """ - raise NotImplementedError + pass ## ------------------------------------------------------------------------------------------------- - def renormalize_on_event(self, p_event_id: str, p_event_object: Event): + def renormalize_on_event(self, p_event_id: EventId, p_event_object: Event): """ - Event handler method to be registered on event Model.C_EVENT_ADAPTED of an online adaptive - normalizer task. It carries out the task-specific renormalization of internally buffered - data by calling the custom method _renormalize(). + Handles adaptation events of an online-adaptive normalizer. + + The handler invokes :meth:`_renormalize` with the event's raising object and marks the task + as adapted with subtype :attr:`OAStreamAdaptationType.RENORM` after successful + renormalization. Parameters ---------- - p_event_id : str - Unique event id + p_event_id : EventId + Unique identifier of the triggering event, typically :attr:`Model.C_EVENT_ADAPTED`. p_event_object : Event - Event object with further context informations + Adaptation event whose raising object is expected to provide the normalizer. """ self.log(Log.C_LOG_TYPE_I, 'Renormalization triggered') diff --git a/src/mlpro/oa/streams/tasks/clusteranalyzers/basics.py b/src/mlpro/oa/streams/tasks/clusteranalyzers/basics.py index 1ecd02909..9a90de852 100644 --- a/src/mlpro/oa/streams/tasks/clusteranalyzers/basics.py +++ b/src/mlpro/oa/streams/tasks/clusteranalyzers/basics.py @@ -52,10 +52,12 @@ ## -- - Bugfix: added missing parameter p_thrs_cluster_influence ## -- - Method _get_cluster_relations(): robustness for negative influences ## -- 2026-08-05 1.9.0 DA New classes ClusterActions, ClusterInfrastructure +## -- 2026-10-06 2.0.0 DA Refactoring and extension +## -- 2026-11-15 2.1.0 DA New constant ClusterAction.C_RESULT_SCOPE_NONZERO ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.9.0 (2026-08-05) +Ver. 2.1.0 (2026-11-15) This module provides a template class for online cluster analysis. """ @@ -63,17 +65,14 @@ from typing import List, Tuple from abc import ABC, abstractmethod +from dataclasses import dataclass -try: - from matplotlib.figure import Figure -except: - class Figure : pass - -from mlpro.bf.events import Event as MLProEvent, EventManager -from mlpro.bf.math.properties import * -from mlpro.bf.streams import Instance, InstDict from mlpro.bf.various import * from mlpro.bf.plot import * +from mlpro.bf.events import * +from mlpro.bf.math.properties import * +from mlpro.bf.streams import Instance, InstDict +from mlpro.bf.ml import EventModeML from mlpro.oa.streams import OAStreamTask from mlpro.bf.math.normalizers import Normalizer @@ -82,11 +81,12 @@ class Figure : pass # Export list for public API -__all__ = [ 'ClusterActions', - 'ClusterInfrastructure', +__all__ = [ 'ResultItem', + 'ClusterActions', + 'EventConfigCA', 'ClusterAnalyzer', - 'ClusterId', - 'ResultItem' ] + 'ClusterInfrastructure', + 'ClusterAnalyzerExt' ] @@ -97,11 +97,19 @@ class Figure : pass ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- class ClusterActions (ABC): + """ + Abstract interface for cluster collections and cluster-relation queries. - # Possible result scopes for methods get_cluster_memberships() and get_cluster_influences() - C_RESULT_SCOPE_ALL : int = 0 - C_RESULT_SCOPE_MAX : int = 1 + The class provides the common clusters container and defines the public interface for evaluating + membership and influence of instances with respect to the currently managed clusters. It does + not prescribe how clusters are created, updated, removed, or stored beyond the public cluster + dictionary. + """ + # Possible result scopes for methods get_cluster_memberships() and get_cluster_influences() + C_RESULT_SCOPE_ALL : int = 0 + C_RESULT_SCOPE_MAX : int = 1 + C_RESULT_SCOPE_NONZERO : int = 2 ## ------------------------------------------------------------------------------------------------- def __init__( self ): @@ -114,24 +122,24 @@ def get_cluster_memberships( self, p_instance : Instance, p_scope : int = C_RESULT_SCOPE_MAX ) -> List[ResultItem]: """ - Method to determine the relative membership of the given instance to each cluster as a value - in [0,1]. - - See also: method Cluster.get_membership(). + Determines the relative memberships of an instance with respect to the managed clusters. + + The cluster-specific membership measure is provided by Cluster.get_membership() or an + equivalent implementation of the cluster interface. Parameters ---------- p_instance : Instance Instance to be evaluated. p_scope : int - Scope of the result list. See class attributes C_RESULT_SCOPE_* for possible values. Default - value is C_RESULT_SCOPE_MAX. + Scope of the result. Use C_RESULT_SCOPE_ALL for all clusters or C_RESULT_SCOPE_MAX for + the cluster with the highest membership. Returns ------- List[ResultItem] - List of membership items which are tuples of a cluster id, a relative membership value - in [0,1], and a reference to the cluster object. + Membership results as tuples of cluster id, membership value in [0,1], and the + corresponding cluster object. """ ... @@ -141,7 +149,29 @@ def get_cluster_memberships( self, @abstractmethod def get_cluster_influences( self, p_instance : Instance, - p_scope : int = C_RESULT_SCOPE_MAX ) -> List[ResultItem]: ... + p_scope : int = C_RESULT_SCOPE_MAX ) -> List[ResultItem]: + """ + Determines the relative influences of the managed clusters on an instance. + + The cluster-specific influence measure is provided by Cluster.get_influence() or an + equivalent implementation of the cluster interface. + + Parameters + ---------- + p_instance : Instance + Instance to be evaluated. + p_scope : int + Scope of the result. Use C_RESULT_SCOPE_ALL for all clusters or C_RESULT_SCOPE_MAX for + the cluster with the highest influence. + + Returns + ------- + List[ResultItem] + Influence results as tuples of cluster id, influence value >= 0, and the + corresponding cluster object. + """ + + ... @@ -149,39 +179,212 @@ def get_cluster_influences( self, ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class ClusterInfrastructure (ClusterActions): # EventManager, Plottable, +@dataclass +class EventConfigCA (EventConfig): """ - Base class for online cluster analysis. It raises an event when a cluster was added or removed. - - Steps to implement a new algorithm are: - - Create a new class and inherit from this base class - - Specify all cluster properties provided/maintained by your algorithm in C_CLUSTER_PROPERTIES. - - Implement method self._adapt() to update your cluster list on new instances - - Implement method self._adapt_reverse() to update your cluster list on obsolete instances - - New cluster: hand over self._cluster_properties.values() on instantiation - + Event configuration for cluster analyzers. + + The configuration extends the generic event configuration by switches for changes of the cluster + population. Both cluster-specific events are disabled by default and can be enabled independently + from outside the analyzer. + + Attributes + ---------- + CLUSTER_ADDED : EventModeML + Event mode for notifications about newly added clusters. + CLUSTER_REMOVED : EventModeML + Event mode for notifications about removed clusters. + """ + + CLUSTER_ADDED : EventModeML = EventModeML.OFF + CLUSTER_REMOVED : EventModeML = EventModeML.OFF + + + + + +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class ClusterAnalyzer (OAStreamTask, ClusterActions): + """ + Lightweight base class for online cluster analysis. + + ClusterAnalyzer combines the execution semantics of OAStreamTask with the abstract cluster + interface defined by ClusterActions. It intentionally does not prescribe a concrete cluster + implementation or cluster-management infrastructure. Specialized analyzers can therefore provide + their own high-performance cluster representation and storage while reusing the standard OA + stream-task, event, plotting, and adaptation mechanisms. + Parameters ---------- - p_cls_cluster - Cluster class (Class Cluster or a child class). - p_cluster_limit : int - Optional limit for clusters to be created. Default = 0 (no limit). - p_thrs_cluster_influence : float - Threshold for cluster influence. Default = 0.0. + p_name : str + Optional task name. Default is None. + p_range_max + Maximum range of asynchronicity. Default is OAStreamTask.C_RANGE_THREAD. + p_ada : bool + Enables or disables adaptivity. Default is True. + p_duplicate_data : bool + If True, incoming instances are duplicated before processing. Default is False. + p_event_config : EventConfigCA + Event configuration used by the analyzer. Default is EventConfigCA(). p_visualize : bool - Boolean switch for visualisation. Default = False. + Enables or disables visualization. Default is False. p_logging - Log level (see constants of class Log). Default: Log.C_LOG_ALL + Log level according to class Log. Default is Log.C_LOG_ALL. + **p_kwargs + Further optional keyword arguments forwarded to the underlying OA stream task. + """ + + C_TYPE = 'Cluster Analyzer' + + C_EVENT_CLUSTER_ADDED = 'CLUSTER_ADDED' + C_EVENT_CLUSTER_REMOVED = 'CLUSTER_REMOVED' + + C_PLOT_ACTIVE = True + C_PLOT_STANDALONE = False + +## ------------------------------------------------------------------------------------------------- + def __init__( self, + p_name: str = None, + p_range_max = OAStreamTask.C_RANGE_THREAD, + p_ada: bool = True, + p_duplicate_data: bool = False, + p_event_config : EventConfigCA = EventConfigCA(), + p_visualize: bool = False, + p_logging = Log.C_LOG_ALL, + **p_kwargs ): + + OAStreamTask.__init__( self, + p_name = p_name, + p_range_max = p_range_max, + p_ada = p_ada, + p_duplicate_data = p_duplicate_data, + p_event_config = p_event_config, + p_visualize = p_visualize, + p_logging = p_logging, + **p_kwargs ) + + ClusterActions.__init__( self ) + + +## ------------------------------------------------------------------------------------------------- + def _run(self, p_instances : InstDict): + """ + Processes a batch of stream instances by forwarding it to the adaptive model. + + Parameters + ---------- + p_instances : InstDict + Dictionary of stream instances to be processed. + """ + + self.adapt( p_instances = p_instances ) + + +## ------------------------------------------------------------------------------------------------- + def init_plot(self, p_figure: Figure = None, p_plot_settings: PlotSettings = None): + """ + Initializes the analyzer plot and propagates plot initialization to all current clusters. + + Parameters + ---------- + p_figure : Figure + Optional matplotlib figure. + p_plot_settings : PlotSettings + Optional plot settings. + """ + + if not self.get_visualization(): return + + super().init_plot( p_figure=p_figure, p_plot_settings=p_plot_settings) + + for cluster in self.clusters.values(): + cluster.init_plot(p_figure=p_figure, p_plot_settings = p_plot_settings) + + +## ------------------------------------------------------------------------------------------------- + def update_plot( self, + p_instances : InstDict = None, + **p_kwargs ): + """ + Updates the visualization of all current clusters. + + Parameters + ---------- + p_instances : InstDict + Optional stream instances related to the current update. + **p_kwargs + Further plot-specific keyword arguments forwarded to the clusters. + """ + + if not self.get_visualization(): return + + for cluster in self.clusters.values(): + cluster.update_plot( p_instances = p_instances, **p_kwargs) + + +## ------------------------------------------------------------------------------------------------- + def remove_plot(self, p_refresh:bool = True): + """ + Removes the plots of all current clusters. + + Parameters + ---------- + p_refresh : bool + If True, requests a display refresh after plot removal. Default is True. + """ + + if not self.get_visualization(): return + + for cluster in self.clusters.values(): + cluster.remove_plot( p_refresh = False) + + +## ------------------------------------------------------------------------------------------------- + def _renormalize(self, p_normalizer: Normalizer): + """ + Renormalizes all current clusters with the supplied normalizer. + + This hook is used by the OA task's event-driven renormalization mechanism. + + Parameters + ---------- + p_normalizer : Normalizer + Normalizer to be applied to all clusters. + """ + + for cluster in self.clusters.values(): + cluster.renormalize( p_normalizer=p_normalizer ) + + + + + +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class ClusterInfrastructure (ClusterActions): + """ + Reusable cluster-management infrastructure for cluster analyzers. + + This mixin implements cluster creation limits, cluster identifiers, cluster storage, and the + evaluation of membership and influence relations. It contains no task or stream-task semantics + of its own and is intended to be combined with ClusterAnalyzer or another compatible host class. + + Parameters + ---------- + p_cls_cluster : type + Cluster class used by the infrastructure. Default is Cluster. + p_cluster_limit : int + Maximum number of clusters. A value of 0 disables the limit. Default is 0. + p_thrs_cluster_influence : float + Optional lower threshold for cluster influence clipping. Default is None. Attributes ---------- - C_RESULT_SCOPE_ALL : int = 0 - Result scope, that includes all clusters - C_RESULT_SCOPE_MAX : int = 2 - Result scope, that includes just the cluster with the highest result value. C_CLUSTER_PROPERTIES : PropertyDefinitions - List of cluster properties supported/maintained by the algorithm. These properties - are handed over to each new cluster. + Property definitions maintained by the standard MLPro cluster infrastructure. + C_EPSILON_CI : float + Small offset used when shifting non-positive influence values. """ # List of cluster properties supported/maintained by the algorithm @@ -243,12 +446,12 @@ def align_cluster_properties( self, p_properties : PropertyDefinitions ) -> list ## ------------------------------------------------------------------------------------------------- def new_cluster_allowed(self) -> bool: """ - Determines whether adding a new cluster is allowed. + Checks whether another cluster may be added. Returns ------- bool - True, if adding a new cluster allowed. False otherwise. + True if the configured cluster limit has not been reached or no limit is active. """ return ( self._cluster_limit == 0 ) or ( len(self.clusters.keys()) < self._cluster_limit ) @@ -256,11 +459,29 @@ def new_cluster_allowed(self) -> bool: ## ------------------------------------------------------------------------------------------------- def get_cluster_cls(self): + """ + Returns the cluster class configured for this infrastructure. + + Returns + ------- + type + Configured cluster class. + """ + return self._cls_cluster ## ------------------------------------------------------------------------------------------------- def _get_next_cluster_id(self) -> ClusterId: + """ + Generates the next cluster identifier. + + Returns + ------- + ClusterId + Next monotonically increasing cluster id. + """ + self._next_cluster_id += 1 return self._next_cluster_id @@ -268,8 +489,9 @@ def _get_next_cluster_id(self) -> ClusterId: ## ------------------------------------------------------------------------------------------------- def _add_cluster(self, p_cluster:Cluster) -> bool: """ - Protected method to be used to add a new cluster. Please use as part of your algorithm. - Please use method new_cluster_allowed() before adding a cluster. + Adds a cluster to the managed cluster collection. + + Algorithms should call new_cluster_allowed() before invoking this method. Parameters ---------- @@ -282,29 +504,21 @@ def _add_cluster(self, p_cluster:Cluster) -> bool: if self.get_visualization(): p_cluster.init_plot( p_figure=self._figure, p_plot_settings=self.get_plot_settings() ) - # self._raise_event( p_event_id = self.C_EVENT_CLUSTER_ADDED, - # p_event_object = MLProEvent( p_raising_object = self, - # p_cluster = p_cluster ) ) - ## ------------------------------------------------------------------------------------------------- def _remove_cluster(self, p_cluster:Cluster): """ - Protected method to remove an existing cluster. Please use as part of your algorithm. + Removes a cluster from the managed cluster collection. Parameters ---------- p_cluster : Cluster - Cluster object to be added. + Cluster object to be removed. """ p_cluster.remove_plot(p_refresh=True) del self.clusters[p_cluster.id] - # self._raise_event( p_event_id = self.C_EVENT_CLUSTER_REMOVED, - # p_event_object = MLProEvent( p_raising_object = self, - # p_cluster = p_cluster ) ) - ## ------------------------------------------------------------------------------------------------- def _get_cluster_relations( self, @@ -313,28 +527,27 @@ def _get_cluster_relations( self, p_relative_values : bool , p_scope : int ) -> List[ResultItem]: """ - Internal method to determine the relation of the given instance to each cluster as a value in - percent. Currently supported relations are membership and influence. + Evaluates one cluster relation for the given instance across the managed clusters. - See also: public methods get_cluster_memberships() and get_cluster influences() + Relation type 0 evaluates membership, while type 1 evaluates influence. Influence values can + optionally be clipped by p_thrs_cluster_influence. If relative values are requested, the + absolute relation values are normalized over the selected result scope. - Parameters ---------- p_relation_type : int - Possible values are 0 (cluster membership) and 1 (cluster influence) + Relation type: 0 for membership or 1 for influence. p_instance : Instance Instance to be evaluated. p_relative_values : bool - If True, the result values are relative (i.e., normalized to the sum of all results). + If True, normalizes the resulting relation values. p_scope : int - Scope of the result list. See class attributes C_RESULT_SCOPE_* for possible values. + Result scope, typically C_RESULT_SCOPE_ALL or C_RESULT_SCOPE_MAX. Returns ------- - results : List[ResultItem] - List of result items which are tuples of a cluster id, a relative result - value in [0,1] and a reference to the cluster object. + List[ResultItem] + Evaluated cluster relations for the requested scope. """ # 1 Determination of membership values of the instance for all clusters @@ -404,24 +617,19 @@ def get_cluster_memberships( self, p_instance : Instance, p_scope : int = ClusterActions.C_RESULT_SCOPE_MAX ) -> List[ResultItem]: """ - Method to determine the relative membership of the given instance to each cluster as a value - in [0,1]. - - See also: method Cluster.get_membership(). + Determines relative cluster memberships for the given instance. Parameters ---------- p_instance : Instance Instance to be evaluated. p_scope : int - Scope of the result list. See class attributes C_RESULT_SCOPE_* for possible values. Default - value is C_RESULT_SCOPE_MAX. + Result scope. Default is C_RESULT_SCOPE_MAX. Returns ------- List[ResultItem] - List of membership items which are tuples of a cluster id, a relative membership value - in [0,1], and a reference to the cluster object. + Membership results as tuples of cluster id, relative membership, and cluster object. """ return self._get_cluster_relations( p_relation_type = 0, @@ -435,24 +643,19 @@ def get_cluster_influences( self, p_instance : Instance, p_scope : int = ClusterActions.C_RESULT_SCOPE_MAX ) -> List[ResultItem]: """ - Method to determine the relative influence of the given instance to each cluster as a value - in [0,1]. - - See also: method Cluster.get_influence(). + Determines relative cluster influences for the given instance. Parameters ---------- p_instance : Instance Instance to be evaluated. p_scope : int - Scope of the result list. See class attributes C_RESULT_SCOPE_* for possible values. Default - value is C_RESULT_SCOPE_MAX. + Result scope. Default is C_RESULT_SCOPE_MAX. Returns ------- List[ResultItem] - List of influence items which are tuples of a cluster id, a relative influence value in - [0,1], and a reference to the cluster object. + Influence results as tuples of cluster id, relative influence, and cluster object. """ return self._get_cluster_relations( p_relation_type = 1, @@ -466,63 +669,44 @@ def get_cluster_influences( self, ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class ClusterAnalyzer (OAStreamTask, ClusterInfrastructure): +class ClusterAnalyzerExt (ClusterAnalyzer, ClusterInfrastructure): """ - Base class for online cluster analysis. It raises an event when a cluster was added or removed. - - Steps to implement a new algorithm are: - - Create a new class and inherit from this base class - - Specify all cluster properties provided/maintained by your algorithm in C_CLUSTER_PROPERTIES. - - Implement method self._adapt() to update your cluster list on new instances - - Implement method self._adapt_reverse() to update your cluster list on obsolete instances - - New cluster: hand over self._cluster_properties.values() on instantiation - + Extended MLPro cluster analyzer with the standard cluster infrastructure. + + This convenience class combines the lightweight ClusterAnalyzer task layer with + ClusterInfrastructure. It represents the standard MLPro implementation for analyzers that use + MLPro cluster objects and the generic cluster-property infrastructure. + Parameters ---------- p_name : str - Optional name of the task. Default is None. - p_range_max : int - Maximum range of asynchonicity. See class Range. Default is Range.C_RANGE_PROCESS. + Optional task name. Default is None. + p_range_max + Maximum range of asynchronicity. Default is OAStreamTask.C_RANGE_PROCESS. p_ada : bool - Boolean switch for adaptivitiy. Default = True. + Enables or disables adaptivity. Default is True. p_duplicate_data : bool - If True, instances will be duplicated before processing. Default = False. - p_cls_cluster - Cluster class (Class Cluster or a child class). + If True, incoming instances are duplicated before processing. Default is False. + p_cls_cluster : type + Cluster class used by the infrastructure. Default is Cluster. p_cluster_limit : int - Optional limit for clusters to be created. Default = 0 (no limit). + Maximum number of clusters. A value of 0 disables the limit. Default is 0. p_thrs_cluster_influence : float - Threshold for cluster influence. Default = 0.0. + Optional threshold for cluster influence clipping. Default is None. p_visualize : bool - Boolean switch for visualisation. Default = False. + Enables or disables visualization. Default is False. p_logging - Log level (see constants of class Log). Default: Log.C_LOG_ALL - p_kwargs : dict - Further optional named parameters. - - Attributes - ---------- - C_RESULT_SCOPE_ALL : int = 0 - Result scope, that includes all clusters - C_RESULT_SCOPE_MAX : int = 2 - Result scope, that includes just the cluster with the highest result value. - C_CLUSTER_PROPERTIES : PropertyDefinitions - List of cluster properties supported/maintained by the algorithm. These properties - are handed over to each new cluster. + Log level according to class Log. Default is Log.C_LOG_ALL. + **p_kwargs + Further optional keyword arguments forwarded to ClusterAnalyzer. """ - C_TYPE = 'Cluster Analyzer' - - C_EVENT_CLUSTER_ADDED = 'CLUSTER_ADDED' - C_EVENT_CLUSTER_REMOVED = 'CLUSTER_REMOVED' - - C_PLOT_ACTIVE = True - C_PLOT_STANDALONE = False + C_TYPE = 'Cluster Analyzer (Ext)' ## ------------------------------------------------------------------------------------------------- def __init__( self, p_name: str = None, - p_range_max = OAStreamTask.C_RANGE_THREAD, + p_range_max = OAStreamTask.C_RANGE_PROCESS, p_ada: bool = True, p_duplicate_data: bool = False, p_cls_cluster : type = Cluster, @@ -532,77 +716,16 @@ def __init__( self, p_logging = Log.C_LOG_ALL, **p_kwargs ): - OAStreamTask.__init__( self, - p_name = p_name, - p_range_max = p_range_max, - p_ada = p_ada, - p_duplicate_data = p_duplicate_data, - p_visualize = p_visualize, - p_logging = p_logging, - **p_kwargs ) + ClusterAnalyzer.__init__( self, + p_name = p_name, + p_range_max = p_range_max, + p_ada = p_ada, + p_duplicate_data = p_duplicate_data, + p_visualize = p_visualize, + p_logging = p_logging, + **p_kwargs ) ClusterInfrastructure.__init__( self, p_cls_cluster = p_cls_cluster, p_cluster_limit = p_cluster_limit, - p_thrs_cluster_influence = p_thrs_cluster_influence ) - - -## ------------------------------------------------------------------------------------------------- - def _run(self, p_instances : InstDict): - self.adapt( p_instances = p_instances ) - - -## ------------------------------------------------------------------------------------------------- - def init_plot(self, p_figure: Figure = None, p_plot_settings: PlotSettings = None): - - if not self.get_visualization(): return - - super().init_plot( p_figure=p_figure, p_plot_settings=p_plot_settings) - - for cluster in self.clusters.values(): - cluster.init_plot(p_figure=p_figure, p_plot_settings = p_plot_settings) - - -## ------------------------------------------------------------------------------------------------- - def update_plot( self, - p_instances : InstDict = None, - **p_kwargs ): - - if not self.get_visualization(): return - - for cluster in self.clusters.values(): - cluster.update_plot( p_instances = p_instances, **p_kwargs) - - -## ------------------------------------------------------------------------------------------------- - def remove_plot(self, p_refresh:bool = True): - """" - Removes the plot and optionally refreshes the display. - - Parameters - ---------- - p_refresh : bool = True - On True the display is refreshed after removal - """ - - if not self.get_visualization(): return - - for cluster in self.clusters.values(): - cluster.remove_plot( p_refresh = False) - - -## ------------------------------------------------------------------------------------------------- - def _renormalize(self, p_normalizer: Normalizer): - """ - Internal renormalization of all clusters. See method OATask.renormalize_on_event() for further - information. - - Parameters - ---------- - p_normalizer : Normalizer - Normalizer object to be applied on task-specific - """ - - for cluster in self.clusters.values(): - cluster.renormalize( p_normalizer=p_normalizer ) - + p_thrs_cluster_influence = p_thrs_cluster_influence ) \ No newline at end of file diff --git a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/basics.py b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/basics.py index 7fec32b46..1eaa534dc 100644 --- a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/basics.py +++ b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/basics.py @@ -41,27 +41,28 @@ ## -- 2024-07-08 2.1.0 DA Class Cluster: hand over of kwargs to inner properties ## -- 2025-06-06 2.2.0 DA Refactoring: p_inst -> p_instances ## -- 2025-06-11 2.3.0 DA New method Cluster.update_properties() +## -- 2026-11-02 2.4.0 DA New class ClusterAPI ## ------------------------------------------------------------------------------------------------- """ -Ver. 2.3.0 (2025-06-11) +Ver. 2.4.0 (2026-11-02) This module provides a template class for clusters to be used in cluster analyzer algorithms. """ - +from abc import ABC, abstractmethod from mlpro.bf.various import Id, KWArgs, TStampType -from mlpro.bf.plot import PlotSettings +from mlpro.bf.plot import PlotSettings, Plottable from mlpro.bf.math.properties import PropertyDefinitions, Properties from mlpro.bf.streams import Instance # Export list for public API -__all__ = [ 'Cluster', - 'ClusterId' ] - +__all__ = [ 'ClusterId', + 'ClusterAPI', + 'Cluster' ] @@ -71,20 +72,23 @@ ## ------------------------------------------------------------------------------------------------- ## ------------------------------------------------------------------------------------------------- -class Cluster (Id, Properties, KWArgs): +class ClusterAPI (ABC, Id, Plottable): """ - Universal template class for a cluster with any number of properties added by a cluster analyzer. + Minimal abstract representation of a cluster. + + ClusterAPI defines only the generic cluster identity, optional visualization support, and the + two relation operations required by cluster analyzers. It is intentionally independent of + MLPro's property model and can therefore serve as a lightweight base for specialized or + high-performance cluster implementations. Parameters ---------- p_id : ClusterId - Unique cluster id. - p_properties : PropertyDefinitions - List of property definitions. + Unique cluster identifier. + p_color : str + Optional plot color. Default is None. p_visualize : bool - Boolean switch for visualisation. Default = False. - p_kwargs : dict - Further parameters. + Enables or disables visualization. Default is False. """ C_PLOT_ACTIVE = True @@ -108,70 +112,134 @@ class Cluster (Id, Properties, KWArgs): ## ------------------------------------------------------------------------------------------------- def __init__( self, p_id : ClusterId, - p_properties : PropertyDefinitions = [], - p_visualize : bool = False, - **p_kwargs ): + p_color : str = None, + p_visualize : bool = False ): - KWArgs.__init__( self, **p_kwargs ) - Properties.__init__( self, p_properties = p_properties, p_visualize = p_visualize, **p_kwargs ) Id.__init__( self, p_id = p_id ) + Plottable.__init__( self, p_visualize = p_visualize ) + self.color : str = p_color -## ------------------------------------------------------------------------------------------------- - def set_plot_color(self, p_color): - Properties.set_plot_color( self, p_color = p_color) - ## ------------------------------------------------------------------------------------------------- + @abstractmethod def get_membership(self, p_instance : Instance ) -> float: """ - Custom method to determine a scalar membership value for the given instance. + Determines the membership of an instance in this cluster. + + Concrete cluster implementations define the membership semantics appropriate to their + representation. Parameters ---------- p_instance : Instance - Instance to be examined for membership. + Instance to be evaluated. Returns ------- float - A scalar value in [0,1] that determines the given instance's membership in this cluster. - A value of 0 means that the given instance is not a member of the cluster at all while - a value of 1 confirms full membership. + Membership value in [0,1], where 0 denotes no membership and 1 full membership. """ - raise NotImplementedError + ... ## ------------------------------------------------------------------------------------------------- + @abstractmethod def get_influence(self, p_instance : Instance ) -> float: """ - Custom method to compute a scalar influence value for the given instance. + Determines the influence of this cluster on an instance. + + Concrete cluster implementations define the influence semantics appropriate to their + representation. Parameters ---------- p_instance : Instance - Instance to be examined for its influence to the cluster. + Instance to be evaluated. Returns ------- float - Scalar value >= 0 that determines the influence of the cluster on the specified instance. - A value 0 means that the cluster has no influence on the instance at all. + Non-negative influence value, where 0 denotes no influence. """ - raise NotImplementedError + ... + + + +## ------------------------------------------------------------------------------------------------- +## ------------------------------------------------------------------------------------------------- +class Cluster (ClusterAPI, Properties, KWArgs): + """ + Property-based MLPro cluster template. + + Cluster extends the lightweight ClusterAPI by MLPro's generic Properties and KWArgs mechanisms. + It is intended for conventional MLPro cluster analyzers that benefit from dynamically configured + cluster properties. The concrete membership and influence semantics remain the responsibility of + specialized subclasses. + + Parameters + ---------- + p_id : ClusterId + Unique cluster identifier. + p_properties : PropertyDefinitions + Property definitions to be instantiated for the cluster. + p_color : str + Optional plot color. Default is None. + p_visualize : bool + Enables or disables visualization. Default is False. + **p_kwargs + Further keyword arguments used by the property infrastructure. + """ + +## ------------------------------------------------------------------------------------------------- + def __init__( self, + p_id : ClusterId, + p_properties : PropertyDefinitions = [], + p_color : str = None, + p_visualize : bool = False, + **p_kwargs ): + + KWArgs.__init__( self, **p_kwargs ) + Properties.__init__( self, + p_properties = p_properties, + p_visualize = p_visualize, + **p_kwargs ) + ClusterAPI.__init__( self, + p_id = p_id, + p_color = p_color, + p_visualize = p_visualize ) + + +## ------------------------------------------------------------------------------------------------- + def set_plot_color(self, p_color): + """ + Sets the plot color of the cluster and its property-based visualization. + + Parameters + ---------- + p_color + Plot color to be applied. + """ + + Properties.set_plot_color( self, p_color = p_color) + + ## ------------------------------------------------------------------------------------------------- def update_properties(self, p_tstamp : TStampType ): """ - Custom method to update inner cluster properties. To be triggered by the cluster analyzer. + Updates the cluster's internal properties. + + This hook is intended to be triggered by the surrounding cluster analyzer and can be + redefined by specialized cluster classes. Parameters ---------- p_tstamp : TStampType - Time stamp of property update. + Time stamp of the property update. """ pass diff --git a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/body.py b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/body.py index c099d0491..ef8f436a8 100644 --- a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/body.py +++ b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/body.py @@ -45,18 +45,21 @@ ## ------------------------------------------------------------------------------------------------- class ClusterBody (ClusterCentroid): """ - Template class for clusters with a centroid and a body. + Property-based cluster with centroid and explicit geometric body. + + ClusterBody extends ClusterCentroid by a body representation and derived geometric properties + such as body size, geometric center, deformation index, and density. Parameters ---------- p_id : ClusterId - ID of the cluster. + Unique cluster identifier. p_properties : PropertyDefinitions - List of property definitions. + Additional property definitions. p_visualize : bool - Boolean switch for visualisation. Default = False. - p_kwargs : dict - Keyword parameters. + Enables or disables visualization. Default is False. + **p_kwargs + Further keyword arguments forwarded to the parent cluster implementation. """ C_PROPERTIES = [ cprop_centroid, @@ -86,11 +89,33 @@ def __init__( self, ## ------------------------------------------------------------------------------------------------- def get_membership(self, p_instance : Instance ) -> float: + """ + Determines instance membership using the cluster body's membership model. + + Parameters + ---------- + p_instance : Instance + Instance to be evaluated. + + Returns + ------- + float + Membership value returned by the body representation. + """ + return self.body.get_membership( p_instance = p_instance ) ## ------------------------------------------------------------------------------------------------- def _update_density(self, p_tstamp : TStampType): + """ + Updates the density from cluster size and geometric body size. + + Parameters + ---------- + p_tstamp : TStampType + Time stamp assigned to the density update. + """ if self.size_geo.value != 0: density = self.size.value / self.size_geo.value @@ -99,6 +124,15 @@ def _update_density(self, p_tstamp : TStampType): ## ------------------------------------------------------------------------------------------------- def update_properties(self, p_tstamp : TStampType): + """ + Updates inherited and body-specific cluster properties. + + Parameters + ---------- + p_tstamp : TStampType + Time stamp assigned to the property updates. + """ + super().update_properties( p_tstamp = p_tstamp ) self._update_density( p_tstamp = p_tstamp ) self.body.update_deformation_index( p_tstamp = p_tstamp ) \ No newline at end of file diff --git a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/centroid.py b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/centroid.py index bc0b78aed..95e753e4e 100644 --- a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/centroid.py +++ b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/centroid.py @@ -65,12 +65,16 @@ ## ------------------------------------------------------------------------------------------------- class ClusterCentroid (Cluster): """ - Extended cluster class with a centroid. + Property-based cluster specialization with a centroid. + + The class adds a centroid property and provides a default distance-based influence measure. + Membership remains undefined because it depends on the concrete cluster shape and therefore has + to be implemented by a further specialization. Attributes ---------- - centroid : Centroid - Centroid object. + centroid + Centroid property of the cluster. """ C_PROPERTIES = [ cprop_centroid ] @@ -78,6 +82,15 @@ class ClusterCentroid (Cluster): # ## ------------------------------------------------------------------------------------------------- def set_id(self, p_id): + """ + Sets the cluster id and keeps the centroid id synchronized. + + Parameters + ---------- + p_id + New cluster identifier. + """ + super().set_id( p_id = p_id ) self.centroid.id = p_id @@ -85,8 +98,20 @@ def set_id(self, p_id): ## ------------------------------------------------------------------------------------------------- def get_influence(self, p_instance: Instance) -> float: """ - Default strategy to determine the influence of a cluster on a specified instance based - on the metric distance between the instance and the cluster centroid. + Determines cluster influence from the metric distance to the centroid. + + The influence is computed as the inverse centroid distance with C_EPSILON added to the + denominator to avoid division by zero. + + Parameters + ---------- + p_instance : Instance + Instance to be evaluated. + + Returns + ------- + float + Positive influence value that decreases with increasing distance to the centroid. """ feature_data = p_instance.get_feature_data() diff --git a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/properties/centroid.py b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/properties/centroid.py index 445aac97f..d6423bcf1 100644 --- a/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/properties/centroid.py +++ b/src/mlpro/oa/streams/tasks/clusteranalyzers/clusters/properties/centroid.py @@ -17,10 +17,11 @@ ## -- 2025-03-19 0.8.2 DA Removed property definitions cprop_center_geo* ## -- 2025-06-08 0.9.0 DA Refactoring of Centroid._update_plot*: new return parameter ## -- 2025-06-25 1.0.0 DA Class Crosshair: implementation of nD plot methods +## -- 2026-09-28 1.0.1 DA Bugfix (illegal import) ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.0.0 (2025-06-25) +Ver. 1.0.1 (2026-09-28) This module provides the cluster property class 'Centroid'. @@ -36,7 +37,6 @@ class Text : pass class Line3D : pass class Text3D : pass -from mlpro.bf.mt import Figure, PlotSettings from mlpro.bf.various import * from mlpro.bf.plot import * from mlpro.bf.streams import * diff --git a/src/setup.py b/src/setup.py index 1154684a2..ee3cb3e1c 100644 --- a/src/setup.py +++ b/src/setup.py @@ -2,7 +2,7 @@ setup(name='mlpro', -version='2.2.1', +version='2.3.0', description='MLPro - The integrative middleware framework for standardized machine learning', author='blueAIC', author_mail='mlpro@blueaic.com', diff --git a/test/howtos/bf/eh/howto_bf_eh_001_event_handling.py b/test/howtos/bf/eh/howto_bf_eh_001_event_handling.py index 44afd85c4..d75896614 100644 --- a/test/howtos/bf/eh/howto_bf_eh_001_event_handling.py +++ b/test/howtos/bf/eh/howto_bf_eh_001_event_handling.py @@ -7,10 +7,11 @@ ## -- yyyy-mm-dd Ver. Auth. Description ## -- 2022-08-21 1.0.0 DA Creation/release ## -- 2022-10-12 1.0.1 DA Refactoring/Renaming +## -- 2026-10-05 1.1.0 DA Refactoring ## ------------------------------------------------------------------------------------------------- """ -Ver. 1.0.1 (2022-10-12) +Ver. 1.1.0 (2026-10-05) This module demonstrates the use of MLPro's event handling as a property in own classes. To this regard, a demo class MyMainClass is set up that inherits event functionalities from MLPro's class @@ -38,12 +39,10 @@ # 1 Definition of custom class that inherits event management functionalities from MLPro's class EventManager class MyMainClass (EventManager): - C_NAME = 'My main class' - C_EVENT_OWN = 'MYEVENT' - def __init__(self, p_logging=Log.C_LOG_ALL): - super().__init__(p_logging) + def __init__(self): + super().__init__() def do_something(self): @@ -73,7 +72,7 @@ def myhandler(self, p_event_id, p_event_object:Event): else: # 3.2 Unit test mode myhandlerobj = MyHandlerClass(p_logging=Log.C_LOG_NOTHING) - mymainobj = MyMainClass(p_logging=Log.C_LOG_NOTHING) + mymainobj = MyMainClass() # 4 Own event handler is registered on main class diff --git a/test/howtos/bf/math/howto_bf_math_011_normalizers.py b/test/howtos/bf/math/howto_bf_math_011_normalizers.py index a760fe54b..b18d0adcf 100644 --- a/test/howtos/bf/math/howto_bf_math_011_normalizers.py +++ b/test/howtos/bf/math/howto_bf_math_011_normalizers.py @@ -183,4 +183,32 @@ # 16. Validating the renormalization normalized_state = my_normalizer_minmax.normalize(my_state.copy()) if p_printing: - print('16. Normalized value (Validation renormalization):\n', normalized_state.get_values(),'\n\n') \ No newline at end of file + print('16. Normalized value (Validation renormalization):\n', normalized_state.get_values(),'\n\n') + +# 17. Validating optimized renormalization against the original two-step operation +# on a numpy dataset, including dimension-wise and explicit parameters +old_param = my_normalizer_minmax._scaler_param_old.copy() +new_param = my_normalizer_minmax._scaler_param_new.copy() + +data_old = np.array([[0.1, -0.4], [0.5, 0.7]], dtype=np.float64) +expected = (data_old - old_param[1]) / old_param[0] * new_param[0] + new_param[1] +actual = my_normalizer_minmax.renormalize(data_old.copy()) +np.testing.assert_allclose(actual, expected, rtol=1e-12, atol=1e-12) + +expected_dim = data_old.copy() +expected_dim[:, 1] = (data_old[:, 1] - old_param[1, 1]) / old_param[0, 1] * new_param[0, 1] + new_param[1, 1] +actual_dim = my_normalizer_minmax.renormalize(data_old.copy(), p_dim=1) +np.testing.assert_allclose(actual_dim, expected_dim, rtol=1e-12, atol=1e-12) + +explicit_old = np.array([[2.0, 0.5], [1.0, -3.0]]) +explicit_new = np.array([[4.0, 3.0], [-1.0, 2.0]]) +explicit_expected = (data_old - explicit_old[1]) / explicit_old[0] * explicit_new[0] + explicit_new[1] +explicit_actual = my_normalizer_minmax.renormalize( + data_old.copy(), + p_param_old=explicit_old, + p_param_new=explicit_new, +) +np.testing.assert_allclose(explicit_actual, explicit_expected, rtol=1e-12, atol=1e-12) + +if p_printing: + print('17. Optimized renormalization validated against two-step transformation')