modusa 0.1.0__py3-none-any.whl

modusa/plugins/plot_time_domain_signal.py

@@ -0,0 +1,59 @@
+#!/usr/bin/env python3
+
+
+from modusa.plugins.base import ModusaPlugin
+from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
+import matplotlib.pyplot as plt
+
+class PlotTimeDomainSignalPlugin(ModusaPlugin):
+	"""
+
+	"""
+	
+	#--------Meta Information----------
+	name = ""
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-03"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+		
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_input_signal_types(self) -> tuple[type, ...]:
+		from modusa.signals import UniformTimeDomainSignal, AudioSignal
+		return (UniformTimeDomainSignal, AudioSignal, )
+	
+	
+	@immutable_property(error_msg="Mutation not allowed.")
+	def allowed_output_signal_types(self) -> tuple[type, ...]:
+		return (plt.Figure, type(None))
+	
+	
+	@plugin_safety_check()
+	@validate_args_type()
+	def apply(
+		self,
+		signal: "UniformTimeDomainSignal",
+		scale_y: tuple[float, float] | None = None,
+		scale_t: tuple[float, float] | None = None,
+		ax: plt.Axes | None = None,
+		color: str | None = "b",
+		marker: str | None = None,
+		linestyle: str | None = None,
+		stem: bool = False,
+		labels: tuple[str, str, str] | None = None,
+		legend_loc: str | None = None,
+		zoom: tuple[float, float] | None = None,
+		highlight: list[tuple[float, float], ...] | None = None,
+		show_grid: bool | None = False,
+	) -> plt.Figure:
+		
+		# Run the engine here
+		from modusa.engines import Plot1DSignalEngine
+		
+		fig: plt.Figure | None = Plot1DSignalEngine().run(y=signal.data, x=signal.t, scale_y=scale_y, scale_x=scale_t, ax=ax, color=color, marker=marker, linestyle=linestyle, stem=stem, labels=labels, legend_loc=legend_loc, zoom=zoom, highlight=highlight) 
+		
+		return fig

modusa/signals/__init__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+
+from .base import ModusaSignal
+
+from .signal1d import Signal1D
+from .signal2d import Signal2D
+from .uniform_time_domain_signal import UniformTimeDomainSignal
+
+from .audio_signal import AudioSignal

modusa/signals/audio_signal.py

@@ -0,0 +1,230 @@
+#!/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
+from pathlib import Path
+
+class AudioSignal(ModusaSignal):
+	"""
+
+	"""
+
+	#--------Meta Information----------
+	name = "Audio Signal"
+	description = ""
+	author_name = "Ankit Anand"
+	author_email = "ankit0.anand0@gmail.com"
+	created_at = "2025-07-04"
+	#----------------------------------
+	
+	@validate_args_type()
+	def __init__(self, y: np.ndarray, t: np.ndarray | None = None):
+		
+		if y.ndim != 1: # Mono
+			raise excp.InputValueError(f"`y` must have 1 dimension not {y.ndim}.")
+		if t.ndim != 1:
+			raise excp.InputValueError(f"`t` must have 1 dimension not {t.ndim}.")
+		
+		if t is None:
+			t = np.arange(y.shape[0])
+		else:
+			if t.shape[0] != y.shape[0]:
+				raise excp.InputValueError(f"`y` and `t` must have same shape.")
+			dts = np.diff(t)
+			if not np.allclose(dts, dts[0]):
+				raise excp.InputValueError("`t` must be equally spaced")
+		
+		super().__init__(data=y, data_idx=t) # Instantiating `ModusaSignal` class
+		
+		self._y_unit = ""
+		self._t_unit = "sec"
+		
+		self._title = "Audio Signal"
+		self._y_label = "Amplitude"
+		self._t_label = "Time"
+	
+	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."""
+		new_signal = self.__class__(y=new_data, t=new_data_idx)
+		new_signal.set_units(y_unit=self.y_unit, t_unit=self.t_unit)
+		new_signal.set_plot_labels(title=self.title, y_label=self.y_label, t_label=self.t_label)
+		
+		return new_signal
+	
+	#----------------------
+	# From methods
+	#----------------------
+	@classmethod
+	def from_array(cls, y: np.ndarray, t: np.ndarray | None = None) -> Self:
+		
+		signal = cls(y=y, t=t)
+		
+		return signal
+	
+	@classmethod
+	def from_array_with_sr(cls, y: np.ndarray, sr: int) -> Self:
+		t = np.arange(y.shape[0]) * (1.0 / sr)
+		
+		signal = cls(y=y, t=t)
+		
+		return signal
+	
+	@classmethod
+	def from_list(cls, y: list, t: list) -> Self:
+		
+		y = np.array(y)
+		t = np.array(t)
+		signal = cls(y=y, t=t)
+		
+		return signal
+	
+	@classmethod
+	def from_file(cls, fp: str | Path, sr: int | None = None) -> Self:
+		
+		import librosa
+		
+		fp = Path(fp)
+		y, sr = librosa.load(fp, sr=sr)
+		t = np.arange(y.shape[0]) * (1.0 / sr)
+		
+		signal = cls(y=y, t=t)
+		signal.set_plot_labels(title=fp.stem)
+		
+		return signal
+		
+	#----------------------
+	# Setters
+	#----------------------
+	
+	@validate_args_type()
+	def set_units(self, y_unit: str | None = None, t_unit: str | None = None) -> Self:
+		
+		if y_unit is not None:
+			self._y_unit = y_unit
+		if t_unit is not None:
+			self._t_unit = t_unit
+		
+		return self
+	
+	@validate_args_type()
+	def set_plot_labels(self, title: str | None = None, y_label: str | None = None, t_label: str | None = None) -> Self:
+		
+		if title is not None:
+			self._title = title
+		if y_label is not None:
+			self._y_label = y_label
+		if t_label is not None:
+			self._t_label = t_label
+		
+		return self
+	
+	
+	#----------------------
+	# Properties
+	#----------------------
+	
+	@immutable_property("Create a new object instead.")
+	def y(self) -> np.ndarray:
+		""""""
+		return self.data
+	
+	@immutable_property("Create a new object instead.")
+	def t(self) -> np.ndarray:
+		""""""
+		return self.data_idx
+	
+	@immutable_property("Create a new object instead.")
+	def sr(self) -> np.ndarray:
+		""""""
+		return 1.0 / self.t[1] - self.t[0]
+	
+	@immutable_property("Use `.set_units` instead.")
+	def y_unit(self) -> str:
+		""""""
+		return self._y_unit
+	
+	@immutable_property("Use `set_units` instead.")
+	def t_unit(self) -> str:
+		""""""
+		return self._t_unit
+	
+	@immutable_property("Use `.set_plot_labels` instead.")
+	def title(self) -> str:
+		""""""
+		return self._title
+	
+	@immutable_property("Use `.set_plot_labels` instead.")
+	def y_label(self) -> str:
+		""""""
+		return self._y_label
+	
+	@immutable_property("Use `.set_plot_labels` instead.")
+	def t_label(self) -> str:
+		""""""
+		return self._t_label
+	
+	@immutable_property("Mutation not allowed.")
+	def Ts(self) -> int:
+		""""""
+		return self.t[1] - self.t[0]
+	
+	@immutable_property("Mutation not allowed.")
+	def duration(self) -> int:
+		""""""
+		return self.t[-1]
+	
+	@immutable_property("Use `.set_labels` instead.")
+	def labels(self) -> tuple[str, str, str]:
+		"""Labels in a tuple format appropriate for the plots."""
+		return (self.title, f"{self.y_label} ({self.y_unit})", f"{self.t_label} ({self.t_unit})")
+	
+	
+	#----------------------
+	# Plugins Access
+	#----------------------
+	@validate_args_type()
+	def plot(
+		self,
+		scale_y: tuple[float, float] | None = None,
+		scale_t: tuple[float, float] | None = None,
+		ax: plt.Axes | None = None,
+		color: str = "b",
+		marker: str | None = None,
+		linestyle: str | None = None,
+		stem: bool | None = None,
+		labels: tuple[str, str, str] | None = None,
+		legend_loc: str | None = None,
+		zoom: tuple[float, float] | None = None,
+		highlight: list[tuple[float, float]] | None = None,
+	) -> plt.Figure:
+		"""
+		Applies `modusa.plugins.PlotTimeDomainSignal` Plugin.
+		"""
+		
+		from modusa.plugins import PlotTimeDomainSignalPlugin
+		
+		labels = labels or self.labels
+		stem = stem or False
+		
+		fig: plt.Figure | None = PlotTimeDomainSignalPlugin().apply(
+			signal=self,
+			scale_y=scale_y,
+			scale_t=scale_t,
+			ax=ax,
+			color=color,
+			marker=marker,
+			linestyle=linestyle,
+			stem=stem,
+			labels=labels,
+			legend_loc=legend_loc,
+			zoom=zoom,
+			highlight=highlight
+		)
+		
+		return fig
+	

modusa/signals/base.py

@@ -0,0 +1,294 @@
+#!/usr/bin/env python3
+
+from modusa import excp
+from modusa.decorators import immutable_property, validate_args_type
+from abc import ABC, abstractmethod
+from typing import Self
+import numpy as np
+import matplotlib.pyplot as plt
+
+class ModusaSignal(ABC):
+	"""
+	Base class prototype for any signal.
+	
+	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
+	"""
+	
+	#--------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"
+	#----------------------------------
+	
+	@validate_args_type()
+	def __init__(self, data: np.ndarray, data_idx: np.ndarray):
+		self._data = data
+		self._data_idx = data_idx
+		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))
+