piel.analysis.signals.frequency
===============================

.. py:module:: piel.analysis.signals.frequency


Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/piel/analysis/signals/frequency/core/index


Functions
---------

.. autoapisummary::

   piel.analysis.signals.frequency.extract_phasor_to_dataframe
   piel.analysis.signals.frequency.extract_phasor_type_to_dataframe
   piel.analysis.signals.frequency.convert_complex_array_to_phasor_dataframe
   piel.analysis.signals.frequency.extract_two_port_network_transmission_to_dataframe
   piel.analysis.signals.frequency.max_power_s21_frequency_metric_from_dataframe


Package Contents
----------------

.. py:function:: extract_phasor_to_dataframe(phasor: piel.types.Phasor) -> pandas.DataFrame

   Converts a Phasor instance into a pandas DataFrame with equivalent lengths for magnitude, phase, and frequency.

   Parameters:
   - input (Phasor): The Phasor instance to convert.

   Returns:
   - pd.DataFrame: A DataFrame containing magnitude, phase, and frequency columns with appropriate units.

   Raises:
   - TypeError: If the fields are of unsupported types.
   - ValueError: If the lengths of the fields do not match.


.. py:function:: extract_phasor_type_to_dataframe(phasor_type: piel.types.PhasorTypes) -> pandas.DataFrame

   Converts any PhasorTypes instance into a pandas DataFrame.
   - If phasor_type is a Phasor instance, uses extract_phasor_to_dataframe.
   - If phasor_type is an array of complex numbers, converts to magnitude, phase, frequency=1.
   - If phasor_type is numerical (int or float), treats as scalar input with magnitude=phasor_type,
     phase=0, frequency=1.
   - If phasor_type is a list or numpy array of numerical types, treats as magnitude with phase=0 and frequency=1.

   Parameters:
   - phasor_type (PhasorTypes): The input type to convert.

   Returns:
   - pd.DataFrame: A DataFrame containing magnitude, phase, and frequency columns.

   Raises:
   - TypeError: If the phasor_type is of unsupported type.
   - ValueError: If input data is invalid.


.. py:function:: convert_complex_array_to_phasor_dataframe(complex_array: Union[List[complex], numpy.ndarray]) -> pandas.DataFrame

   Converts an array of complex numbers into a pandas DataFrame with magnitude, phase, and frequency.
   Sets frequency to 1 Hz for all entries.

   Parameters:
   - complex_array (List[complex] | np.ndarray): The array of complex numbers to convert.

   Returns:
   - pd.DataFrame: A DataFrame containing magnitude, phase, and frequency columns.

   Raises:
   - TypeError: If the input is not a list or numpy array of complex numbers.
   - ValueError: If the complex array is empty.


.. py:function:: extract_two_port_network_transmission_to_dataframe(network_transmission: piel.types.NetworkTransmission) -> pandas.DataFrame

   Converts a NetworkTransmission instance into a single pandas DataFrame that includes:
   - The main input data from NetworkTransmission.input.
   - The transmission input data from each PathTransmission in NetworkTransmission.network,
     with columns prefixed by the corresponding S-parameter name (e.g., s_11, s_21).

   This function is generalized to handle both integer-based port tuples (e.g., (0, 0))
   and string-based port tuples (e.g., ("in0", "out0")).

   Parameters:
   - network_transmission (NetworkTransmission): The NetworkTransmission instance to convert.

   Returns:
   - pd.DataFrame: A combined DataFrame containing the main input and all path transmission phasors.

   Raises:
   - TypeError: If any transmission input is of unsupported type.
   - ValueError: If any input data is invalid or if DataFrames have mismatched lengths.


.. py:function:: max_power_s21_frequency_metric_from_dataframe(dataframe: pandas.DataFrame) -> piel.types.FrequencyMetric

   Extracts the maximum s_21_magnitude_dBm from the DataFrame, composes the corresponding input input,
   and returns both as a Phasor and ScalarMetric.

   :param dataframe: DataFrame containing the required columns.
   :type dataframe: pd.DataFrame

   :returns: A tuple containing the input Phasor and the output ScalarMetric.
   :rtype: Tuple[Phasor, ScalarMetric]