modusa 0.2.21__py3-none-any.whl → 0.2.23__py3-none-any.whl

modusa/signals/time_domain_signal.py

@@ -4,6 +4,7 @@
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type
 from modusa.signals.base import ModusaSignal
+from modusa.tools.math_ops import MathOps
 from typing import Self, Any
 import numpy as np
 import matplotlib.pyplot as plt
@@ -12,11 +13,12 @@ class TimeDomainSignal(ModusaSignal):
 	"""
 	Initialize a uniformly sampled 1D time-domain signal.
 	
-	This class is specifically designed to hold 1D signals that result
-	from slicing a 2D representation like a spectrogram. For example,
-	if you have a spectrogram `S` and you perform `S[10, :]`, the result
-	is a 1D signal over time, this class provides a clean and consistent
-	way to handle such slices.
+	- Not to be instantiated directly.
+	- This class is specifically designed to hold 1D signals that result
+	from slicing a 2D representation like a spectrogram.
+	- For example, if you have a spectrogram `S` and you perform `S[10, :]`,
+	the result is a 1D signal over time, this class provides a
+	clean and consistent way to handle such slices.
 	
 	Parameters
 	----------
@@ -66,17 +68,55 @@ class TimeDomainSignal(ModusaSignal):
 		""""""
 		return self._t0
 	
+	#----------------------
+	# Derived Properties
+	#----------------------
+	
 	@immutable_property("Create a new object instead.")
 	def t(self) -> np.ndarray:
-		return self.t0 + np.arange(len(self._y)) / self.sr
+		"""Timestamp array of the audio."""
+		return self.t0 + np.arange(len(self.y)) / self.sr 
+	
+	@immutable_property("Mutation not allowed.")
+	def Ts(self) -> float:
+		"""Sampling Period of the audio."""
+		return 1. / self.sr
+	
+	@immutable_property("Mutation not allowed.")
+	def duration(self) -> float:
+		"""Duration of the audio."""
+		return len(self.y) / self.sr
+	
+	@immutable_property("Mutation not allowed.")
+	def shape(self) -> tuple:
+		"""Shape of the audio signal."""
+		return self.y.shape
+	
+	@immutable_property("Mutation not allowed.")
+	def ndim(self) -> int:
+		"""Dimension of the audio."""
+		return self.y.ndim
+	
+	@immutable_property("Mutation not allowed.")
+	def __len__(self) -> int:
+		"""Dimension of the audio."""
+		return len(self.y)
 	
-	def __len__(self):
-		return len(self._y)
 	
 	#----------------------
-	# Tools
+	# Methods
 	#----------------------
 	
+	def print_info(self) -> None:
+		"""Prints info about the audio."""
+		print("-" * 50)
+		print(f"{'Title':<20}: {self.title}")
+		print(f"{'Type':<20}: {self._name}")
+		print(f"{'Duration':<20}: {self.duration:.2f} sec")
+		print(f"{'Sampling Rate':<20}: {self.sr} Hz")
+		print(f"{'Sampling Period':<20}: {(self.Ts*1000) :.4f} ms")
+		print("-" * 50)
+	
 	def __getitem__(self, key: slice) -> Self:
 		sliced_y = self._y[key]
 		t0_new = self.t[key.start] if key.start is not None else self.t0
@@ -85,59 +125,89 @@ class TimeDomainSignal(ModusaSignal):
 	@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,
+		fmt: str = "k-",
 		title: str | None = None,
+		label: str | None = None,
 		ylabel: str | None = "Amplitude",
 		xlabel: str | None = "Time (sec)",
 		ylim: tuple[float, float] | None = None,
 		xlim: tuple[float, float] | None = None,
 		highlight: list[tuple[float, float]] | None = None,
-	) -> plt.Figure:
+		vlines: list[float] | None = None,
+		hlines: list[float] | None = None,
+		show_grid: bool = False,
+		stem: bool | None = False,
+		legend_loc: str | None = None,
+	) -> plt.Figure | None:
 		"""
-		Plot the time-domain signal.
+		Plot the audio waveform using matplotlib.
 		
 		.. code-block:: python
-
-			signal.plot(color='g', marker='o', stem=True)
+		
+			from modusa.generators import AudioSignalGenerator
+			audio_example = AudioSignalGenerator.generate_example()
+			audio_example.plot(color="orange", title="Example Audio")
 		
 		Parameters
 		----------
-		scale_y : tuple[float, float], optional
-			Min-max values to scale the y-axis data.
-		ax : matplotlib.axes.Axes, optional
-			Axes to plot on; if None, creates a new figure.
-		color : str, default='b'
-			Line or stem color.
-		marker : str, optional
-			Marker style for each data point.
-		linestyle : str, optional
-			Line style to use if not using stem plot.
-		stem : bool, default=False
-			Whether to draw a stem plot instead of a line plot.
-		legend_loc : str, optional
-			If given, adds a legend at the specified location.
+		ax : matplotlib.axes.Axes | None
+			Pre-existing axes to plot into. If None, a new figure and axes are created.
+		fmt : str | None
+			Format of the plot as per matplotlib standards (Eg. "k-" or "blue--o)
+		title : str | None
+			Plot title. Defaults to the signal’s title.
+		label: str | None
+			Label for the plot, shown as legend.
+		ylabel : str | None
+			Label for the y-axis. Defaults to `"Amplitude"`.
+		xlabel : str | None
+			Label for the x-axis. Defaults to `"Time (sec)"`.
+		ylim : tuple[float, float] | None
+			Limits for the y-axis.
+		xlim : tuple[float, float] | None
+		highlight : list[tuple[float, float]] | None
+			List of time intervals to highlight on the plot, each as (start, end).
+		vlines: list[float]
+			List of x values to draw vertical lines. (Eg. [10, 13.5])
+		hlines: list[float]
+			List of y values to draw horizontal lines. (Eg. [10, 13.5])
+		show_grid: bool
+			If true, shows grid.
+		stem : bool
+			If True, use a stem plot instead of a continuous line. Autorejects if signal is too large.
+		legend_loc : str | None
+			If provided, adds a legend at the specified location (e.g., "upper right" or "best").
+			Limits for the x-axis.
 		
 		Returns
 		-------
-		matplotlib.axes.Axes
-			The axes object containing the plot.
-		
-		Note
-		----
-		This is useful for visualizing 1D signals obtained from time slices of spectrograms.
+		matplotlib.figure.Figure | None
+			The figure object containing the plot or None in case an axis is provided.
 		"""
 		
-		from modusa.io import Plotter
+		from modusa.tools.plotter import Plotter
 		
 		title = title or self.title
 		
-		fig: plt.Figure | None = Plotter.plot_signal(y=self.y, x=self.t, 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)
+		fig: plt.Figure | None = Plotter.plot_signal(
+			y=self.y,
+			x=self.t,
+			ax=ax,
+			fmt=fmt,
+			title=title,
+			label=label,
+			ylabel=ylabel,
+			xlabel=xlabel,
+			ylim=ylim,
+			xlim=xlim,
+			highlight=highlight,
+			vlines=vlines,
+			hlines=hlines,
+			show_grid=show_grid,
+			stem=stem,
+			legend_loc=legend_loc,
+		)
 		
 		return fig
 	
@@ -148,131 +218,164 @@ class TimeDomainSignal(ModusaSignal):
 	def __array__(self, dtype=None):
 		return np.asarray(self.y, dtype=dtype)
 	
+	def __array_ufunc__(self, ufunc, method, *inputs, **kwargs):
+		if method == "__call__":
+			input_arrays = [x.y if isinstance(x, self.__class__) else x for x in inputs]
+			result = ufunc(*input_arrays, **kwargs)
+			return self.__class__(y=result, sr=self.sr, title=f"{self.title}")
+		return NotImplemented
+	
 	def __add__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.add(self.y, other_data)
+		result = MathOps.add(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __radd__(self, other):
-		result = np.add(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.add(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __sub__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.subtract(self.y, other_data)
+		result = MathOps.subtract(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __rsub__(self, other):
-		result = np.subtract(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.subtract(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __mul__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.multiply(self.y, other_data)
+		result = MathOps.multiply(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __rmul__(self, other):
-		result = np.multiply(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.multiply(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __truediv__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.true_divide(self.y, other_data)
+		result = MathOps.divide(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __rtruediv__(self, other):
-		result = np.true_divide(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.divide(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __floordiv__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.floor_divide(self.y, other_data)
+		result = MathOps.floor_divide(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __rfloordiv__(self, other):
-		result = np.floor_divide(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.floor_divide(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __pow__(self, other):
 		other_data = other.y if isinstance(other, self.__class__) else other
-		result = np.power(self.y, other_data)
+		result = MathOps.power(self.y, other_data)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __rpow__(self, other):
-		result = np.power(other, self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.power(other_data, self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def __abs__(self):
-		result = np.abs(self.y)
+		other_data = other.y if isinstance(other, self.__class__) else other
+		result = MathOps.abs(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
+	def __or__(self, other):
+		if not isinstance(other, self.__class__):
+			raise excp.InputTypeError(f"Can only concatenate with another {self.__class__.__name__}")
+			
+		if self.sr != other.sr:
+			raise excp.InputValueError(f"Cannot concatenate: Sampling rates differ ({self.sr} vs {other.sr})")
+			
+		# Concatenate raw audio data
+		y_cat = np.concatenate([self.y, other.y])
+		
+		# Preserve t0 of the first signal
+		new_title = f"{self.title} | {other.title}"
+		return self.__class__(y=y_cat, sr=self.sr, t0=self.t0, title=new_title)
+	
 	
 	#--------------------------
 	# Other signal ops
 	#--------------------------
+	def abs(self) -> Self:
+		"""Compute the element-wise abs of the signal data."""
+		result = MathOps.abs(self.y)
+		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
+	
 	def sin(self) -> Self:
 		"""Compute the element-wise sine of the signal data."""
-		result = np.sin(self.y)
+		result = MathOps.sin(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def cos(self) -> Self:
 		"""Compute the element-wise cosine of the signal data."""
-		result = np.cos(self.y)
+		result = MathOps.cos(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def exp(self) -> Self:
 		"""Compute the element-wise exponential of the signal data."""
-		result = np.exp(self.y)
+		result = MathOps.exp(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def tanh(self) -> Self:
 		"""Compute the element-wise hyperbolic tangent of the signal data."""
-		result = np.tanh(self.y)
+		result = MathOps.tanh(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def log(self) -> Self:
 		"""Compute the element-wise natural logarithm of the signal data."""
-		result = np.log(self.y)
+		result = MathOps.log(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	def log1p(self) -> Self:
 		"""Compute the element-wise natural logarithm of (1 + signal data)."""
-		result = np.log1p(self.y)
+		result = MathOps.log1p(self.y)
 		return self.__class__(y=result, sr=self.sr, 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.y)
+		result = MathOps.log10(self.y)
 		return self.__class__(y=result, sr=self.sr, 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.y)
+		result = MathOps.log2(self.y)
 		return self.__class__(y=result, sr=self.sr, t0=self.t0, title=self.title)
 	
 	
 	#--------------------------
 	# Aggregation signal ops
 	#--------------------------
-	def mean(self) -> float:
+	def mean(self) -> "np.generic":
 		"""Compute the mean of the signal data."""
-		return float(np.mean(self.y))
+		return MathOps.mean(self.y)
 	
-	def std(self) -> float:
+	def std(self) -> "np.generic":
 		"""Compute the standard deviation of the signal data."""
-		return float(np.std(self.y))
+		return MathOps.std(self.y)
 	
-	def min(self) -> float:
+	def min(self) -> "np.generic":
 		"""Compute the minimum value in the signal data."""
-		return float(np.min(self.y))
+		return MathOps.min(self.y)
 	
-	def max(self) -> float:
+	def max(self) -> "np.generic":
 		"""Compute the maximum value in the signal data."""
-		return float(np.max(self.y))
+		return MathOps.max(self.y)
 	
-	def sum(self) -> float:
+	def sum(self) -> "np.generic":
 		"""Compute the sum of the signal data."""
-		return float(np.sum(self.y))
+		return MathOps.sum(self.y)
 	
 	#-----------------------------------
 	# Repr
@@ -291,7 +394,7 @@ class TimeDomainSignal(ModusaSignal):
 			formatter={'float_kind': lambda x: f"{x:.4g}"}
 		)
 		
-		return f"Signal({arr_str}, shape={data.shape}, kind={cls})"
+		return f"Signal({arr_str}, shape={data.shape}, type={cls})"
 	
 	def __repr__(self):
 		cls = self.__class__.__name__
@@ -306,4 +409,4 @@ class TimeDomainSignal(ModusaSignal):
 			formatter={'float_kind': lambda x: f"{x:.4g}"}
 		)
 		
-		return f"Signal({arr_str}, shape={data.shape}, kind={cls})"
+		return f"Signal({arr_str}, shape={data.shape}, type={cls})"

modusa/tools/__init__.py

@@ -0,0 +1,2 @@
+#!/usr/bin/env python3
+

modusa/{io → tools}/audio_converter.py

@@ -3,15 +3,14 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.io.base import ModusaIO
-from typing import Any
+from modusa.tools.base import ModusaTool
 import subprocess
 from pathlib import Path
 
 
-class AudioConverter(ModusaIO):
+class AudioConverter(ModusaTool):
 	"""
-	Converts audio using FFmpeg.
+	Converts audio to any given format using FFmpeg.
 
 	Note
 	----
@@ -59,6 +58,15 @@ class AudioConverter(ModusaIO):
 		"""
 		inp_audio_fp = Path(inp_audio_fp)
 		output_audio_fp = Path(output_audio_fp)
+		
+		if not inp_audio_fp.exists():
+			raise excp.FileNotFoundError(f"`inp_audio_fp` does not exist, {inp_audio_fp}")
+		
+		if inp_audio_fp == output_audio_fp:
+			raise excp.InputValueError(f"`inp_fp` and `output_fp` must be different")
+			
+		output_audio_fp.parent.mkdir(parents=True, exist_ok=True)
+		
 
 		cmd = [
 			"ffmpeg",

modusa/tools/audio_player.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.tools.base import ModusaTool
+from IPython.display import display, HTML, Audio
+import numpy as np
+
+class AudioPlayer(ModusaTool):
+	"""
+	Provides audio player in the jupyter notebook environment.
+	"""
+	
+	#--------Meta Information----------
+	_name = "Audio Player"
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-08"
+	#----------------------------------
+	
+	@staticmethod
+	def play(
+		y: np.ndarray,
+		sr: int,
+		regions: list[tuple[float, float]] | None = None,
+		title: str | None = None
+	) -> None:
+		"""
+		Plays audio clips for given regions in Jupyter Notebooks.
+
+		Parameters
+		----------
+		y : np.ndarray
+			Audio time series.
+		sr : int
+			Sampling rate.
+		regions : list of (float, float), optional
+			Regions to extract and play (in seconds).
+		title : str, optional
+			Title to display above audio players.
+
+		Returns
+		-------
+		None
+		"""
+		if not AudioPlayer._in_notebook():
+			return
+		
+		if title:
+			display(HTML(f"<h4>{title}</h4>"))
+		
+		clip_numbers = []
+		timings = []
+		players = []
+		
+		if regions:
+			for i, (start_sec, end_sec) in enumerate(regions):
+				
+				if start_sec is None:
+					start_sec = 0.0
+				if end_sec is None:
+					end_sec = y.shape[0] / sr
+				
+				start_sample = int(start_sec * sr)
+				end_sample = int(end_sec * sr)
+				clip = y[start_sample:end_sample]
+				audio_tag = Audio(data=clip, rate=sr)._repr_html_()
+				
+				clip_numbers.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>{i+1}</td>")
+				timings.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>{start_sec:.2f}s → {end_sec:.2f}s</td>")
+				players.append(f"<td style='padding:6px;'>{audio_tag}</td>")
+		else:
+			total_duration = len(y) / sr
+			audio_tag = Audio(data=y, rate=sr)._repr_html_()
+			
+			clip_numbers.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>1</td>")
+			timings.append(f"<td style='text-align:center; border-right:1px solid #ccc; padding:6px;'>0.00s → {total_duration:.2f}s</td>")
+			players.append(f"<td style='padding:6px;'>{audio_tag}</td>")
+			
+		# Wrap rows in a table with border
+		table_html = f"""
+		<div style="display:inline-block; border:1px solid #ccc; border-radius:6px; overflow:hidden;">
+			<table style="border-collapse:collapse;">
+				<tr style="background-color:#f2f2f2;">
+					<th style="text-align:left; padding:6px 12px;">Clip</th>
+					{''.join(clip_numbers)}
+				</tr>
+				<tr style="background-color:#fcfcfc;">
+					<th style="text-align:left; padding:6px 12px;">Timing</th>
+					{''.join(timings)}
+				</tr>
+				<tr>
+					<th style="text-align:left; padding:6px 12px;">Player</th>
+					{''.join(players)}
+				</tr>
+			</table>
+		</div>
+		"""
+		
+		return HTML(table_html)
+		
+			
+	@staticmethod
+	def _in_notebook() -> bool:
+		try:
+			from IPython import get_ipython
+			shell = get_ipython()
+			return shell and shell.__class__.__name__ == "ZMQInteractiveShell"
+		except ImportError:
+			return False
+		
+		

modusa/tools/base.py

@@ -0,0 +1,43 @@
+#!/usr/bin/env python3
+
+from abc import ABC, abstractmethod
+
+class ModusaTool(ABC):
+	"""
+	Base class for all tool: youtube downloader, audio converter, filter.
+	
+	>>> modusa-dev create io
+
+	.. code-block:: python
+		
+		# General template of a subclass of ModusaTool
+		from modusa.tools.base import ModusaTool
+
+		class MyCustomIOClass(ModusaIO):
+			#--------Meta Information----------
+			_name = "My Custom Tool"
+			_description = "My custom class for Tool."
+			_author_name = "Ankit Anand"
+			_author_email = "ankit0.anand0@gmail.com"
+			_created_at = "2025-07-06"
+			#----------------------------------
+			
+			@staticmethod
+			def do_something():
+				pass
+		
+	
+	Note
+	----
+	- This class is intended to be subclassed by any tool built for the modusa framework.
+	- In order to create a tool, you can use modusa-dev CLI to generate a template.
+	- It is recommended to treat subclasses of ModusaTool as namespaces and define @staticmethods with control parameters, rather than using instance-level __init__ methods.
+	"""
+	
+	#--------Meta Information----------
+	_name: str = "Modusa Tool"
+	_description: str = "Base class for any tool in the Modusa framework."
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-11"
+	#----------------------------------

modusa/tools/fourier_tranform.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from modusa.tools.base import ModusaTool
+
+
+class FourierTransform(ModusaTool):
+	"""
+	
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-11"
+	#----------------------------------
+	
+	def __init__(self):
+		super().__init__()
+