Merge pull request #31 from upb-lea/CorrectionFunctionParameterDescription

Review function parameter description and correct findings

Author: gituser789

pysignalscope/functions.py

@@ -38,29 +38,29 @@ def fft(period_vector_t_i: Union[List[List[float]], np.ndarray], sample_factor:
     >>> out = pss.fft(example_waveform, plot=True, mode='rad', f0=25000, title='ffT input current')
 
     :param period_vector_t_i: numpy-array [[time-vector[,[current-vector]]. One period only
-    :type period_vector_t_i: np.array
-    :param sample_factor: f_sampling/f_period, defaults to 1000
+    :type period_vector_t_i: np.array or List[List[float]
+    :param sample_factor: f_sampling/f_period with default = 1000 (optional parameter)
     :type sample_factor: int
-    :param plot: insert anything else than "no" or 'False' to show a plot to visualize input and output
+    :param plot: insert anything else than "no" or 'False' to show a plot to visualize input and output (optional parameter)
     :type plot: str
-    :param mode: 'rad'[default]: full period is 2*pi, 'deg': full period is 360°, 'time': time domain.
+    :param mode: 'rad'[default]: full period is 2*pi, 'deg': full period is 360°, 'time': time domain. (optional parameter)
     :type mode: str
-    :param f0: fundamental frequency. Needs to be set in 'rad'- or 'deg'-mode
+    :param f0: fundamental frequency. Needs to be set in 'rad'- or 'deg'-modewith (optional parameter)
     :type f0: float
-    :param title: plot window title, defaults to 'ffT'
+    :param title: plot window title, defaults to 'ffT' (optional parameter)
     :type title: str
-    :param filter_type: 'factor'[default] or 'harmonic' or 'disabled'.
+    :param filter_type: 'factor'[default] or 'harmonic' or 'disabled'. (optional parameter)
     :type filter_type: str
-    :param filter_value_factor: filters out amplitude-values below a certain factor of max. input amplitude.
+    :param filter_value_factor: filters out amplitude-values below a certain factor of max. input amplitude. (optional parameter)
         Should be 0...1, default to 0.01 (1%)
     :type filter_value_factor: float
-    :param filter_value_harmonic: filters out harmonics up to a certain number. Default value is 100.
+    :param filter_value_harmonic: filters out harmonics up to a certain number with default = 100 (optional parameter)
         Note: count 1 is DC component, count 2 is the fundamental frequency
     :type filter_value_harmonic: int
-    :param figure_directory: full path with file extension
-    :type figure_directory: Tuple
-    :param figure_size: None for auto-fit; fig_size for matplotlib (width, length)
+    :param figure_size: None for auto-fit; fig_size for matplotlib (width, length) (optional parameter)
     :type figure_size: Tuple
+    :param figure_directory: full path with file extension  (optional parameter)
+    :type figure_directory: Tuple
 
     :return: numpy-array [[frequency-vector],[amplitude-vector],[phase-vector]]
     :rtype: npt.NDArray[list]

pysignalscope/scope.py

@@ -47,19 +47,20 @@ def generate_channel(time: Union[List[float], np.ndarray], data: Union[List[floa
         Generate a channel object.
 
         :param time: time series
-        :type time: Union[List[float], np.ndarray]
+        :type time: List[float] or np.ndarray
         :param data: channel data
-        :type data: Union[List[float], np.ndarray]
-        :param label: channel label
-        :type label: Optional[str]
-        :param unit: channel unit
-        :type unit: Optional[str]
-        :param color: channel color
-        :type color: Union[str, tuple, None]
-        :param source: channel source
-        :type source: Optional[str]
-        :param linestyle: channel linestyle
-        :type linestyle: Optional[str]
+        :type data: List[float] or np.ndarray
+        :param label: channel label (optional parameter)
+        :type label: str
+        :param unit: channel unit (optional parameter)
+        :type unit: str
+        :param color: channel color (optional parameter)
+        :type color: str or tuple
+        :param source: channel source (optional parameter)
+        :type source: str
+        :param linestyle: channel linestyle (optional parameter) e.g.'-' '--' '-.' ':'
+                          see also https://matplotlib.org/stable/gallery/lines_bars_and_markers/linestyles.html
+        :type linestyle: str
         """
         # check time for a valid type, convert to numpy if necessary
         if isinstance(time, List):
@@ -143,28 +144,29 @@ def modify(channel: Channel, data_factor: Optional[float] = None, data_offset: O
 
         :param channel: Scope channel object
         :type channel: Channel
-        :param data_factor: multiply self.data by data_factor
+        :param data_factor: multiply self.data by data_factor (optional parameter)
         :type data_factor: float
-        :param data_offset: add an offset to self.data
+        :param data_offset: add an offset to self.data (optional parameter)
         :type data_offset: float
-        :param label: label to add to the Channel-class
+        :param label: label to add to the Channel-class (optional parameter)
         :type label: str
-        :param unit: unit to add to the Channel-class
+        :param unit: unit to add to the Channel-class (optional parameter)
         :type unit: str
-        :param color: Color of a channel
-        :type color: str
-        :param source: Source of a channel, e.g. 'GeckoCIRCUITS', 'Numpy', 'Tektronix-Scope', ...
+        :param color: Color of a channel (optional parameter)
+        :type color: str or tuple
+        :param source: Source of a channel, e.g. 'GeckoCIRCUITS', 'Numpy', 'Tektronix-Scope', ... (optional parameter)
         :type source: str
-        :param time_shift: add time to the time base
+        :param time_shift: add time to the time base (optional parameter)
         :type time_shift: float
         :param time_shift_rotate: shifts a signal by the given time, but the end of the signal will
-            come to the beginning of the signal. Only recommended for periodic signals!
+            come to the beginning of the signal. Only recommended for periodic signals! (optional parameter)
         :type time_shift_rotate: float
-        :param time_cut_min: removes all time units smaller than the given one
+        :param time_cut_min: removes all time units smaller than the given one (optional parameter)
         :type time_cut_min: float
-        :param time_cut_max: removes all time units bigger than the given one
+        :param time_cut_max: removes all time units bigger than the given one (optional parameter)
         :type time_cut_max: float
-        :param linestyle: channel linestyle, e.g. '--'
+        :param linestyle: channel linestyle (optional parameter)
+                          for details see parameter description of method 'generate_channel'
         :type linestyle: str
         :return: Channel object
         :rtype: Channel
@@ -548,11 +550,11 @@ def from_numpy(period_vector_t_i: np.ndarray, mode: str = 'rad', f0: Union[float
         :type period_vector_t_i: npt.ArrayLike
         :param mode: 'rad' [default], 'deg' or 'time'
         :type mode: str
-        :param f0: fundamental frequency in Hz
+        :param f0: fundamental frequency in Hz (optional parameter)
         :type f0: float
-        :param label: channel label
+        :param label: channel label (optional parameter)
         :type label: str
-        :param unit: channel unit
+        :param unit: channel unit (optional parameter)
         :type unit: str
 
         :Example:
@@ -595,7 +597,7 @@ def from_geckocircuits(txt_datafile: str, f0: Optional[float] = None) -> List['C
 
         :param txt_datafile: path to text file, generated by geckoCIRCUITS
         :type txt_datafile: str
-        :param f0: fundamental frequency [optional]
+        :param f0: fundamental frequency (optional parameter)
         :type f0: float
         :return: List of Channels
         :rtype: list[Channel]
@@ -652,7 +654,7 @@ def multiply(channel_1: 'Channel', channel_2: 'Channel', label: Optional[str] =
         :type channel_1: Channel
         :param channel_2: channel_2, e.g. current channel
         :type channel_2: Channel
-        :param label: label for new dataset_channel
+        :param label: label for new dataset_channel (optional parameter)
         :type label: str
         :return: Multiplication of two datasets, e.g. power from voltage and current
         :rtype: Channel
@@ -677,7 +679,7 @@ def multiply(channel_1: 'Channel', channel_2: 'Channel', label: Optional[str] =
         return channel_power
 
     @staticmethod
-    def integrate(channel: 'Channel', label: Optional[str] = None):
+    def integrate(channel: 'Channel', label: Optional[str] = None) -> 'Channel':
         """
         Integrate a channels signal.
 
@@ -686,8 +688,8 @@ def integrate(channel: 'Channel', label: Optional[str] = None):
 
         :param channel: channel with power
         :type channel: Channel
-        :param label: channel label
-        :type label: Optional[str]
+        :param label: channel label (optional parameter)
+        :type label: str
         :return: returns a Channel-class, what integrates the input values
         :rtype: Channel
         """
@@ -823,9 +825,9 @@ def plot_channels(*channel: List['Channel'], timebase: str = 's', figure_size: O
         :type channel: list[Channel]
         :param timebase: timebase, can be 's', 'ms', 'us', 'ns' or 'ps'
         :type timebase: str
-        :param figure_size: None for auto-fit; fig_size for matplotlib (width, length in mm)
+        :param figure_size: None for auto-fit; fig_size for matplotlib (width, length in mm) (optional parameter)
         :type figure_size: Tuple
-        :param figure_directory: full path with file extension
+        :param figure_directory: full path with file extension (optional parameter)
         :type figure_directory: str
 
         :return: Plots
@@ -1237,14 +1239,21 @@ def unify_sampling_rate(*channel_datasets: 'Channel', sample_calc_mode: str, sam
 
         :param channel_datasets: dataset according to Channel
         :type channel_datasets: Channel
-        :param sample_calc_mode: keyword, which define the sampling rate calculation 'avg', 'max', 'min' 'user'
+        :param sample_calc_mode: keyword, which define the sampling rate calculation
+                                 possible keywords are 'avg', 'max', 'min' 'user'
         :type sample_calc_mode: str
-        :param sampling_rate: sampling rate defined by the user (only valid, if sample_calc_mode is set to 'user'
-        :type sampling_rate: Optional[float]
-        :param shift: shift of the sample rate from origin. None corresponds to a shift to first time point of first channel
-        :type shift: Optional[float]
-        :param mastermode: Indicate, if only the first data set or all data sets are used for sampling rate calculation
+        :param sampling_rate: sampling rate defined by the user (optional parameter)
+                              only valid, if sample_calc_mode is set to 'user'
+        :type sampling_rate: float
+        :param shift: shift of the sample rate from origin (optional parameter)
+                      None corresponds to a shift to first time point of first channel
+        :type shift: float
+        :param mastermode: Indicates the channels, which are used for sampling rate calculation (optional parameter)
+                           True (default): Only the first channel is used for sampling rate calculation
+                           False: All channels are used for sampling rate calculation
         :type mastermode: bool
+        :return: List of channels
+        :rtype: list['Channel']
 
         If the mastermode is 'True' (default), only the first data set is used for  sampling rate calculation.
         This parameter is ignored, if the sample_calc_mode approach is set to 'user'
@@ -1423,12 +1432,12 @@ def compare_channels(*channels: 'Channel', shift: Optional[List[Union[None, floa
 
         :param channels: dataset according to Channel
         :type channels: Channel
-        :param shift: phase shift in a list for every input dataset
-        :type shift: list[Union[None, float]]
-        :param scale: channel scale factor in a list for every input dataset
-        :type scale: list[Union[None, float]]
-        :param offset: channel offset in a list for every input dataset
-        :type offset: list[Union[None, float]]
+        :param shift: phase shift in a list for every input dataset (optional parameter)
+        :type shift: list[float]
+        :param scale: channel scale factor in a list for every input dataset (optional parameter)
+        :type scale: list[float]
+        :param offset: channel offset in a list for every input dataset (optional parameter)
+        :type offset: list[float]
         :param timebase: timebase, can be 's', 'ms', 'us', 'ns' or 'ps'
         :type timebase: str
         """
@@ -1487,7 +1496,7 @@ def fft(channel: Channel, plot: bool = True):
 
         :param channel: Scope channel object
         :type channel: Channel
-        :param plot: True to show a figure
+        :param plot: True (default) to show a figure  (optional parameter)
         :type plot: bool
         :return: numpy-array [[frequency-vector],[amplitude-vector],[phase-vector]]
         :rtype: npt.NDArray[list]
@@ -1515,11 +1524,11 @@ def short_to_period(channel: Channel, f0: Union[float, int, None] = None, time_p
 
         :param channel: Scope channel object
         :type channel: Channel
-        :param f0: frequency in Hz
+        :param f0: frequency in Hz (optional parameter)
         :type f0: float
-        :param time_period: time period in seconds
+        :param time_period: time period in seconds (optional parameter)
         :type time_period: float
-        :param start_time: start time in seconds
+        :param start_time: start time in seconds (optional parameter)
         :type start_time: float
         """
         if not isinstance(f0, (float, int)) != f0 is not None:
@@ -1554,9 +1563,10 @@ def low_pass_filter(channel: Channel, order: int = 1, angular_frequency_rad: flo
 
         :param channel: Channel object
         :type channel: Channel
-        :param order: filter order
+        :param order: filter order with default = 1  (optional parameter)
         :type order: int
-        :param angular_frequency_rad: angular frequency in rad. Valid for values 0...1. Smaller value means lower filter frequency.
+        :param angular_frequency_rad: angular frequency in rad. Valid for values 0...1. (optional parameter)
+                                      with default = 0.05. Smaller value means lower filter frequency.
         :type angular_frequency_rad: float
         :return: Channel object with filtered data
         :rtype: Channel
@@ -1596,7 +1606,8 @@ def derivative(channel: Channel, order: int = 1) -> Channel:
 
         :param channel: Channel object
         :type channel: Channel
-        :param order: oder of derivative, e.g. 1st order, ...
+        :param order: order of derivative with default = 1  (optional parameter)
+                      1 corresponds to 1st order
         :type order: int
         :return: Channel object
         :rtype: Channel