nff-normalized-factor-flow 0.1.0__py3-none-any.whl

nff/__init__.py

@@ -0,0 +1,28 @@
+"""NFF — Normalized Factor Flow.
+
+This archive contains the package structure and reusable data utilities.
+The original NFF analysis engine still needs to be integrated; see INTEGRATION.md.
+"""
+
+from .comparison import compare_signatures
+from .containers import create_containers
+from .core import Flow, NFFEngine
+from .data import load_csv, load_numpy
+from .normalization import normalize
+from .results import AnalysisResult
+from .exporters import export_csv, export_json
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AnalysisResult",
+    "Flow",
+    "NFFEngine",
+    "compare_signatures",
+    "create_containers",
+    "export_csv",
+    "export_json",
+    "load_csv",
+    "load_numpy",
+    "normalize",
+]

nff/cli.py

@@ -0,0 +1,48 @@
+"""Command-line interface for the NFF package."""
+
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="nff", description="Normalized Factor Flow utilities")
+    parser.add_argument("--version", action="version", version=f"NFF {__version__}")
+    sub = parser.add_subparsers(dest="command")
+    sub.add_parser("info", help="Display package and integration status")
+    sub.add_parser("doctor", help="Check optional runtime dependencies")
+    return parser
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    if args.command == "doctor":
+        try:
+            import torch  # noqa: F401
+            print("PyTorch: available")
+        except ImportError:
+            print("PyTorch: not installed (install with: pip install 'nff-normalized-factor-flow[engine]')")
+        try:
+            import matplotlib  # noqa: F401
+            print("Matplotlib: available")
+        except ImportError:
+            print("Matplotlib: not installed (optional)")
+        try:
+            import serial  # noqa: F401
+            print("PySerial: available")
+        except ImportError:
+            print("PySerial: not installed (optional)")
+        return 0
+    if args.command == "info":
+        print(f"NFF {__version__}")
+        print("Package scaffold: original NFF analysis engine not yet integrated.")
+        print("See INTEGRATION.md before publishing a functional release.")
+        return 0
+    build_parser().print_help()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

nff/comparison.py

@@ -0,0 +1,37 @@
+"""Generic signature comparison metrics."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+
+Metric = Literal["cosine", "euclidean", "manhattan"]
+
+
+def compare_signatures(left: object, right: object, *, metric: Metric = "cosine") -> float:
+    """Compare two equally-sized numeric vectors.
+
+    Cosine returns similarity in [-1, 1]. Euclidean and Manhattan return distances.
+    This is a generic vector comparison utility, not an NFF-defined distance unless
+    the project specification explicitly adopts it.
+    """
+    a = np.asarray(left, dtype=np.float64)
+    b = np.asarray(right, dtype=np.float64)
+    if a.ndim != 1 or b.ndim != 1:
+        raise ValueError("Both signatures must be one-dimensional.")
+    if a.shape != b.shape:
+        raise ValueError("Signatures must have identical dimensions.")
+    if not np.isfinite(a).all() or not np.isfinite(b).all():
+        raise ValueError("Signatures must contain only finite values.")
+
+    if metric == "cosine":
+        denom = float(np.linalg.norm(a) * np.linalg.norm(b))
+        if denom == 0:
+            return 1.0 if np.array_equal(a, b) else 0.0
+        return float(np.dot(a, b) / denom)
+    if metric == "euclidean":
+        return float(np.linalg.norm(a - b))
+    if metric == "manhattan":
+        return float(np.abs(a - b).sum())
+    raise ValueError("metric must be 'cosine', 'euclidean', or 'manhattan'.")

nff/containers.py

@@ -0,0 +1,42 @@
+"""Utilities to split a continuous flow into temporal containers."""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+import numpy as np
+
+
+def create_containers(
+    data: Iterable[float] | np.ndarray,
+    size: int,
+    *,
+    stride: int | None = None,
+    drop_remainder: bool = False,
+) -> list[np.ndarray]:
+    """Split one-dimensional data into possibly overlapping windows.
+
+    Parameters are generic segmentation controls; they do not impose or infer
+    the canonical NFF Container Delay or NUA configuration.
+    """
+    values = np.asarray(data, dtype=np.float64)
+    if values.ndim != 1:
+        raise ValueError("data must be one-dimensional.")
+    if values.size == 0:
+        raise ValueError("data cannot be empty.")
+    if size <= 0:
+        raise ValueError("size must be greater than zero.")
+    step = size if stride is None else stride
+    if step <= 0:
+        raise ValueError("stride must be greater than zero.")
+
+    result: list[np.ndarray] = []
+    for start in range(0, values.size, step):
+        window = values[start : start + size]
+        if window.size < size and drop_remainder:
+            break
+        if window.size:
+            result.append(window.copy())
+        if start + size >= values.size:
+            break
+    return result

nff/core.py

@@ -0,0 +1,87 @@
+"""Public NFF objects. The project's original analysis engine is integrated separately."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Iterable
+
+import numpy as np
+
+from .results import AnalysisResult
+
+
+@dataclass(slots=True)
+class Flow:
+    """A one-dimensional numeric data flow.
+
+    Parameters
+    ----------
+    data:
+        Iterable of numeric samples or a NumPy array.
+    name:
+        Optional human-readable flow name.
+    sampling_rate:
+        Optional sampling frequency in samples per second.
+    """
+
+    data: np.ndarray
+    name: str = "flow"
+    sampling_rate: float | None = None
+
+    def __init__(
+        self,
+        data: Iterable[float] | np.ndarray,
+        name: str = "flow",
+        sampling_rate: float | None = None,
+    ) -> None:
+        values = np.asarray(data, dtype=np.float64)
+        if values.ndim != 1:
+            raise ValueError("Flow data must be one-dimensional.")
+        if values.size == 0:
+            raise ValueError("Flow data cannot be empty.")
+        if not np.isfinite(values).all():
+            raise ValueError("Flow data must contain only finite numeric values.")
+        if sampling_rate is not None and sampling_rate <= 0:
+            raise ValueError("sampling_rate must be greater than zero.")
+        self.data = values
+        self.name = str(name)
+        self.sampling_rate = sampling_rate
+
+    def __len__(self) -> int:
+        return int(self.data.size)
+
+    def __array__(self, dtype: Any = None) -> np.ndarray:
+        return np.asarray(self.data, dtype=dtype)
+
+
+class NFFEngine:
+    """Entry point reserved for the original NFF analysis implementation.
+
+    The public repository's main.py could not be downloaded in the archive-building
+    environment. This class deliberately does not substitute a made-up ORDER or
+    NUA formula. Integrate the original algorithm as described in INTEGRATION.md.
+    """
+
+    def __init__(self, *, device: str = "auto", dtype: str = "float64") -> None:
+        if device not in {"auto", "cpu", "cuda"}:
+            raise ValueError("device must be 'auto', 'cpu', or 'cuda'.")
+        if dtype not in {"float32", "float64"}:
+            raise ValueError("dtype must be 'float32' or 'float64'.")
+        self.device = device
+        self.dtype = dtype
+
+    def analyze(self, flow: Flow | Iterable[float] | np.ndarray) -> AnalysisResult:
+        """Run the canonical NFF algorithm.
+
+        Raises
+        ------
+        NotImplementedError
+            Until the original engine from the repository's main.py is integrated.
+        """
+        if not isinstance(flow, Flow):
+            flow = Flow(flow)
+        raise NotImplementedError(
+            "The canonical NFF engine has not been integrated into this package scaffold. "
+            "See INTEGRATION.md and add the original repository's main.py implementation "
+            "before publishing a functional NFF release."
+        )

nff/data.py

@@ -0,0 +1,38 @@
+"""Input helpers for common numeric data formats."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+
+
+def load_csv(path: str | Path, *, column: int = 0, delimiter: str = ",", skip_header: int = 0) -> np.ndarray:
+    """Load one numeric column from a CSV file."""
+    if column < 0:
+        raise ValueError("column must be zero or greater.")
+    table = np.genfromtxt(path, delimiter=delimiter, skip_header=skip_header, dtype=np.float64)
+    if table.size == 0:
+        raise ValueError("The CSV file contains no numeric data.")
+    if table.ndim == 1:
+        if column != 0:
+            raise IndexError("Requested column does not exist in this one-column CSV.")
+        values = table
+    else:
+        if column >= table.shape[1]:
+            raise IndexError(f"column {column} is outside CSV width {table.shape[1]}.")
+        values = table[:, column]
+    values = np.asarray(values, dtype=np.float64).reshape(-1)
+    if not np.isfinite(values).all():
+        raise ValueError("Selected CSV column contains missing or non-finite values.")
+    return values
+
+
+def load_numpy(path: str | Path, *, allow_pickle: bool = False) -> np.ndarray:
+    """Load an array from a .npy file."""
+    data: Any = np.load(path, allow_pickle=allow_pickle)
+    values = np.asarray(data, dtype=np.float64)
+    if values.size == 0 or not np.isfinite(values).all():
+        raise ValueError("NumPy file must contain non-empty finite numeric data.")
+    return values

nff/exporters.py

@@ -0,0 +1,47 @@
+"""Export numeric arrays and structured results."""
+
+from __future__ import annotations
+
+import csv
+import json
+from dataclasses import asdict, is_dataclass
+from pathlib import Path
+from typing import Any, Mapping
+
+import numpy as np
+
+
+def _jsonable(value: Any) -> Any:
+    if isinstance(value, np.ndarray):
+        return value.tolist()
+    if isinstance(value, np.generic):
+        return value.item()
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable(asdict(value))
+    if isinstance(value, Mapping):
+        return {str(k): _jsonable(v) for k, v in value.items()}
+    if isinstance(value, (list, tuple)):
+        return [_jsonable(v) for v in value]
+    return value
+
+
+def export_json(data: Any, path: str | Path, *, indent: int = 2) -> Path:
+    """Write a result or mapping as UTF-8 JSON and return the output path."""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_text(json.dumps(_jsonable(data), indent=indent, ensure_ascii=False), encoding="utf-8")
+    return target
+
+
+def export_csv(data: object, path: str | Path, *, header: str = "value") -> Path:
+    """Write a one-dimensional numeric sequence to CSV."""
+    values = np.asarray(data)
+    if values.ndim != 1:
+        raise ValueError("CSV export expects one-dimensional data.")
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("w", newline="", encoding="utf-8") as stream:
+        writer = csv.writer(stream)
+        writer.writerow([header])
+        writer.writerows([[value.item() if isinstance(value, np.generic) else value] for value in values])
+    return target

nff/normalization.py

@@ -0,0 +1,40 @@
+"""General-purpose normalization helpers (not a replacement for NFF's own method)."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+import numpy as np
+
+Method = Literal["zscore", "minmax", "robust"]
+
+
+def normalize(data: object, method: Method = "zscore", *, axis: int | None = None) -> np.ndarray:
+    """Normalize numeric data using z-score, min-max, or robust scaling.
+
+    Constant ranges are returned as zeros. This utility is independent from the
+    canonical NFF normalization pipeline, which must be ported from the source engine.
+    """
+    values = np.asarray(data, dtype=np.float64)
+    if values.size == 0:
+        raise ValueError("data cannot be empty.")
+    if not np.isfinite(values).all():
+        raise ValueError("data must contain only finite numeric values.")
+
+    if method == "zscore":
+        center = np.mean(values, axis=axis, keepdims=axis is not None)
+        scale = np.std(values, axis=axis, keepdims=axis is not None)
+    elif method == "minmax":
+        center = np.min(values, axis=axis, keepdims=axis is not None)
+        scale = np.max(values, axis=axis, keepdims=axis is not None) - center
+    elif method == "robust":
+        center = np.median(values, axis=axis, keepdims=axis is not None)
+        q75 = np.percentile(values, 75, axis=axis, keepdims=axis is not None)
+        q25 = np.percentile(values, 25, axis=axis, keepdims=axis is not None)
+        scale = q75 - q25
+    else:
+        raise ValueError("method must be 'zscore', 'minmax', or 'robust'.")
+
+    safe_scale = np.where(np.asarray(scale) == 0, 1.0, scale)
+    result = (values - center) / safe_scale
+    return np.where(np.asarray(scale) == 0, 0.0, result)

nff/results.py

@@ -0,0 +1,24 @@
+"""Result container for NFF analyses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+import numpy as np
+
+
+@dataclass(slots=True)
+class AnalysisResult:
+    """Structured result returned by the NFF analysis engine."""
+
+    order: float
+    signature: np.ndarray
+    metrics: dict[str, Any] = field(default_factory=dict)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self.order = float(self.order)
+        self.signature = np.asarray(self.signature, dtype=np.float64)
+        if self.signature.ndim != 1:
+            raise ValueError("signature must be one-dimensional.")

nff_normalized_factor_flow-0.1.0.dist-info/METADATA

@@ -0,0 +1,147 @@
+Metadata-Version: 2.4
+Name: nff-normalized-factor-flow
+Version: 0.1.0
+Summary: Python package scaffold for Normalized Factor Flow (NFF).
+Author: Elxrth
+Project-URL: Homepage, https://github.com/Elxrth/NFF-normalized-factor-flow
+Project-URL: Repository, https://github.com/Elxrth/NFF-normalized-factor-flow
+Project-URL: Issues, https://github.com/Elxrth/NFF-normalized-factor-flow/issues
+Keywords: data-streams,signal-analysis,time-series,normalized-factor-flow
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Provides-Extra: engine
+Requires-Dist: torch>=2.0; extra == "engine"
+Provides-Extra: plot
+Requires-Dist: matplotlib>=3.7; extra == "plot"
+Provides-Extra: serial
+Requires-Dist: pyserial>=3.5; extra == "serial"
+Provides-Extra: all
+Requires-Dist: torch>=2.0; extra == "all"
+Requires-Dist: matplotlib>=3.7; extra == "all"
+Requires-Dist: pyserial>=3.5; extra == "all"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+
+# NFF — Normalized Factor Flow
+
+Python package migration scaffold for [Elxrth/NFF-normalized-factor-flow](https://github.com/Elxrth/NFF-normalized-factor-flow).
+
+> **Important status:** this archive provides the packaging layout, installation metadata,
+> tests, command-line entry point, and reusable data utilities. It does **not** contain the
+> original `main.py` analysis implementation. The source file could not be retrieved while
+> preparing this ZIP, so no NUA, normalization, signature, or ORDER formula has been recreated
+> or guessed. Follow [`INTEGRATION.md`](INTEGRATION.md) to integrate the actual engine before
+> publishing a functional NFF release to PyPI.
+
+## Requirements
+
+- Python 3.10 or newer
+- NumPy 1.24 or newer
+- PyTorch is an optional extra in this scaffold; install it when integrating/running the
+  original PyTorch engine.
+
+## Install for development
+
+```bash
+git clone https://github.com/Elxrth/NFF-normalized-factor-flow.git
+cd NFF-normalized-factor-flow
+python -m venv .venv
+```
+
+Windows PowerShell:
+
+```powershell
+.venv\Scripts\Activate.ps1
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev,engine]"
+```
+
+Linux / macOS:
+
+```bash
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e '.[dev,engine]'
+```
+
+For a CUDA-enabled PyTorch build, install the build matching your CUDA/runtime from the
+[official PyTorch install selector](https://pytorch.org/get-started/locally/) before installing
+this project with `--no-deps`, or adjust the project extras to your supported CUDA index.
+
+## Current utility API
+
+```python
+import nff
+import numpy as np
+
+flow = nff.Flow(np.sin(np.linspace(0, 10, 2_000)), name="sensor", sampling_rate=100)
+containers = nff.create_containers(flow.data, size=256, stride=128)
+normalized = nff.normalize(containers[0], method="zscore")
+
+print(len(flow))
+print(normalized[:5])
+```
+
+Available utilities:
+
+| API | Purpose |
+| --- | --- |
+| `nff.Flow(data)` | Validated one-dimensional numeric flow |
+| `nff.create_containers(data, size, stride=...)` | Split a stream into temporal windows |
+| `nff.normalize(data, method=...)` | Generic z-score, min-max, or robust scaling |
+| `nff.compare_signatures(a, b, metric=...)` | Generic cosine / Euclidean / Manhattan comparison |
+| `nff.load_csv(path, column=0)` | Load a numeric CSV column |
+| `nff.load_numpy(path)` | Load a `.npy` array |
+| `nff.export_json(data, path)` | Export structured data to JSON |
+| `nff.export_csv(data, path)` | Export a numeric vector to CSV |
+| `nff.NFFEngine(...).analyze(flow)` | Reserved for the original NFF engine; pending integration |
+
+The generic normalization and comparison helpers are convenience utilities. They are not claims
+about the project's canonical NFF normalization or signature-comparison definitions.
+
+## CLI
+
+```bash
+nff --version
+nff info
+nff doctor
+```
+
+## Tests
+
+```bash
+python -m pytest
+```
+
+## Build distributions
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+twine check dist/*
+```
+
+Do not upload this scaffold to PyPI as a finished NFF release until the original algorithm is
+integrated, tests cover its documented outputs, and the license metadata has been verified.
+
+## PyPI publication
+
+1. Confirm that the distribution name `nff-normalized-factor-flow` is available on PyPI.
+2. Integrate the original engine and complete the tests (see `INTEGRATION.md`).
+3. Verify the real license and author metadata.
+4. Build and validate the distributions with the commands above.
+5. Test on TestPyPI, then publish with `twine upload dist/*` or configure PyPI Trusted Publishing.
+
+Project source and theory: <https://github.com/Elxrth/NFF-normalized-factor-flow>

nff_normalized_factor_flow-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+nff/__init__.py,sha256=MCoPvzgJhN0gNGyzjB3tkzRy7JLVXSP0mnIaNenVGsY,703
+nff/cli.py,sha256=oUjEfFzgpnBZgtZcHzzlHzJYI1S1arzcU3psvF9DNfE,1624
+nff/comparison.py,sha256=9bRAr1cuWdzowc_yZo0sg3Jag35HysmJnvv8mreqmw8,1412
+nff/containers.py,sha256=fa8-AAlilbcjpTm-TbN2xPaFwivDmv1vACxJifFag_4,1291
+nff/core.py,sha256=IQ6eZGvDHjTzAn2p242pzoMc8CAhGsimxKDJLDCoZI0,2950
+nff/data.py,sha256=3k18_HRUTqGPi1j01xB2beWgYl-3t5wgGZJ_5bQUups,1507
+nff/exporters.py,sha256=tlDGPzvYFV467oX2YSxb18gal-PPswbDHDajeX499xU,1665
+nff/normalization.py,sha256=fLniGr4mPI4xEOGAdCp6MxZElWhqKtGyGyXG7l8VbGc,1681
+nff/results.py,sha256=hqaME-WS1dGqbewVZYsmrrBgtps2EZ5paPrN0JV2XjE,686
+nff_normalized_factor_flow-0.1.0.dist-info/METADATA,sha256=ekOGRD_1l9fTjZKC2YeT6OWJXSWT-ixnMDsK-nLxaYk,5348
+nff_normalized_factor_flow-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+nff_normalized_factor_flow-0.1.0.dist-info/entry_points.txt,sha256=KcTJ9_Z6qqK-1OUdv7GJmkn8bPVkPWcjHe3Juq4COBE,37
+nff_normalized_factor_flow-0.1.0.dist-info/top_level.txt,sha256=K5kgEY0GFqztWlM65sgCppDsnNPsQFUkt0F7gRA56t0,4
+nff_normalized_factor_flow-0.1.0.dist-info/RECORD,,

nff_normalized_factor_flow-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nff_normalized_factor_flow-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nff = nff.cli:main

nff_normalized_factor_flow-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+nff