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

modusa/tools/math_ops.py

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+
+from modusa import excp
+from modusa.tools.base import ModusaTool
+from typing import Any
+import numpy as np
+
+class MathOps(ModusaTool):
+	"""
+	Performs arithmetic and NumPy-style ops.
+
+	Note
+	----
+	- Shape-changing operations like reshape, transpose, etc. are not yet supported. Use only element-wise or aggregation ops for now. 
+	- Index alignment must be handled carefully in future extensions.
+	"""
+	
+	def _axes_match(a1: tuple[np.ndarray, ...], a2: tuple[np.ndarray, ...]) -> bool:
+		"""
+		To check if two axes are same.
+
+		It checks the length of the axes and the corresponding values.
+		"""
+		if len(a1) != len(a2):
+			return False
+		return all(np.allclose(x, y, atol=1e-8) for x, y in zip(a1, a2))
+	
+	
+	#----------------------------------
+	# To handle basic element wise 
+	# math operations like
+	# +, -, *, **, / ...
+	#----------------------------------
+	
+	@staticmethod
+	def add(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.add(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be added") from e
+			
+		if isinstance(a, str) and isinstance(b, str): # numpy actually concatenates, we do not want that
+			raise excp.InputError(f"`a` and `b` can't be added")
+		return result
+	
+	@staticmethod
+	def subtract(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.subtract(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be subtracted") from e
+		return result
+		
+	@staticmethod
+	def multiply(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.multiply(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be multiplied") from e
+		
+		if isinstance(a, str) and isinstance(b, str): # numpy actually concatenates, we do not want that
+			raise excp.InputError(f"`a` and `b` can't be multiplied")
+		return result
+
+	@staticmethod
+	def divide(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.divide(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` and `b` can't be divided") from e
+		return result
+
+	@staticmethod
+	def power(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.power(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` can't be exponentiated with `b`") from e
+		return result
+	
+	@staticmethod
+	def floor_divide(a: Any, b: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.floor_divide(a, b)
+		except Exception as e:
+			raise excp.InputError(f"`a` can't be floor divided by `b`") from e
+		return result
+		
+	#----------------------------------
+	# To handle numpy aggregator ops
+	#----------------------------------
+	@staticmethod
+	def mean(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.mean(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find mean for `a`") from e
+		return result
+	
+	@staticmethod
+	def std(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		""""""
+		try:
+			result = np.std(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find std for `a`") from e
+		return result
+	
+	@staticmethod
+	def min(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.min(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find min for `a`") from e
+		return result
+	
+	@staticmethod
+	def max(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.max(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find max for `a`") from e
+		return result
+	
+	@staticmethod
+	def sum(a: Any, axis: int | None = None) -> np.generic | np.ndarray:
+		try:
+			result = np.sum(a, axis=axis)
+		except Exception as e:
+			raise excp.InputError(f"can't find sum for `a`") from e
+		return result
+	
+	#----------------------------------
+	# To handle numpy ops where the
+	# shapes are unaltered
+	# sin, cos, exp, log, ...
+	#----------------------------------
+	
+	@staticmethod
+	def sin(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.sin(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find sin for `a`") from e
+		return result
+	
+	@staticmethod
+	def cos(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.cos(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find cos for `a`") from e
+		return result
+	
+	@staticmethod
+	def tanh(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.tanh(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find tanh for `a`") from e
+		return result
+	
+	@staticmethod
+	def exp(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.exp(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find exp for `a`") from e
+		return result
+	
+	@staticmethod
+	def log(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log for `a`") from e
+		return result
+	
+	@staticmethod
+	def log10(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log10(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log10 for `a`") from e
+		return result
+	
+	@staticmethod
+	def log2(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log2(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log2 for `a`") from e
+		return result
+	
+	@staticmethod
+	def log1p(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.log1p(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find log1p for `a`") from e
+		return result
+	
+	
+	@staticmethod
+	def sqrt(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.sqrt(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find sqrt for `a`") from e
+		return result
+	
+	@staticmethod
+	def abs(a: Any) -> np.generic | np.ndarray:
+		try:
+			result = np.abs(a)
+		except Exception as e:
+			raise excp.InputError(f"can't find abs for `a`") from e
+		return result
+	
+	#------------------------------------
+	# TODO: Add shape-changing ops like 
+	# reshape, transpose, squeeze later
+	#------------------------------------
+	
+	@staticmethod
+	def reshape(a: Any, shape: int | tuple[int, ...]) -> np.ndarray:
+		try:
+			result = np.reshape(a, shape=shape)
+		except Exception as e:
+			raise excp.InputError(f"can't reshape `a`") from e
+		return result
+	

modusa/{io → tools}/plotter.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.io import ModusaIO
+from modusa.tools.base import ModusaTool
 import numpy as np
 import matplotlib.pyplot as plt
 from matplotlib.patches import Rectangle
@@ -13,7 +13,7 @@ import warnings
 warnings.filterwarnings("ignore", message="Glyph .* missing from font.*") # To supress any font related warnings, TODO: Add support to Devnagri font
 
 
-class Plotter(ModusaIO):
+class Plotter(ModusaTool):
 	"""
 	Plots different kind of signals using `matplotlib`.
 	
@@ -35,20 +35,20 @@ class Plotter(ModusaIO):
 	def plot_signal(
 		y: np.ndarray,
 		x: np.ndarray | None,
-		scale_y: tuple[float, float] | None = None,
 		ax: plt.Axes | None = None,
-		color: str = "k",
-		marker: str | None = None,
-		linestyle: str | None = None,
-		stem: bool = False,
-		labels: tuple[str, str, str] | None = None,
-		legend_loc: str | None = None,
+		fmt: str = "k",
 		title: str | None = None,
+		label: str | None = None,
 		ylabel: str | None = None,
 		xlabel: str | None = None,
 		ylim: tuple[float, float] | None = None,
 		xlim: tuple[float, float] | None = None,
 		highlight: list[tuple[float, float], ...] | None = None,
+		vlines: list[float] | None = None,
+		hlines: list[float] | None = None,
+		show_grid: bool = False,
+		stem: bool = False,
+		legend_loc: str = None,
 	) -> plt.Figure | None:
 		"""
 		Plots 1D signal using `matplotlib` with various settings passed through the
@@ -67,7 +67,6 @@ class Plotter(ModusaIO):
 			fig = Plotter.plot_signal(
 				y=y,
 				x=x,
-				scale_y=None,
 				ax=None,
 				color="blue",
 				marker=None,
@@ -86,8 +85,6 @@ class Plotter(ModusaIO):
 			The signal values to plot on the y-axis.
 		x: np.ndarray | None
 			The x-axis values. If None, indices of `y` are used.
-		scale_y: tuple[float, float] | None
-			Linear scaling for `y` values, (a, b) => ay+b
 		ax: plt.Axes | None
 			matplotlib Axes object to draw on. If None, a new figure and axis are created. Return type depends on parameter value.
 		color: str
@@ -131,33 +128,31 @@ class Plotter(ModusaIO):
 		if x.shape[0] != y.shape[0]:
 			raise excp.InputValueError(f"`y` and `x` must be of same shape")
 			
-		# Scale the signal if needed
-		if scale_y is not None:
-			if len(scale_y) != 2:
-				raise excp.InputValueError(f"`scale_y` must be tuple of two values (1, 2) => 1y+2")
-			a, b = scale_y
-			y = a * y + b
-			
 		# Create a figure
 		if ax is None:
 			fig, ax = plt.subplots(figsize=(15, 2))
 			created_fig = True
 		else:
 			fig = ax.get_figure()
-			created_fig = False 
-			
-		# Plot the signal with right configurations
-		plot_label = labels[0] if labels is not None and len(labels) > 0 else None
-		if stem:
-			ax.stem(x, y, linefmt=color, markerfmt='o', label=title)
-		elif marker is not None:
-			ax.plot(x, y, c=color, linestyle=linestyle, lw=1.5, marker=marker, label=title)
-		else:
-			ax.plot(x, y, c=color, linestyle=linestyle, lw=1.5, label=title)
-			
+			created_fig = False
+		
 		# Add legend
-		if legend_loc is not None:
+		if label is not None:
+			legend_loc = legend_loc or "best"
+			# Plot the signal and attach the label
+			if stem:
+				ax.stem(x, y, linefmt="k", markerfmt='o', label=label)
+			else:
+				ax.plot(x, y, fmt, lw=1.5, ms=3, label=label)
 			ax.legend(loc=legend_loc)
+		else:
+			# Plot the signal without label
+			if stem:
+				ax.stem(x, y, linefmt="k", markerfmt='o')
+			else:
+				ax.plot(x, y, fmt, lw=1.5, ms=3)
+		
+		
 			
 		# Set the labels
 		if title is not None:
@@ -173,21 +168,76 @@ class Plotter(ModusaIO):
 		if xlim is not None:
 			ax.set_xlim(xlim)
 			
-		# Highlight a list of regions
 		if highlight is not None:
-			for highlight_region in highlight:
+			y_min = np.min(y)
+			y_max = np.max(y)
+			y_range = y_max - y_min
+			label_box_height = 0.20 * y_range
+			
+			for i, highlight_region in enumerate(highlight):
 				if len(highlight_region) != 2:
-					raise excp.InputValueError(f"`highlight should be a list of tuple of 2 values (left, right) => (1, 10.5)")
+					raise excp.InputValueError("`highlight` should be a list of tuple of 2 values (left, right) => [(1, 10.5)]")
+					
 				l, r = highlight_region
-				ax.add_patch(Rectangle((l, np.min(y)), r - l, np.max(y) - np.min(y), color='red', alpha=0.2, zorder=10))
+				l = x[0] if l is None else l
+				r = x[-1] if r is None else r
+				
+				# Highlight rectangle (main background)
+				ax.add_patch(Rectangle(
+					(l, y_min),
+					r - l,
+					y_range,
+					color='red',
+					alpha=0.2,
+					zorder=10
+				))
+				
+				# Label box inside the top of the highlight
+				ax.add_patch(Rectangle(
+					(l, y_max - label_box_height),
+					r - l,
+					label_box_height,
+					color='red',
+					alpha=0.4,
+					zorder=11
+				))
+				
+				# Centered label inside that box
+				ax.text(
+					(l + r) / 2,
+					y_max - label_box_height / 2,
+					str(i + 1),
+					ha='center',
+					va='center',
+					fontsize=10,
+					color='white',
+					fontweight='bold',
+					zorder=12
+				)
+		
+		# Vertical lines
+		if vlines:
+			for xpos in vlines:
+				ax.axvline(x=xpos, color='blue', linestyle='--', linewidth=2, zorder=5)
+				
+		# Horizontal lines
+		if hlines:
+			for ypos in hlines:
+				ax.axhline(y=ypos, color='blue', linestyle='--', linewidth=2, zorder=5)
+				
+		# Show grid
+		if show_grid:
+			ax.grid(True, color="gray", linestyle="--", linewidth=0.5)
 				
 		# Show/Return the figure as per needed
 		if created_fig:
 			fig.tight_layout()
 			if Plotter._in_notebook():
+				plt.tight_layout()
 				plt.close(fig)
 				return fig
 			else:
+				plt.tight_layout()
 				plt.show()
 				return fig
 	
@@ -197,7 +247,6 @@ class Plotter(ModusaIO):
 		M: np.ndarray,
 		r: np.ndarray | None = None,
 		c: np.ndarray | None = None,
-		log_compression_factor: int | float | None = None,
 		ax: plt.Axes | None = None,
 		cmap: str = "gray_r",
 		title: str | None = None,
@@ -207,7 +256,10 @@ class Plotter(ModusaIO):
 		rlim: tuple[float, float] | None = None,
 		clim: tuple[float, float] | None = None,
 		highlight: list[tuple[float, float, float, float]] | None = None,
+		vlines: list[float] | None = None,
+		hlines: list[float] | None = None,
 		origin: str = "lower",  # or "lower"
+		gamma: int | float | None = None,
 		show_colorbar: bool = True,
 		cax: plt.Axes | None = None,
 		show_grid: bool = True,
@@ -307,8 +359,8 @@ class Plotter(ModusaIO):
 			raise excp.InputValueError(f"`c` must have shape as `M column` not {c.shape}")
 			
 		# Scale the signal if needed
-		if log_compression_factor is not None:
-			M = np.log1p(float(log_compression_factor) * M)
+		if gamma is not None:
+			M = np.log1p(float(gamma) * M)
 			
 		# Create a figure
 		if ax is None:
@@ -377,14 +429,65 @@ class Plotter(ModusaIO):
 		if clim is not None:
 			ax.set_xlim(clim)
 			
-		# Highlight a list of regions
 		if highlight is not None:
-			for r1, r2, c1, c2 in highlight:
+			row_range = r.max() - r.min()
+			label_box_height = 0.08 * row_range
+			
+			for i, highlight_region in enumerate(highlight):
+				if len(highlight_region) != 4 and len(highlight_region) != 2:
+					raise excp.InputValueError(
+						"`highlight` should be a list of tuple of 4 or 2 values (row_min, row_max, col_min, col_max) or (col_min, col_max) => [(1, 10.5, 2, 40)] or [(2, 40)] "
+					)
+				
+				if len(highlight_region) == 2:
+					r1, r2 = None, None
+					c1, c2 = highlight_region
+				elif len(highlight_region) == 4:
+					r1, r2, c1, c2 = highlight_region
+				
+				r1 = r[0] if r1 is None else r1
+				r2 = r[-1] if r2 is None else r2
+				c1 = c[0] if c1 is None else c1
+				c2 = c[-1] if c2 is None else c2
+				
 				row_min, row_max = min(r1, r2), max(r1, r2)
 				col_min, col_max = min(c1, c2), max(c1, c2)
+				
 				width = col_max - col_min
 				height = row_max - row_min
-				ax.add_patch(Rectangle((col_min, row_min), width, height, color='red', alpha=0.2, zorder=10))
+				
+				# Main red highlight box
+				ax.add_patch(Rectangle(
+					(col_min, row_min),
+					width,
+					height,
+					color='red',
+					alpha=0.2,
+					zorder=10
+				))
+				
+				# Label box inside top of highlight (just below row_max)
+				ax.add_patch(Rectangle(
+					(col_min, row_max - label_box_height),
+					width,
+					label_box_height,
+					color='red',
+					alpha=0.4,
+					zorder=11
+				))
+				
+				# Centered label in that box
+				ax.text(
+					(col_min + col_max) / 2,
+					row_max - (label_box_height / 2),
+					str(i + 1),
+					ha='center',
+					va='center',
+					fontsize=10,
+					color='white',
+					fontweight='bold',
+					zorder=12
+				)
 				
 		# Show colorbar
 		if show_colorbar is not None:
@@ -392,9 +495,19 @@ class Plotter(ModusaIO):
 			if Mlabel is not None:
 				cbar.set_label(Mlabel)
 				
+		# Vertical lines
+		if vlines:
+			for xpos in vlines:
+				ax.axvline(x=xpos, color='blue', linestyle='--', linewidth=2, zorder=5)
+				
+		# Horizontal lines
+		if hlines:
+			for ypos in hlines:
+				ax.axhline(y=ypos, color='blue', linestyle='--', linewidth=2, zorder=5)
+				
 		# Show grid
 		if show_grid:
-			ax.grid(True, color="gray", linestyle="--", linewidth=0.5) # TODO
+			ax.grid(True, color="gray", linestyle="--", linewidth=0.5)
 			
 		# Show/Return the figure as per needed
 		if created_fig:

modusa/{io → tools}/youtube_downloader.py

@@ -3,12 +3,12 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.io.base import ModusaIO
+from modusa.tools.base import ModusaTool
 from typing import Any
 from pathlib import Path
 import yt_dlp
 
-class YoutubeDownloader(ModusaIO):
+class YoutubeDownloader(ModusaTool):
 	"""
 	Download highest quality audio/video from YouTube.
 

modusa/utils/excp.py

@@ -4,73 +4,40 @@
 #----------------------------------------
 # Base class errors
 #----------------------------------------
-class MusaBaseError(Exception):
+class ModusaBaseError(Exception):
 	"""
 	Ultimate base class for any kind of custom errors.
 	"""
 	pass
 
-class TypeError(MusaBaseError):
+class TypeError(ModusaBaseError):
 	pass
 	
-class InputError(MusaBaseError):
+class InputError(ModusaBaseError):
 	"""
 	Any Input type error.
 	"""
 
-class InputTypeError(MusaBaseError):
+class InputTypeError(ModusaBaseError):
 	"""
 	Any Input type error.
 	"""
 
-class InputValueError(MusaBaseError):
+class InputValueError(ModusaBaseError):
 	"""
 	Any Input type error.
 	"""
 	
-class ImmutableAttributeError(MusaBaseError):
+class ImmutableAttributeError(ModusaBaseError):
 	"""Raised when attempting to modify an immutable attribute."""
 	pass
 	
-class FileNotFoundError(MusaBaseError):
+class FileNotFoundError(ModusaBaseError):
 	"""Raised when file does not exist."""
 	pass
 	
-	
-class PluginInputError(MusaBaseError):
-	pass
-
-class PluginOutputError(MusaBaseError):
+class PluginInputError(ModusaBaseError):
 	pass
-	
-
 
-class SignalOpError(MusaBaseError):
-	pass
-	
-class AttributeNotFoundError(MusaBaseError):
-	pass
-	
-class ParsingError(MusaBaseError):
-	"""
-	Base class for any parsing related issues
-	"""
-	pass
-
-class ValidationError(MusaBaseError):
-	"""
-	Base class for all input validation error
-	"""
-	pass
-
-class GenerationError(MusaBaseError):
-	"""
-	Error when generation fails
-	"""
-	pass
-
-class FileLoadingError(MusaBaseError):
-	"""
-	Error loading a file
-	"""
+class PluginOutputError(ModusaBaseError):
 	pass

{modusa-0.2.21.dist-info → modusa-0.2.23.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: modusa
-Version: 0.2.21
+Version: 0.2.23
 Summary: A modular signal analysis python library.
 Author-Email: Ankit Anand <ankit0.anand0@gmail.com>
 License: MIT
@@ -9,6 +9,7 @@ Requires-Dist: numpy>=2.2.6
 Requires-Dist: matplotlib>=3.10.3
 Requires-Dist: yt-dlp>=2025.6.30
 Requires-Dist: librosa==0.10.1
+Requires-Dist: IPython>=8.0.0
 Description-Content-Type: text/markdown
 
 # modusa