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

modusa/signals/signal1d.py

@@ -1,311 +0,0 @@
-#!/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 Signal1D(ModusaSignal):
-	"""
-
-	"""
-	
-	#--------Meta Information----------
-	name = "1D Signal"
-	description = ""
-	author_name = "Ankit Anand"
-	author_email = "ankit0.anand0@gmail.com"
-	created_at = "2025-07-02"
-	#----------------------------------
-	
-	@validate_args_type()
-	def __init__(self, y: np.ndarray, x: np.ndarray | None = None):
-		
-		if y.ndim != 1:
-			raise excp.InputValueError(f"`data` must have 1 dimension not {data.ndim}.")
-			
-		if x is None:
-			x = np.arange(y.shape[0])
-		else:
-			if x.ndim != 1:
-				raise excp.InputValueError(f"`x` must have 1 dimension not {x.ndim}.")
-			if x.shape[0] != y.shape[0]:
-				raise excp.InputValueError(f"`x` and `y` must have same shape.")
-		
-		super().__init__(data=y, data_idx=x)# Instantiating `ModusaSignal` class
-
-		self._x_unit = "index"
-		self._y_unit = ""
-		self._title = self.name
-		self._y_label = "y"
-		self._x_label = "x"
-		
-	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, x=new_data_idx)
-		new_signal.set_units(y_unit=self.y_unit, x_unit=self.x_unit)
-		new_signal.set_plot_labels(title=self.title, y_label=self.y_label, x_label=self.x_label)
-		
-		return new_signal
-	
-	#----------------------
-	# From methods
-	#----------------------
-	@classmethod
-	@validate_args_type()
-	def from_array(cls, y: np.ndarray, x: np.ndarray | None = None) -> Self:
-		"""
-		Loads `Signal1D` instance from numpy array or a python list.
-		
-		Note
-		----
-		- If you have python `list`, use `.from_list` instead
-		"""
-		
-		signal: Self = cls(y=y, x=x)
-			
-		return signal
-	
-	@classmethod
-	@validate_args_type()
-	def from_list(cls, y: list, x: list | None = None) -> Self:
-		"""
-		Loads `Signal1D` instance from a python list.
-		"""
-		y = np.array(y)
-		
-		if x is not None:
-			x = np.array(x)
-		
-		signal: Self = cls(y=y, x=x)
-			
-		return signal
-	
-	
-	#----------------------
-	# Setters
-	#----------------------
-
-	@validate_args_type()
-	def set_units(self, y_unit: str | None = None, x_unit: str | None = None) -> Self:
-		"""
-		Set the physical units for the y-axis and x-axis of the signal.
-		
-		This method attaches metadata describing the physical units of the signal.
-		These units are used for display and labeling purposes (e.g., in plots),
-		but do not affect the underlying signal data.
-	
-		Parameters
-		----------
-		y_unit : str or None
-			Unit of the y-axis (e.g., "V", "Amplitude"). If None, the unit is left unchanged.
-		x_unit : str or None
-			Unit of the x-axis (e.g., "s", "Hz"). If None, the unit is left unchanged.
-	
-		Returns
-		-------
-		Self
-			The signal instance with updated unit metadata. Supports method chaining.
-	
-		Raises
-		------
-		InputTypeError
-			If `y_unit` or `x_unit` is not a string or None.
-
-		Example
-		-------
-		.. code-block:: python
-			
-			# Set y-axis to volts and x-axis to seconds
-			signal.set_units("V", "s")
-		"""
-		
-		if y_unit is not None:
-			self._y_unit = y_unit
-		if x_unit is not None:
-			self._x_unit = x_unit
-			
-		return self
-	
-	@validate_args_type()
-	def set_plot_labels(
-		self,
-		title: str | None = None,
-		y_label: str | None = None,
-		x_label: str | None = None
-	) -> Self:
-		"""
-		Set plot-related labels: title, y-axis label, and x-axis label.
-	
-		This method is useful for customizing plots generated from the signal,
-		especially when exporting figures or displaying meaningful metadata.
-	
-		Parameters
-		----------
-		title : str or None, optional
-			The title of the plot (e.g., "Waveform" or "FFT Magnitude").
-		y_label : str or None, optional
-			Label for the y-axis (e.g., "Amplitude" or "Power (dB)").
-		x_label : str or None, optional
-			Label for the x-axis (e.g., "Time (s)" or "Frequency (Hz)").
-
-		Returns
-		-------
-		Self
-			A modified instance of the signal class.
-	
-		Raises
-		------
-		InputTypeError
-			If any provided argument is not a string or None.
-	
-		Examples
-		--------
-		.. code-block:: python
-
-			# Set plot title and axis labels for a time-domain signal
-			signal.set_plot_labels(
-				title="Time-Domain Signal",
-				y_label="Amplitude",
-				x_label="Time (s)"
-				)
-			"""
-		
-		if title is not None:
-			self._title = title
-		if y_label is not None:
-			self._y_label = y_label
-		if x_label is not None:
-			self._x_label = x_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 x(self) -> np.ndarray:
-		return self._data_idx
-
-	@immutable_property("Use `.set_units` instead.")
-	def y_unit(self) -> str:
-		return self._y_unit
-	
-	@immutable_property("Use `.set_units` instead.")
-	def x_unit(self) -> str:
-		return self._x_unit
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def title(self) -> str:
-		return self._title
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def y_label(self) -> str:
-		return self._y_label
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def x_label(self) -> str:
-		return self._x_label
-	
-	#----------------------
-	# Additional Properties
-	#----------------------
-	
-	@immutable_property(error_msg="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.x_label} ({self.x_unit})")
-	
-	#----------------------
-	# Plugins Access
-	#----------------------
-	
-	def trim(self, region: tuple[float, float]) -> Self:
-		"""
-		Return a new signal instance trimmed to a specific region of the x-axis.
-		
-		This method creates a new signal containing only the portion of the data
-		where `x` lies within the specified range. It is useful for zooming in on
-		a region of interest in time, frequency, or any other x-axis domain.
-	
-		Parameters
-		----------
-		region : tuple[float, float]
-			The (start, end) range of the x-axis to retain. Must be in the same
-			units as the x-axis (e.g., seconds, Hz, samples).
-	
-		Returns
-		-------
-		Self
-			A new instance of the signal class, trimmed to the specified region.
-	
-		Raises
-		------
-		InputTypeError
-			If `region` is not a tuple of two floats.
-	
-		Examples
-		--------
-		.. code-block:: python
-
-			# Trim the signal to the region between x = 0.2 and x = 0.6
-			trimmed = signal.trim((0.2, 0.6))
-		"""
-		
-		from modusa.plugins.trim import Trim1DPlugin
-		trimmed_signal: Self = Trim1DPlugin(region=region).apply(self)
-		
-		return trimmed_signal
-	
-	
-	@validate_args_type()
-	def plot(
-		self,
-		scale_y: tuple[float, float] | None = None,
-		scale_x: tuple[float, float] | None = None,
-		ax: plt.Axes | None = None,
-		color: str = "k",
-		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.Plot1DPlugin` Plugin.
-		"""
-		
-		from modusa.plugins import Plot1DSignalPlugin
-		
-		labels = labels or self.labels
-		stem = stem or False
-		
-		fig: plt.Figure = Plot1DSignalPlugin().apply(
-			signal=self,
-			scale_y=scale_y,
-			scale_x=scale_x,
-			ax=ax,
-			color=color,
-			marker=marker,
-			linestyle=linestyle,
-			stem=stem,
-			labels=labels,
-			legend_loc=legend_loc,
-			zoom=zoom,
-			highlight=highlight
-		)
-		
-		return fig
-	

modusa/signals/signal2d.py

@@ -1,226 +0,0 @@
-#!/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 Signal2D(ModusaSignal):
-	"""
-
-	"""
-	
-	#--------Meta Information----------
-	name = "2D Signal"
-	description = ""
-	author_name = "Ankit Anand"
-	author_email = "ankit0.anand0@gmail.com"
-	created_at = "2025-07-02"
-	#----------------------------------
-	
-	@validate_args_type()
-	def __init__(self, M: np.ndarray, r: np.ndarray | None = None, c: np.ndarray | None = None):
-		
-		if M.ndim != 2:
-			raise excp.InputValueError(f"`M` must have 2 dimensions not {M.ndim}.")
-		
-		if r is None:
-			r = np.arange(M.shape[0])
-		else:
-			if r.ndim != 1:
-				raise excp.InputValueError(f"`r` must have 1 dimension not {r.ndim}.")
-			if r.shape != M.shape[0]:
-				raise excp.InputValueError(f"`r` must have shape compatible with `M`.")
-		
-		if c is None:
-			c = np.arange(M.shape[0])
-		else:
-			if c.ndim != 1:
-				raise excp.InputValueError(f"`c` must have 1 dimension not {c.ndim}.")
-			if c.shape != M.shape[1]:
-				raise excp.InputValueError(f"`c` must have shape compatible with `M`.")
-		
-		super().__init__(data=M, data_idx={0: r, 1: c})# Instantiating `ModusaSignal` class
-		
-		self._M_unit = ""
-		self._r_unit = "index"
-		self._c_unit = "index"
-		
-		self._title = self.__class__.name
-		self._M_label = "Matrix"
-		self._r_label = "Row"
-		self._c_label = "Column"
-	
-	def _with_data(self, new_data: np.ndarray, new_data_idx: dict) -> Self:
-		"""Subclasses must override this to return a copy with new data."""
-		new_signal = self.__class__(M=new_data, r=new_data_idx[0], c=new_data_idx[1])
-		new_signal.set_units(M_unit=self.M_unit, y_unit=self.y_unit, x_unit=self.x_unit)
-		new_signal.set_plot_labels(title=self.title, M_label=self.M_label, y_label=self.y_label, x_label=self.x_label)
-		
-		return new_signal
-	
-	#----------------------
-	# From methods
-	#----------------------
-	@classmethod
-	@validate_args_type()
-	def from_array(cls, M: np.ndarray, r: np.ndarray | None = None, c: np.ndarray | None = None) -> Self:
-		
-		signal: Self = cls(M=M, r=r, c=c)
-		
-		return signal
-	
-	@classmethod
-	@validate_args_type()
-	def from_list(cls, M: list, r: list | None = None, c: list | None = None) -> Self:
-		
-		M = np.array(M)
-		if r is not None:
-			r = np.array(r)
-		if c is not None:
-			c = np.array(c)
-			
-		signal: Self = cls(M=M, r=r, c=c)
-		
-		return signal
-	
-	#----------------------
-	# Setters
-	#----------------------
-	
-	@validate_args_type()
-	def set_plot_labels(
-		self,
-		title: str | None = None,
-		M_label: str | None = None,
-		r_label: str | None = None,
-		c_label: str | None = None
-	) -> Self:
-		
-		if title is not None:
-			self._title = title
-		if M_label is not None:
-			self._M_label = M_label
-		if r_label is not None:
-			self._r_label = r_label
-		if c_label is not None:
-			self._c_label = c_label
-			
-		return self
-	
-	@validate_args_type()
-	def set_units(
-		self,
-		M_unit: str | None = None,
-		r_unit: str | None = None,
-		c_unit: str | None = None
-	) -> Self:
-			
-		if M_unit is not None:
-			self._M_unit = M_unit
-		if r_unit is not None:
-			self._r_unit = r_unit
-		if c_unit is not None:
-			self._c_unit = c_unit
-			
-		return self
-	
-	
-	
-	#----------------------
-	# Properties
-	#----------------------
-	
-	@immutable_property("Create a new object instead.")
-	def M(self) -> np.ndarray:
-		return self.data
-	
-	@immutable_property("Create a new object instead.")
-	def r(self) -> np.ndarray:
-		return self.data_idx[0]
-	
-	@immutable_property("Create a new object instead.")
-	def c(self) -> np.ndarray:
-		return self.data_idx[1]
-	
-	@immutable_property("Use `.set_units` instead.")
-	def M_unit(self) -> str:
-		return self._M_unit
-	
-	@immutable_property("Use `.set_units` instead.")
-	def r_unit(self) -> str:
-		return self._r_unit
-	
-	
-	@immutable_property("Use `.set_units` instead.")
-	def c_unit(self) -> str:
-		return self._c_unit
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def title(self) -> str:
-		return self._title
-	
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def M_label(self) -> str:
-		return self._M_label
-	
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def r_label(self) -> str:
-		return self._r_label
-	
-	
-	@immutable_property("Use `.set_labels` instead.")
-	def c_label(self) -> str:
-		return self._c_label
-	
-	
-	@property
-	def labels(self) -> tuple[str, str, str, str]:
-		"""Labels in a format appropriate for the plots."""
-		return (self.title, f"{self.M_label} ({self.M_unit})", f"{self.r_label} ({self.r_unit})", f"{self.c_label} ({self.c_unit})")
-	
-	#----------------------
-	# Plugins Access
-	#----------------------
-	def plot(
-		self,
-		log_compression_factor: int | None = None,
-		ax: plt.Axes | None = None,
-		labels: tuple[str, str, str, str] | None = None,
-		zoom: tuple[float, float, float, float] | None = None,
-		highlight: list[tuple[float, float, float, float]] | None = None,
-		cmap: str = "gray_r",
-		origin: str = "upper",
-		show_colorbar: bool = False,
-		cax: plt.Axes | None = None,
-		show_grid: bool = False,
-		tick_mode: str = "center", # or "edge"
-		value_range: tuple[float, float] | None = None
-	) -> plt.Figure:
-		"""
-		Applies `modusa.plugins.Plot2DPlugin`.
-		"""
-		from modusa.plugins import Plot2DMatrixPlugin
-		
-		fig = Plot2DMatrixPlugin().apply(
-			signal=self,
-			ax=ax,
-			labels=labels or self.labels,
-			zoom=zoom,
-			highlight=highlight,
-			log_compression_factor=log_compression_factor,
-			cmap=cmap,
-			origin=origin,
-			show_colorbar=show_colorbar,
-			cax=cax,
-			show_grid=show_grid,
-			tick_mode=tick_mode,
-			value_range=value_range
-		)
-		return fig
-