Metadata-Version: 2.4
Name: diamondback
Version: 6.0.0
Summary: Diamondback DSP
Author-email: Larry Turner <larry.turner@se.com>
License-Expression: BSD-3-Clause
Project-URL: homepage, https://github.com/larryturner/diamondback
Keywords: DSP,FFT,FIR,GMM,IIR,PSD
Classifier: Development Status :: 5 - Production/Stable
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: <3.15,>=3.11
Description-Content-Type: text/x-rst
Requires-Dist: loguru<1.0.0,>=0.7.1
Requires-Dist: numpy<3.0.0,>=1.25.0
Requires-Dist: pandas<4.0.0,>=2.1.0
Requires-Dist: requests<3.0.0,>=2.31.0
Requires-Dist: scikit-learn<2.0.0,>=1.3.0
Requires-Dist: scipy<2.0.0,>=1.11.1
Provides-Extra: build
Requires-Dist: build<2.0.0,>=1.2.2; extra == "build"
Requires-Dist: virtualenv<21.0.0,>=20.29.3; extra == "build"
Provides-Extra: dependencies
Requires-Dist: pydeps<4.0.0,>=3.0.1; extra == "dependencies"
Provides-Extra: docs
Requires-Dist: sphinx<9.0.0,>=8.2.3; extra == "docs"
Requires-Dist: sphinx-rtd-theme<4.0.0,>=3.0.2; extra == "docs"
Provides-Extra: format
Requires-Dist: ruff<1.0.0,>=0.11.3; extra == "format"
Provides-Extra: lint
Requires-Dist: ruff<1.0.0,>=0.11.3; extra == "lint"
Provides-Extra: notebook
Requires-Dist: ipython<9.0.0,>=8.31.0; extra == "notebook"
Requires-Dist: ipywidgets<9.0.0,>=8.1.5; extra == "notebook"
Requires-Dist: jupyter<2.0.0,>=1.1.1; extra == "notebook"
Requires-Dist: matplotlib<4.0.0,>=3.10.1; extra == "notebook"
Requires-Dist: pillow<12.0.0,>=11.1.0; extra == "notebook"
Provides-Extra: tests
Requires-Dist: pytest<9.0.0,>=8.3.5; extra == "tests"
Provides-Extra: typing
Requires-Dist: mypy<2.0.0,>=1.15.0; extra == "typing"
Requires-Dist: types-python-dateutil<3.0.0,>=2.9.0; extra == "typing"
Requires-Dist: types-requests<3.0.0,>=2.31.0; extra == "typing"

diamondback
===========

.. image:: https://img.shields.io/pypi/pyversions/diamondback.svg?color=steelblue
    :target: https://www.python.org/
.. image:: https://img.shields.io/pypi/v/diamondback.svg?label=pypi&color=midnightblue
    :target: https://pypi.org/project/diamondback
.. image:: https://img.shields.io/badge/admin-nox-orangered
    :target: https://pypi.org/project/nox/
.. image:: https://img.shields.io/badge/doc-sphinx-royalblue
    :target: https://pypi.org/project/sphinx/
.. image:: https://img.shields.io/badge/format-ruff-black
    :target: https://pypi.org/project/ruff/
.. image:: https://img.shields.io/badge/lint-ruff-firebrick
    :target: https://pypi.org/project/ruff/
.. image:: https://img.shields.io/badge/test-pytest-forestgreen
    :target: https://pypi.org/project/pytest/
.. image:: https://img.shields.io/badge/type-mypy-royalblue
    :target: http://pypi.org/project/mypy/
.. image:: https://img.shields.io/github/license/larryturner/diamondback?color=darkslategray
    :target: https://github.com/larryturner/diamondback/blob/master/LICENSE

Description
~~~~~~~~~~~

*diamondback* Digital Signal Processing (DSP).

*diamondback* complements Artificial Intelligence (AI) frameworks, by defining
components which filter, model, and transform data into forms which are
useful in feature extraction and pattern recognition.

*diamondback* supports applications including cancellation, identification,
optimization, probabilistic modeling, rate adaptation, and serialization.

Installation
~~~~~~~~~~~~

*diamondback* is a public repository hosted at `PyPI <https://pypi.org/project/diamondback>`_ and `GitHub <https://github.com/larryturner/diamondback>`_.

.. code-block:: bash

    pip install diamondback

.. code-block:: bash

    pip install git+https://github.com/larryturner/diamondback.git

.. code-block:: bash

    git clone https://github.com/larryturner/diamondback.git
    cd diamondback
    pip install .

Details
~~~~~~~

Data collections are consistently expressed in native types, including tuples, sets,
lists, and dictionaries, with vector and matrix types expressed in numpy arrays.
Complex or real types are supported as appropriate.

*diamondback* is defined in subpackages *commons*, *filters*, *models*, and
*transforms*.

`commons <https://larryturner.github.io/diamondback/diamondback.commons>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-   `Log <https://larryturner.github.io/diamondback/diamondback.commons#diamondback-commons-log-module>`_
    formats and writes log entries with a specified level and stream using
    loguru. Log entries contain an ISO 8601 datetime and level.  Log uses
    lazy initialization to coexist with loguru.  Dynamic stream redirection and
    level specification are supported.  Singleton.

-   `RestClient <https://larryturner.github.io/diamondback/diamondback.commons#diamondback-commons-rest-client-module>`_
    defines a client for simple REST service requests using requests.  An API
    and an elective dictionary of parameter strings are encoded to build
    a URL, elective binary or JSON data are defined in the body of a request,
    and a requests response containing JSON, text, or binary data is returned.
    Proxy, timeout, and URL definition are supported.

-   `Serial <https://larryturner.github.io/diamondback/diamondback.commons#diamondback-commons-serial-module>`_
    encodes and decodes an instance to a Base-85 encoded serialized string with
    elective gzip compression, and generates SHA3-256 hash codes.  Singleton.


`filters <https://larryturner.github.io/diamondback/diamondback.filters>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-   `ComplexBandpassFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-complex-bandpass-filter-module>`_
    adaptively extracts or rejects signals at a normalized frequency of
    interest, and may be employed to dynamically track magnitude and phase
    or demodulate signals.

-   `ComplexExponentialFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-complex-exponential-filter-module>`_
    synthesizes a complex exponential signal at a normalized frequency
    of interest with contiguous phase.

-   `ComplexFrequencyFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-complex-frequency-filter-module>`_
    adaptively discriminates and estimates a normalized frequency of
    a signal.

-   `DerivativeFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-derivative-filter-module>`_
    estimates discrete derivative approximations at several filter
    orders.

-   `FirFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-fir-filter-module>`_
    realizes discrete difference equations of Finite Impulse
    Response (FIR) form. Instances are defined based on style,
    normalized frequency, order, cascade count, and complement, or
    forward coefficients. Root extraction, group delay, and frequency
    response evaluation are defined.

-   `GoertzelFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-goertzel-filter-module>`_
    efficiently evaluates a Discrete Fourier Transform (DFT)
    at a normalized frequency, based on a window filter and normalized
    frequency.

-   `IirFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-iir-filter-module>`_
    realizes discrete difference equations of Infinite Impulse
    Response (IIR) form. Instances are defined based on style,
    normalized frequency, order, cascade count, and complement, or recursive
    and forward coefficients. Root extraction, group delay, and frequency
    response evaluation are defined.

-   `IntegralFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-integral-filter-module>`_
    estimates discrete integral approximations at several filter
    orders.

-   `PidFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-pid-filter-module>`_
    realizes discrete difference equations of Proportional
    Integral Derivative (PID) form.

-   `PolynomialRateFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-polynomial-rate-filter-module>`_
    approximates a signal evaluated at an effective frequency
    equal to the product of the normalized frequency and a rate greater
    than zero, supporting decimation and interpolation through localized
    polynomial approximation with no group delay.

-   `PolyphaseRateFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-polyphase-rate-filter-module>`_
    approximates a signal evaluated at an effective frequency
    equal to the product of the normalized frequency and a rate greater
    than zero, supporting decimation and interpolation through
    definition and application of a polyphase filter bank, a sequence
    of low pass filters with a common frequency response and a fractional
    sample difference in group delay. An appropriate stride is determined
    to realize the specified effective frequency without bias and with
    group delay based on order.

-   `RankFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-rank-filter-module>`_
    defines nonlinear morphological operators, which define
    behavior based on rank and order, including dilation, median,
    and erosion, and may be combined in sequences to support close and
    open.

-   `WindowFilter <https://larryturner.github.io/diamondback/diamondback.filters#diamondback-filters-window-filter-module>`_
    realizes discrete window functions useful in Fourier
    analysis, based on style, order, and normalization.

`models <https://larryturner.github.io/diamondback/diamondback.models>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-   `DiversityModel <https://larryturner.github.io/diamondback/diamondback.models#diamondback-models-diversity-model-module>`_
    selects and retains a state extracted to maximize the minimum
    distance between state members based on style and order. An
    opportunistic unsupervised learning model typically improves condition
    and numerical accuracy and reduces storage relative to alternative
    approaches including generalized linear inverse.

-   `GaussianModel <https://larryturner.github.io/diamondback/diamondback.models#diamondback-models-gaussian-model-module>`_
    is a supervised learning probabilistic model which uses maximum
    likelihood estimation and regularization to maximize posterior
    probability and classify an incident signal.  Learns one distribution
    instance per class.

-   `GaussianMixtureModel <https://larryturner.github.io/diamondback/diamondback.models#diamondback-models-gaussian-mixture-model-module>`_
    is a semi-supervised learning probabilistic model which uses maximum
    likelihood estimation, regularization, and expectation maximization
    to maximize posterior probability and classify an incident signal.
    Learns distribution of a specified order per class, where intra-class
    models capture mixture distributions.

`transforms <https://larryturner.github.io/diamondback/diamondback.transforms>`_
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

-   `ComplexTransform <https://larryturner.github.io/diamondback/diamondback.transforms#diamondback-transforms-complex-transform-module>`_
    converts a three-phase real signal to a complex signal, or a complex
    signal to a three-phase real signal, in equivalent and reversible
    representations, based on a neutral condition.  Singleton.

-   `FourierTransform <https://larryturner.github.io/diamondback/diamondback.transforms#diamondback-transforms-fourier-transform-module>`_
    converts a real or complex discrete-time signal to a complex
    discrete-frequency signal, or a complex discrete-frequency signal
    to a real or complex discrete-time signal, in equivalent and
    reversible representations, based on a window filter and inverse.
    Singleton.

-   `PsdTransform <https://larryturner.github.io/diamondback/diamondback.transforms#diamondback-transforms-psd-transform-module>`_
    realizes a Power Spectral Density (PSD) which converts a real or
    complex discrete-time signal to a real discrete-frequency signal
    which estimates an aggregate power spectrum of the signal, based
    on a window filter, index, and spectrogram.  A spectrogram
    constructs a time frequency representation of the power spectrum.
    Singleton.

-   `WaveletTransform <https://larryturner.github.io/diamondback/diamondback.transforms#diamondback-transforms-wavelet-transform-module>`_
    realizes a temporal spatial frequency transformation through
    defninition and application of analysis and synthesis filters with
    complementary frequency responses, combined with downsampling and
    upsampling operations, in equivalent and reversible representations.
    Instances are defined based on style and order.

-   `ZTransform <https://larryturner.github.io/diamondback/diamondback.transforms#diamondback-transforms-z-transform-module>`_
    converts continuous s-domain to discrete z-domain difference
    equations, based on a normalized frequency and application of
    bilinear or impulse invariant methods.  Singleton.

Dependencies
~~~~~~~~~~~~

*diamondback* depends upon external packages.

-   `loguru <https://pypi.org/project/loguru/>`_
-   `numpy <https://pypi.org/project/numpy/>`_
-   `requests <https://pypi.org/project/requests/>`_
-   `scikit-learn <https://pypi.org/project/scikit-learn/>`_
-   `scipy <https://pypi.org/project/scipy/>`_

*diamondback* elective build, dependencies, docs, format, lint, notebook,
tests, and typing behavior depends upon additional external packages.

-   `build <https://pypi.org/project/build/>`_
-   `ipython <https://pypi.org/project/ipython/>`_
-   `ipywidgets <https://pypi.org/project/ipywidgets/>`_
-   `jupyter <https://pypi.org/project/jupyter/>`_
-   `matplotlib <https://pypi.org/project/matplotlib/>`_
-   `mypy <https://pypi.org/project/mypy/>`_
-   `nox <https://pypi.org/project/nox/>`_
-   `pandas <https://pypi.org/project/pandas/>`_
-   `pillow <https://pypi.org/project/pillow/>`_
-   `pydeps <https://pypi.org/project/pydeps/>`_
-   `pytest <https://pypi.org/project/pytest/>`_
-   `ruff <https://pypi.org/project/ruff/>`_
-   `sphinx <https://pypi.org/project/sphinx/>`_
-   `sphinx-rtd-theme <https://pypi.org/project/sphinx-rtd-theme/>`_

*diamondback* dependency diagram.

.. image:: https://larryturner.github.io/diamondback/dependencies.svg
    :target: https://larryturner.github.io/diamondback/dependencies.svg

Documentation
~~~~~~~~~~~~~

*diamondback* documentation is available on `GitHub Pages <https://larryturner.github.io/diamondback/>`_.

Run a nox *docs* session to generate documentation.

.. code-block:: bash

    nox -s docs

Notebook
~~~~~~~~

A jupyter notebook defines cells to create and exercise *diamondback* components.
The notebook serves as a tool for visualization, validation, and demonstration
of *diamondback* capabilities.

Run a nox *notebook* session to exercise notebook.  Restart kernel and run all cells,
then exercise widgets.

.. code-block:: bash

    nox -s notebook

Tests
~~~~~

A test solution is provided to exercise and verify components, pytest is
used to execute unit and integration tests.

Run a nox *tests* session to exercise tests.

.. code-block:: bash

    nox -s tests

License
~~~~~~~

`BSD-3-Clause <https://github.com/larryturner/diamondback/blob/master/LICENSE>`_

Author
~~~~~~

`Larry Turner <https://github.com/larryturner>`_
