modusa 0.1.0__py3-none-any.whl → 0.2.1__py3-none-any.whl

modusa/signals/base.py

@@ -2,293 +2,33 @@
 
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type
+from modusa.signals.signal_ops import SignalOps
 from abc import ABC, abstractmethod
+from dataclasses import dataclass
 from typing import Self
 import numpy as np
 import matplotlib.pyplot as plt
 
 class ModusaSignal(ABC):
 	"""
-	Base class prototype for any signal.
+	Base class for any signal in the modusa framework.
 	
 	Note
 	----
-	- Serves as the foundation for all signal types in the Modusa framework
-	- Intended to be subclassed
-	- Subclass shoud implement a **read-only** `data` property (e.g., amplitude or spectral data) and a `plot()` method to visualize the signal
-
-	Warning
-	-------
-	- You cannot create a subclass without `data` and `plot()` implemented. It will throw an error on instantiating the subclass.
-	
-	Example
-	-------
-	.. code-block:: python
-			
-		from modusa.signals import ModusaSignal
-		from modusa.decorators import validate_args_type
-
-		class MySignal(ModusaSignal):
-			
-			@validate_args_type()
-			def __init__(self, y: nd.ndarray):
-				super().__init__() # Very important for proper initialisation
-				self._y = y
-	
-			@property
-			def data(self):
-				return self._y
-			
-			@validate_args_type()
-			def plot(self):
-				# Your plotting logic here
-				pass
+	- Intended to be subclassed.
 	"""
 	
 	#--------Meta Information----------
-	name = "Modusa Signal"
-	description = "Base class for any signal types in the Modusa framework."
-	author_name = "Ankit Anand"
-	author_email = "ankit0.anand0@gmail.com"
-	created_at = "2025-06-23"
+	_name = "Modusa Signal"
+	_description = "Base class for any signal types in the Modusa framework."
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-06-23"
 	#----------------------------------
 	
 	@validate_args_type()
-	def __init__(self, data: np.ndarray, data_idx: np.ndarray):
-		self._data = data
-		self._data_idx = data_idx
+	def __init__(self):
 		self._plugin_chain = []
-		
-	#----------------------------
-	# Setters
-	#----------------------------
-	@validate_args_type()
-	def set_name(self, name: str) -> Self:
-		self.name = name
-		
-		return name
-	
-	
-	#----------------------------
-	# Properties
-	#----------------------------
-	
-	@property
-	def data(self) -> np.ndarray:
-		"""
-		The core signal data as a NumPy array.
-		
-		Note
-		----
-		- Different signals might need to have different variable names to store data, e.g. y(t) -> y, M(x, y) -> M, x(t) -> x
-		- This `data` property must return the correct data for any given subclass (y for y(t), M for M(x, y)), see the example.
-		- Must return `np.ndarray`
-		"""
-		return self._data
-	
-	@immutable_property("Create a new object instead.")
-	def data_idx(self) -> np.ndarray:
-		"""
-		The coordinate values associated with each element of the signal `data`.
-	
-		Note
-		----
-		- This is often a 1D array of the same length as the first axis of `data`.
-		- For time-domain signals, this typically represents timestamps.
-		- For spectrograms or other 2D signals, you may use a dict mapping axes to coordinate arrays.
-		- This property is read-only; to modify it, create a new signal object.
-		
-		Returns
-		-------
-		np.ndarray
-			An array of coordinates or indices corresponding to the signal data.
-		"""
-		return self._data_idx
-	
-	@immutable_property("Read-only property.")
-	def shape(self) -> tuple[int]:
-		"""Shape of the signal."""
-		return self.data.shape
-	
-	
-	@immutable_property("plugin_chain is read-only. It is automatically updated.")
-	def plugin_chain(self) -> list[str]:
-		"""
-		List of plugin names applied to the signal.
-		
-		Note
-		----
-		- Reflects the signal’s processing history
-		- Ordered by application sequence
-		- Managed automatically (read-only)
-		- Use `info` for a formatted summary
-		"""
-		return self._plugin_chain.copy()
-	
-	@immutable_property("Mutation not allowed, generated automatically.")
-	def info(self) -> None:
-		"""
-		Prints a quick summary of the signal.
-		
-		Note
-		----
-		- Output is printed to the console.
-		- Returns nothing.
-
-		"""
-		
-		print("\n".join([
-			f"{self.__class__.__name__}(",
-			f"  Signal Name: '{self.name}',",
-			f"  Inheritance: {' → '.join(cls.__name__ for cls in self.__class__.mro()[:-1])}",
-			f"  Plugin Chain: {' → '.join(self._plugin_chain) or '(none)'}",
-			f")"
-		]))
-		
-	#-------------------------------
-	# Basic functionalities
-	#-------------------------------
-		
-	@abstractmethod
-	def plot(self) -> plt.Figure:
-		"""
-		Plot a visual representation of the signal.
-		
-		Note
-		----
-		- For any signal, one must implement `plot` method with useful features to make users happy
-		- Try to return `matplotlib.figure.Figure` for customization/saving but other plotting libraries are also welcome
-		"""
-		pass
-	
-	@abstractmethod
-	def _with_data(self, new_data: np.ndarray, new_data_idx: np.ndarray) -> Self:
-		"""Subclasses must override this to return a copy with new data."""
-		pass
-		
-	
-	def trim(self, start: float | None = None, stop: float | None = None):
-		"""
-		Returns a new signal trimmed between two data_idx values.
-	
-		Parameters
-		----------
-		start : float or None
-			The starting data_idx value (inclusive). If None, starts from the beginning.
-		stop : float or None
-			The stopping data_idx value (exclusive). If None, goes till the end.
-	
-		Returns
-		-------
-		ModusaSignal
-			A new signal with trimmed data and data_idx.
-		"""
-		# Define bounds
-		start_v = -np.inf if start is None else start
-		stop_v = np.inf if stop is None else stop
-	
-		# Build a mask over data_idx values
-		mask = (self.data_idx >= start_v) & (self.data_idx < stop_v)
-		idx = np.where(mask)[0]
-	
-		return self._with_data(new_data=self.data[idx], new_data_idx=self.data_idx[idx])
-	
-	#----------------------------
-	# Dunder method
-	#----------------------------
-	
-	
-	#----------------------------
-	# Slicing
-	#----------------------------
-	
-	def __getitem__(self, key):
-		if isinstance(key, (int, slice)):
-			# Normal Python-style slicing by index
-			sliced_data = self.data[key]
-			sliced_idx = self.data_idx[key]
-			return self._with_data(new_data=sliced_data, new_data_idx=sliced_idx)
-		
-		else:
-			raise TypeError(f"Indexing with type {type(key)} is not supported. Use int or slice.")
-			
 	
 
-	def __str__(self):
-		cls = self.__class__.__name__
-		data = self.data
-		
-		arr_str = np.array2string(
-			data,
-			separator=", ",
-			threshold=50,       # limit number of elements shown
-			edgeitems=3,          # show first/last 3 rows and columns
-			max_line_width=120,   # avoid wrapping
-			formatter={'float_kind': lambda x: f"{x:.4g}"}
-		)
-		
-		return f"{cls}({arr_str}, shape={data.shape})"
-	
-	def __repr__(self):
-		cls = self.__class__.__name__
-		data = self.data
-		
-		arr_str = np.array2string(
-			data,
-			separator=", ",
-			threshold=50,       # limit number of elements shown
-			edgeitems=3,          # show first/last 3 rows and columns
-			max_line_width=120,   # avoid wrapping
-			formatter={'float_kind': lambda x: f"{x:.4g}"}
-		)
-		
-		return f"{cls}({arr_str}, shape={data.shape})"
-	
-	
-	#----------------------------
-	# Math ops
-	#----------------------------
-	
-	def __array__(self, dtype=None):
-		return self.data if dtype is None else self.data.astype(dtype)
-	
-	def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
-		if method != '__call__':
-			return NotImplemented
-		
-		# Replace ModusaSignal instances with their data
-		new_inputs = [i.data if isinstance(i, ModusaSignal) else i for i in inputs]
-		
-		try:
-			result = ufunc(*new_inputs, **kwargs)
-		except Exception as e:
-			raise TypeError(f"Ufunc {ufunc.__name__} failed: {e}")
-			
-		return self._with_data(result)
-	
-	def _apply_op(self, other, op, label):
-		if isinstance(other, ModusaSignal):
-			other = other.data  # extract data
-			
-		try:
-			result = op(self.data, other)
-		except Exception as e:
-			raise TypeError(f"Operation {label} failed: {e}")
-			
-		return self._with_data(result)
-	
-	def __add__(self, other): return self._apply_op(other, np.add, "+")
-	def __sub__(self, other): return self._apply_op(other, np.subtract, "-")
-	def __mul__(self, other): return self._apply_op(other, np.multiply, "*")
-	def __truediv__(self, other): return self._apply_op(other, np.divide, "/")
-	def __pow__(self, other): return self._apply_op(other, np.power, "**")
-		
-	def __radd__(self, other): return self.__add__(other)
-	def __rsub__(self, other): return self._apply_op(other, lambda a, b: b - a, "r-")
-	def __rmul__(self, other): return self.__mul__(other)
-	def __rtruediv__(self, other): return self._apply_op(other, lambda a, b: b / a, "r/")
-	def __rpow__(self, other): return self._apply_op(other, lambda a, b: b ** a, "r**")
-		
-	def __neg__(self): return self._with_data(-self.data)
-	def __abs__(self): return self._with_data(np.abs(self.data))
-		
+	

modusa/signals/frequency_domain_signal.py

@@ -0,0 +1,329 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import immutable_property, validate_args_type
+from modusa.signals.base import ModusaSignal
+from typing import Self, Any
+import numpy as np
+import matplotlib.pyplot as plt
+
+class FrequencyDomainSignal(ModusaSignal):
+	"""
+	Represents a 1D signal in the frequency domain.
+	
+	Note
+	----
+	- The class is not intended to be instantiated directly 
+	This class stores the Complex spectrum of a signal
+	along with its corresponding frequency axis. It optionally tracks the time
+	origin (`t0`) of the spectral slice, which is useful when working with
+	time-localized spectral data (e.g., from a spectrogram or short-time Fourier transform).
+
+	Parameters
+	----------
+	spectrum : np.ndarray
+		The frequency-domain representation of the signal (real or complex-valued).
+	f : np.ndarray
+		The frequency axis corresponding to the spectrum values. Must match the shape of `spectrum`.
+	t0 : float, optional
+		The time (in seconds) corresponding to the origin of this spectral slice. Defaults to 0.0.
+	title : str, optional
+		An optional title for display or plotting purposes.
+	"""
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-09"
+	#----------------------------------
+	
+	@validate_args_type()
+	def __init__(self, spectrum: np.ndarray, f: np.ndarray, t0: float | int = 0.0, title: str | None = None):
+		super().__init__() # Instantiating `ModusaSignal` class
+		
+		if spectrum.shape != f.shape:
+			raise excp.InputValueError(f"`spectrum` and `f` shape must match, got {spectrum.shape} and {f.shape}")
+		
+		
+		self._spectrum = spectrum
+		self._f = f
+		self._t0 = float(t0)
+	
+		self.title = title or self._name # This title will be used as plot title by default
+		
+	
+	#----------------------
+	# Properties
+	#----------------------
+	
+	@immutable_property("Create a new object instead.")
+	def spectrum(self) -> np.ndarray:
+		"""Complex valued spectrum data."""
+		return self._spectrum
+	
+	@immutable_property("Create a new object instead.")
+	def f(self) -> np.ndarray:
+		"""frequency array of the spectrum."""
+		return self._f
+	
+	@immutable_property("Create a new object instead.")
+	def t0(self) -> np.ndarray:
+		"""Time origin (in seconds) of this spectral slice, e.g., from a spectrogram frame."""
+		return self._t0
+	
+	def __len__(self):
+		return len(self._y)
+	
+	
+	#----------------------
+	# Tools
+	#----------------------
+	
+	def __getitem__(self, key: slice) -> Self:
+		sliced_spectrum = self._spectrum[key]
+		sliced_f = self._f[key]
+		return self.__class__(spectrum=sliced_spectrum, f=sliced_f, t0=self.t0, title=self.title)
+	
+	@validate_args_type()
+	def plot(
+		self,
+		scale_y: tuple[float, float] | None = None,
+		ax: plt.Axes | None = None,
+		color: str = "b",
+		marker: str | None = None,
+		linestyle: str | None = None,
+		stem: bool | None = False,
+		legend_loc: str | None = None,
+		title: str | None = None,
+		ylabel: str | None = "Amplitude",
+		xlabel: str | None = "Freq (Hz)",
+		ylim: tuple[float, float] | None = None,
+		xlim: tuple[float, float] | None = None,
+		highlight: list[tuple[float, float]] | None = None,
+	) -> plt.Figure:
+		"""
+		Plot the frequency-domain signal as a line or stem plot.
+		
+		.. code-block:: python
+
+			spectrum.plot(stem=True, color="r", title="FFT Frame", xlim=(0, 5000))
+		
+		Parameters
+		----------
+		scale_y : tuple[float, float], optional
+			Range to scale the spectrum values before plotting (min, max).
+		ax : matplotlib.axes.Axes, optional
+			Axis to plot on. If None, a new figure and axis are created.
+		color : str, default="b"
+			Color of the line or stem.
+		marker : str, optional
+			Marker style for points (ignored if stem=True).
+		linestyle : str, optional
+			Line style for the plot (ignored if stem=True).
+		stem : bool, default=False
+			Whether to use a stem plot instead of a line plot.
+		legend_loc : str, optional
+			Legend location (e.g., 'upper right'). If None, no legend is shown.
+		title : str, optional
+			Title of the plot. Defaults to signal title.
+		ylabel : str, default="Amplitude"
+			Label for the y-axis.
+		xlabel : str, default="Freq (Hz)"
+			Label for the x-axis.
+		ylim : tuple[float, float], optional
+			Limits for the y-axis.
+		xlim : tuple[float, float], optional
+			Limits for the x-axis.
+		highlight : list[tuple[float, float]], optional
+			Regions to highlight on the frequency axis as shaded spans.
+		
+		Returns
+		-------
+		matplotlib.figure.Figure
+			The figure containing the plotted signal.
+		
+		Note
+		----
+		- If `ax` is provided, the plot is drawn on it; otherwise, a new figure is created.
+		- `highlight` can be used to emphasize frequency bands (e.g., formants, harmonics).
+		- Use `scale_y` to clip or normalize extreme values before plotting.
+		"""
+		
+		
+		from modusa.io import Plotter
+		
+		title = title or self.title
+		
+		fig: plt.Figure | None = Plotter.plot_signal(y=self.spectrum, x=self.f, scale_y=scale_y, ax=ax, color=color, marker=marker, linestyle=linestyle, stem=stem, legend_loc=legend_loc, title=title, ylabel=ylabel, xlabel=xlabel, ylim=ylim, xlim=xlim, highlight=highlight)
+		
+		return fig
+	
+	#----------------------------
+	# Math ops
+	#----------------------------
+	
+	def __array__(self, dtype=None):
+		return np.asarray(self.spectrum, dtype=dtype)
+	
+	def __add__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.add(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __radd__(self, other):
+		result = np.add(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __sub__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.subtract(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __rsub__(self, other):
+		result = np.subtract(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __mul__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.multiply(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __rmul__(self, other):
+		result = np.multiply(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __truediv__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.true_divide(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __rtruediv__(self, other):
+		result = np.true_divide(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __floordiv__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.floor_divide(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __rfloordiv__(self, other):
+		result = np.floor_divide(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __pow__(self, other):
+		other_data = other.spectrum if isinstance(other, self.__class__) else other
+		result = np.power(self.spectrum, other_data)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __rpow__(self, other):
+		result = np.power(other, self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def __abs__(self):
+		result = np.abs(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	
+	#--------------------------
+	# Other signal ops
+	#--------------------------
+	def sin(self) -> Self:
+		"""Compute the element-wise sine of the signal data."""
+		result = np.sin(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def cos(self) -> Self:
+		"""Compute the element-wise cosine of the signal data."""
+		result = np.cos(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def exp(self) -> Self:
+		"""Compute the element-wise exponential of the signal data."""
+		result = np.exp(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def tanh(self) -> Self:
+		"""Compute the element-wise hyperbolic tangent of the signal data."""
+		result = np.tanh(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def log(self) -> Self:
+		"""Compute the element-wise natural logarithm of the signal data."""
+		result = np.log(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def log1p(self) -> Self:
+		"""Compute the element-wise natural logarithm of (1 + signal data)."""
+		result = np.log1p(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def log10(self) -> Self:
+		"""Compute the element-wise base-10 logarithm of the signal data."""
+		result = np.log10(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	def log2(self) -> Self:
+		"""Compute the element-wise base-2 logarithm of the signal data."""
+		result = np.log2(self.spectrum)
+		return self.__class__(spectrum=result, f=self.f, t0=self.t0, title=self.title)
+	
+	
+	#--------------------------
+	# Aggregation signal ops
+	#--------------------------
+	def mean(self) -> float:
+		"""Compute the mean of the signal data."""
+		return float(np.mean(self.spectrum))
+	
+	def std(self) -> float:
+		"""Compute the standard deviation of the signal data."""
+		return float(np.std(self.spectrum))
+	
+	def min(self) -> float:
+		"""Compute the minimum value in the signal data."""
+		return float(np.min(self.spectrum))
+	
+	def max(self) -> float:
+		"""Compute the maximum value in the signal data."""
+		return float(np.max(self.spectrum))
+	
+	def sum(self) -> float:
+		"""Compute the sum of the signal data."""
+		return float(np.sum(self.spectrum))
+	
+	#-----------------------------------
+	# Repr
+	#-----------------------------------
+	
+	def __str__(self):
+		cls = self.__class__.__name__
+		data = self.spectrum
+		
+		arr_str = np.array2string(
+			data,
+			separator=", ",
+			threshold=50,       # limit number of elements shown
+			edgeitems=3,          # show first/last 3 rows and columns
+			max_line_width=120,   # avoid wrapping
+			formatter={'float_kind': lambda x: f"{x:.4g}"}
+		)
+		
+		return f"Signal({arr_str}, shape={data.shape}, kind={cls})"
+	
+	def __repr__(self):
+		cls = self.__class__.__name__
+		data = self.spectrum
+		
+		arr_str = np.array2string(
+			data,
+			separator=", ",
+			threshold=50,       # limit number of elements shown
+			edgeitems=3,          # show first/last 3 rows and columns
+			max_line_width=120,   # avoid wrapping
+			formatter={'float_kind': lambda x: f"{x:.4g}"}
+		)
+		
+		return f"Signal({arr_str}, shape={data.shape}, kind={cls})"
+