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

modusa/__init__.py

@@ -1 +1,8 @@
-from modusa.utils import excp, config
+from modusa.utils import excp, config
+
+#=====Giving access to plot functions to plot multiple signals.=====
+from modusa.tools import plot1d, plot2d
+from modusa.tools import play, convert
+from modusa.tools import download
+from modusa.tools import load
+#=====

modusa/devtools/{generate_doc_source.py → generate_docs_source.py}

@@ -9,17 +9,17 @@ from collections import defaultdict
 # === Configuration ===
 BASE_MODULES = [
     'modusa.tools',
-    'modusa.signals',
+    'modusa.models',
     'modusa.generators',
     'modusa.plugins',
-    'modusa.io'
+#   'modusa.io'
 ]
 OUTPUT_DIRS = [
     Path('docs/source/tools'),
-    Path('docs/source/signals'),
+    Path('docs/source/models'),
     Path('docs/source/generators'),
     Path('docs/source/plugins'),
-    Path('docs/source/io')
+#   Path('docs/source/io')
 ]
 
 # Ensure output directories exist
@@ -81,7 +81,7 @@ def write_index_rst_file(tools_by_module, output_dir, section_name="Tools"):
             f.write(f"   {name}\n")
 
 # === Main Script ===
-def generate_doc_source():
+def generate_docs_source():
     for base_module, output_dir in zip(BASE_MODULES, OUTPUT_DIRS):
         module_class_map = get_classes_grouped_by_module(base_module)
     

modusa/devtools/generate_template.py

@@ -28,11 +28,11 @@ GENERATOR_INFO = {
 	"template_dump_dp": SRC_CODE_DIR / "generators",
 	"test_template_dump_dp": TESTS_DIR / "test_generators"
 }
-SIGNAL_INFO = {
-	"template_fp": TEMPLATES_DIR / "signal.py",
+MODEL_INFO = {
+	"template_fp": TEMPLATES_DIR / "model.py",
 	"test_template_fp": TEMPLATES_DIR / "test.py",
-	"template_dump_dp": SRC_CODE_DIR / "signals",
-	"test_template_dump_dp": TESTS_DIR / "test_signals"
+	"template_dump_dp": SRC_CODE_DIR / "models",
+	"test_template_dump_dp": TESTS_DIR / "test_models"
 }
 TOOL_INFO = {
 	"template_fp": TEMPLATES_DIR / "tool.py",
@@ -53,7 +53,7 @@ class TemplateGenerator():
 	def get_path_info(for_what: str):
 		if for_what == "plugin": return PLUGIN_INFO
 		if for_what == "io": return IO_INFO
-		if for_what == "signal": return SIGNAL_INFO
+		if for_what == "model": return MODEL_INFO
 		if for_what == "tool": return TOOL_INFO
 		if for_what == "generator": return GENERATOR_INFO
 	

modusa/devtools/main.py

@@ -2,7 +2,7 @@
 
 
 from .generate_template import TemplateGenerator
-from .generate_doc_source import generate_doc_source
+from .generate_docs_source import generate_docs_source
 from .list_plugins import list_plugins
 from . import list_authors
 
@@ -23,10 +23,10 @@ def main():
 		
 		create_subparsers.add_parser("tool", help="Create a new tool class").set_defaults(func=lambda:TemplateGenerator.create_template("tool"))
 		create_subparsers.add_parser("plugin", help="Create a new plugin class").set_defaults(func=lambda:TemplateGenerator.create_template("plugin"))
-		create_subparsers.add_parser("signal", help="Create a new signal class").set_defaults(func=lambda:TemplateGenerator.create_template("signal"))
+		create_subparsers.add_parser("model", help="Create a new model class").set_defaults(func=lambda:TemplateGenerator.create_template("model"))
 		create_subparsers.add_parser("generator", help="Create a new signal generator class").set_defaults(func=lambda:TemplateGenerator.create_template("generator"))
 		create_subparsers.add_parser("io", help="Create a new IO class").set_defaults(func=lambda:TemplateGenerator.create_template("io"))
-		create_subparsers.add_parser("doc", help="Create a new IO class").set_defaults(func=lambda:generate_doc_source())
+		create_subparsers.add_parser("docs", help="Generate the docs").set_defaults(func=lambda:generate_docs_source())
 		
 		# --- LIST group ---
 		list_parser = subparsers.add_parser("list", help="List information about Modusa components")

modusa/devtools/templates/generator.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.generators import ModusaGenerator
+from modusa.generators.base import ModusaGenerator
 
 
 class {class_name}(ModusaGenerator):

modusa/devtools/templates/io.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type
-from modusa.io import ModusaIO
+from modusa.io.base import ModusaIO
 
 
 class {class_name}(ModusaIO):

modusa/devtools/templates/{signal.py → model.py}

@@ -3,17 +3,18 @@
 
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type
-from modusa.signals.base import ModusaSignal
+from modusa.signals.base import ?
 from typing import Self, Any
 import numpy as np
 
-class {class_name}(ModusaSignal):
+class {class_name}():
 	"""
 
 	"""
 	
 	#--------Meta Information----------
 	_name = ""
+	_nickname = "" # This is to be used in repr/str methods
 	_description = ""
 	_author_name = "{author_name}"
 	_author_email = "{author_email}"
@@ -26,15 +27,21 @@ class {class_name}(ModusaSignal):
 	
 		self.title = "" # This title will be used as plot title by default
 		
-	#----------------------
+	#-----------------------------------
 	# Properties
-	#----------------------
+	#-----------------------------------
 		
-	
-	
-	
-	
-	
-	#----------------------
+		
+	#===================================
+		
+		
+		
+		
+		
+		
+	#-----------------------------------
 	# Tools
-	#----------------------
+	#-----------------------------------
+		
+		
+	#===================================

modusa/devtools/templates/plugin.py

@@ -3,7 +3,7 @@
 
 from modusa import excp
 from modusa.decorators import immutable_property, validate_args_type, plugin_safety_check
-from modusa.plugins import ModusaPlugin
+from modusa.plugins.base import ModusaPlugin
 
 
 class {class_name}(ModusaPlugin):

modusa/generators/__init__.py

@@ -1,3 +1,13 @@
 #!/usr/bin/env python3
 
-from .audio_waveforms import AudioWaveformGenerator
+from .base import ModusaGenerator
+
+from .s_ax import SAxGen
+from .t_ax import TAxGen
+
+from .s1d import S1DGen
+from .tds import TDSGen
+from .audio import AudioGen
+
+from .s2d import S2DGen
+from .ftds import FTDSGen

modusa/generators/audio.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from .base import ModusaGenerator
+from modusa.models.t_ax import TAx
+from modusa.models.audio import Audio
+from modusa.models.data import Data
+import numpy as np
+from pathlib import Path
+
+class AudioGen(ModusaGenerator):
+	"""
+	Provides user friendly APIs to generate instances of different 
+	`AudioSignal` instances.
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-27"
+	#----------------------------------
+	
+	@staticmethod
+	def from_array(
+		y: np.ndarray,
+		sr: float | int = 1.0,
+		t0: float | int = 0.0,
+		y_label: str = "Amplitude",
+		t_label: str = "Time (sec)",
+		title: str = "Audio Signal"
+	) -> Audio:
+		"""
+		Create `AudioSignal` instance from basic data structures.
+
+		.. code-block:: python
+
+			import modusa as ms
+			t = ms.tds.from_array([1, 2, 3])
+			print(t)
+			t.print_info()
+		
+		Parameters
+		----------
+		y: np.ndarray
+			- Audio data array.
+		sr: float | int
+			- Sampling rate.
+		t0: float | int
+			- Start timestamp.
+		y_label: str
+			- Y label for the signal.
+			- Default: "Y"
+		t_label: str
+			- T label for the signal.
+			- Default: "Time (sec)"
+		title: str
+			- Title for the signal.
+			- Default: "1D Signal"
+		Returns
+		-------
+		Audio
+			An instance of Audio.
+		"""
+		assert isinstance(y, np.ndarray)
+		assert isinstance(sr, (int, float)) and isinstance(t0, (int, float))
+		assert isinstance(y_label, str) and isinstance(t_label, str) and isinstance(title, str)
+		
+		assert y.ndim == 1
+		
+		sr = float(sr)
+		t0 = float(t0)
+		
+		t = TAx(n_points=y.shape[0], sr=sr, t0=t0, label=t_label) # Creating a signal axis instance
+		y = Data(values=y, label=y_label)
+		
+		return Audio(y=y, t=t, title=title)
+	
+	@classmethod
+	def from_youtube(cls, url: str, sr: int | float = None):
+		"""
+		Loads audio from youtube at a given sr.
+		The audio is deleted from the device
+		after loading.
+		
+		.. code-block:: python
+			
+			import modusa as ms
+			audio = ms.audio.from_youtube(
+				url="https://www.youtube.com/watch?v=lIpw9-Y_N0g", 
+				sr=None
+			)
+
+		PARAMETERS
+		----------
+		url: str
+			Link to the YouTube video.
+		sr: int
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		Audio:
+			An `Audio` instance with loaded audio content from YouTube.
+		"""
+		
+		from modusa.tools.youtube_downloader import YoutubeDownloader
+		from modusa import convert
+		import soundfile as sf
+		from scipy.signal import resample
+		import tempfile
+		
+		# Download the audio in temp directory using tempfile module
+		with tempfile.TemporaryDirectory() as tmpdir:
+			audio_fp: Path = YoutubeDownloader.download(url=url, content_type="audio", output_dir=Path(tmpdir))
+			
+			# Convert the audio to ".wav" form for loading
+			wav_audio_fp: Path = convert(inp_audio_fp=audio_fp, output_audio_fp=audio_fp.with_suffix(".wav"))
+			
+			# Load the audio in memory
+			audio_data, audio_sr = sf.read(wav_audio_fp)
+			
+			# Convert to mono if it's multi-channel
+			if audio_data.ndim > 1:
+				audio_data = audio_data.mean(axis=1)
+				
+			# Resample if needed
+			if sr is not None:
+				if audio_sr != sr:
+					n_samples = int(len(audio_data) * sr / audio_sr)
+					audio_data = resample(audio_data, n_samples)
+					audio_sr = sr
+					
+		audio = cls.from_array(y=audio_data, sr=audio_sr, title=audio_fp.stem)
+		
+		return audio
+	
+	@classmethod
+	def from_filepath(cls, fp: str | Path, sr: int | float = None):
+		"""
+		Loads audio from filepath at a given sr.
+		
+		.. code-block:: python
+			
+			import modusa as ms
+			audio = ms.audio.from_filepath(
+				fp="path/to/audio.wav",
+				sr=None
+			)
+
+		PARAMETERS
+		----------
+		fp: str | Path
+			Audio file path.
+		sr: int
+			Sampling rate to load the audio in.
+		
+		Returns
+		-------
+		Audio:
+			An `Audio` instance with loaded audio content.
+		"""
+		import soundfile as sf
+		from scipy.signal import resample
+		from pathlib import Path
+		
+		fp = Path(fp)
+		# Load the audio in memory
+		audio_data, audio_sr = sf.read(fp)
+		
+		# Convert to mono if it's multi-channel
+		if audio_data.ndim > 1:
+			audio_data = audio_data.mean(axis=1)
+			
+		# Resample if needed
+		if sr is not None:
+			if audio_sr != sr:
+				n_samples = int(len(audio_data) * sr / audio_sr)
+				audio_data = resample(audio_data, n_samples)
+				audio_sr = sr
+				
+		audio = cls.from_array(y=audio_data, sr=audio_sr, title=fp.stem)
+		
+		return audio
+	

modusa/generators/audio_waveforms.py

@@ -4,7 +4,7 @@
 from modusa import excp
 from modusa.decorators import validate_args_type
 from modusa.generators.base import ModusaGenerator
-from modusa.signals.audio_signal import AudioSignal
+from modusa.models.audio_signal import AudioSignal
 import numpy as np
 
 class AudioWaveformGenerator(ModusaGenerator):

modusa/generators/base.py

@@ -2,7 +2,7 @@
 
 from modusa import excp
 from modusa.decorators import validate_args_type, immutable_property
-from modusa.signals.base import ModusaSignal
+from modusa.models.base import ModusaSignal
 from abc import ABC, abstractmethod
 from typing import Any
 

modusa/generators/ftds.py

@@ -0,0 +1,298 @@
+#!/usr/bin/env python3
+
+
+from modusa import excp
+from modusa.decorators import validate_args_type
+from .base import ModusaGenerator
+from modusa.models.data import Data
+from modusa.models.s_ax import SAx
+from modusa.models.t_ax import TAx
+from modusa.models.ftds import FTDS
+import numpy as np
+
+class FTDSGen(ModusaGenerator):
+	"""
+	Provides user friendly APIs to generate instances of different 
+	`FTDS` instances.
+	"""
+	
+	#--------Meta Information----------
+	_name = ""
+	_description = ""
+	_author_name = "Ankit Anand"
+	_author_email = "ankit0.anand0@gmail.com"
+	_created_at = "2025-07-27"
+	#----------------------------------
+	
+	@staticmethod
+	def from_array(
+		M: np.ndarray | list | float | int | np.generic,
+		f: np.ndarray | list | float | int | np.generic | None = None,
+		sr: int | float = 1.0,
+		t0: int | float = 0.0,
+		M_label: str = "M",
+		f_label: str = "Feature",
+		t_label: str = "Time (sec)",
+		title: str = "Feature Time Domain Signal"
+	) -> FTDS:
+		"""
+		Create `FDTS` instance from basic data structures.
+
+		.. code-block:: python
+
+			import modusa as ms
+			M = ms.ftds.from_array([1, 2, 3])
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		M: np.ndarray | list | float | int | np.generic
+			- Data values.
+		f: np.ndarray | list | float | int | np.generic | None
+			- y axis values.
+			- Default: None → Creates an integer indexing.
+		sr: int | float
+			- Sampling rate / Frame rate.
+			- Default: 1.0
+		t0: int | float
+			- Start timestamp.
+			- Default: 0.0
+		M_label: str
+			- Label for the data.
+			- Default: "M"
+		f_label: str
+			- Feature label for the signal.
+			- Default: "Feature"
+		t_label: str
+			- Time label for the signal.
+			- Default: "Time (sec)"
+		title: str
+			- Title for the signal.
+			- Default: "Feature Time Domain Signal"
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		assert isinstance(M, (np.ndarray, list, float, int, np.generic))
+		assert isinstance(f, (np.ndarray, list, float, int, np.generic)) or f is None
+		assert isinstance(sr, (int, float)) and isinstance(t0, (int, float))
+		assert isinstance(M_label, str) and isinstance(f_label, str) and isinstance(t_label, str) and isinstance(title, str)
+		
+		if isinstance(M, (float, int, np.generic)): M = [[M]] # Convert to list of 1 element
+		if isinstance(f, (float, int, np.generic)): f = [f] # Convert to list of 1 element
+		
+		M = np.asarray(M)
+		assert M.ndim == 2
+		
+		if f is None: f = np.arange(M.shape[0])
+		else: f = np.asarray(f)
+		assert f.ndim == 1
+		assert f.shape[0] == M.shape[0], "Shape mismatch"
+		
+		sr = float(sr)
+		t0 = float(t0)
+		
+		M = Data(values=M, label=M_label)
+		f = SAx(values=f, label=f_label)
+		t = TAx(n_points=M.shape[1], sr=sr, t0=t0, label=t_label)
+		
+		return FTDS(M=M, f=f, t=t, title=title)
+	
+	@classmethod
+	def zeros(cls, shape, f=None, sr=1.0, t0=0.0) -> FTDS:
+		"""
+		Create `FTDS` instance with all zeros.
+
+		.. code-block:: python
+
+			import modusa as ms
+			M = ms.ftds.zeros((10, 5))
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		shape: tuple[int, int]
+			- Shape of the signal with zeros.
+			- Must be 1 dimensional
+			- E.g. (10, 5)
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		assert isinstance(shape, tuple)
+		M = np.zeros(shape)
+		
+		return cls.from_array(M=M, f=f, sr=sr, t0=t0, title="Zeros")
+	
+	@classmethod
+	def zeros_like(cls, signal: FTDS) -> FTDS:
+		"""
+		Create `FTDS` instance similar to `signal`
+		but with all entries being zeros.
+
+		.. code-block:: python
+
+			import modusa as ms
+			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
+			M = ms.ftds.zeros_like(signal)
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		signal: FTDS
+			- Reference signal to create zeros like that.
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		
+		assert signal.__class__ in [FTDS]
+		
+		M = np.zeros(signal.shape)
+		f = signal._f
+		t = signal._t
+		
+		M_label = signal._M_label
+		f_label = signal._f_label
+		t_label = signal._t_label
+		title = signal._title
+		
+		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
+	
+	
+	@classmethod
+	def ones(cls, shape: tuple[int, int]) -> FTDS:
+		"""
+		Create `FTDS` instance with all ones.
+
+		.. code-block:: python
+
+			import modusa as ms
+			M = ms.ftds.ones((10, 5))
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		shape: tuple[int, int]
+			- Shape of the signal with ones.
+			- Must be 1 dimensional
+			- E.g. (10, 5)
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		assert isinstance(shape, tuple)
+		M = np.ones(shape)
+		
+		return cls.from_array(M=M, title="Ones")
+	
+	@classmethod
+	def ones_like(cls, signal: FTDS) -> FTDS:
+		"""
+		Create `FTDS` instance similar to `signal`
+		but with all entries being ones.
+
+		.. code-block:: python
+
+			import modusa as ms
+			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
+			M = ms.ftds.ones_like(signal)
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		signal: FTDS
+			- Reference signal to create ones like that.
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		
+		assert signal.__class__ in [FTDS]
+		
+		M = np.ones(signal.shape)
+		f = signal._f
+		t = signal._t
+		
+		M_label = signal._M_label
+		f_label = signal._f_label
+		t_label = signal._t_label
+		title = signal._title
+		
+		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
+	
+	@classmethod
+	def random(cls, shape: tuple[int, int]) -> FTDS:
+		"""
+		Create `FTDS` instance with random entries.
+
+		.. code-block:: python
+
+			import modusa as ms
+			M = ms.ftds.random((10, 5))
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		shape: tuple[int, int]
+			- Shape of the signal with random values.
+			- Must be 1 dimensional
+			- E.g. (10, 5)
+		Returns
+		-------
+		FTDS
+			An instance of FTDS.
+		"""
+		assert isinstance(shape, tuple)
+		M = np.random.random(shape)
+		
+		return cls.from_array(M=M, title="Random")
+	
+	@classmethod
+	def random_like(cls, signal: FTDS) -> FTDS:
+		"""
+		Create `FTDS` instance similar to `signal`
+		but with random entries.
+
+		.. code-block:: python
+
+			import modusa as ms
+			signal = ms.ftds.from_array([[1, 2, 3], [4, 5, 6]])
+			M = ms.ftds.random_like(signal)
+			print(M)
+			M.print_info()
+		
+		Parameters
+		----------
+		signal: FTDS
+			- Reference signal.
+		Returns
+		-------
+		FTDS
+			An instance of FTDS with random values.
+		"""
+		
+		assert signal.__class__ in [FTDS]
+		
+		M = np.random.random(signal.shape)
+		f = signal._f
+		t = signal._t
+		
+		M_label = signal._M_label
+		f_label = signal._f_label
+		t_label = signal._t_label
+		title = signal._title
+		
+		return cls.from_array(M=M, f=f, t=t, M_label=M_label, f_label=f_label, t_label=t_label, title=title)
+