Update setup & documentation

fourMs · Aug 30, 2022 · 65e8b53 · 65e8b53
1 parent 2f5daeb
commit 65e8b53
Show file tree

Hide file tree

Showing 8 changed files with 96 additions and 44 deletions.
diff --git a/.github/workflows/github-actions.yml b/.github/workflows/github-actions.yml
diff --git a/docs/MODULES.md b/docs/MODULES.md
@@ -27,6 +27,7 @@ Full list of [Mgt-python](README.md#mgt-python) project modules.
     - [Pose](musicalgestures/_pose.md#pose)
     - [Show](musicalgestures/_show.md#show)
     - [Show Window](musicalgestures/_show_window.md#show-window)
+    - [Ssm](musicalgestures/_ssm.md#ssm)
     - [Utils](musicalgestures/_utils.md#utils)
     - [Videoadjust](musicalgestures/_videoadjust.md#videoadjust)
     - [Videograms](musicalgestures/_videograms.md#videograms)

diff --git a/docs/musicalgestures/_motionvideo.md b/docs/musicalgestures/_motionvideo.md
@@ -13,7 +13,7 @@
 
 ## mg_motion
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L272)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L273)
 
 ```python
 def mg_motion(
@@ -109,7 +109,7 @@ Shortcut for [mg_motion](#mg_motion) to only render motion data.
 
 ## mg_motiongrams
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L17)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L16)
 
 ```python
 def mg_motiongrams(
@@ -173,6 +173,7 @@ Shortcut for [mg_motion](#mg_motion) to only render motion plots.
 - `thresh` *float, optional* - Eliminates pixel values less than given threshold. Ranges from 0 to 1. Defaults to 0.05.
 - `blur` *str, optional* - 'Average' to apply a 10px * 10px blurring filter, 'None' otherwise. Defaults to 'None'.
 - `kernel_size` *int, optional* - Size of structuring element. Defaults to 5.
+- `audio_descriptors` *bool, optional* - Whether to plot motion plots together with audio descriptors in order to see possible correlations in the data. Deflauts to False.
 - `unit` *str, optional* - Unit in QoM plot. Accepted values are 'seconds' or 'samples'. Defaults to 'seconds'.
 - `title` *str, optional* - Optionally add title to the plot. Defaults to None, which uses the file name as a title.
 - `target_name` *str, optional* - Target output name for the plot. Defaults to None (which assumes that the input filename with the suffix "_motion_com_aom_qom" should be used).
@@ -184,7 +185,7 @@ Shortcut for [mg_motion](#mg_motion) to only render motion plots.
 
 ## mg_motionvideo
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L212)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L213)
 
 ```python
 def mg_motionvideo(
@@ -242,7 +243,7 @@ Helper function to plot the centroid and quantity of motion using matplotlib.
 
 ## save_txt
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L675)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_motionvideo.py#L707)
 
 ```python
 def save_txt(

diff --git a/docs/musicalgestures/_show.md b/docs/musicalgestures/_show.md
@@ -35,7 +35,7 @@ General method to show an image or video file either in a window, or inline in a
 
 ## show_in_new_process
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_show.py#L262)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_show.py#L274)
 
 ```python
 def show_in_new_process(command):

diff --git a/docs/musicalgestures/_ssm.md b/docs/musicalgestures/_ssm.md
@@ -0,0 +1,81 @@
+# Ssm
+
+> Auto-generated documentation for [musicalgestures._ssm](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_ssm.py) module.
+
+- [Mgt-python](../README.md#mgt-python) / [Modules](../MODULES.md#mgt-python-modules) / [Musicalgestures](index.md#musicalgestures) / Ssm
+    - [mg_ssm](#mg_ssm)
+    - [smooth_downsample_feature_sequence](#smooth_downsample_feature_sequence)
+
+## mg_ssm
+
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_ssm.py#L43)
+
+```python
+def mg_ssm(
+    self,
+    features='motiongrams',
+    filtertype='Regular',
+    thresh=0.05,
+    blur='None',
+    norm=np.inf,
+    threshold=0.001,
+    cmap='gray_r',
+    use_median=False,
+    kernel_size=5,
+    target_name=None,
+    overwrite=False,
+):
+```
+
+Compute Self-Similarity Matrix (SSM) by converting the input signal into a suitable feature sequence and comparing each element of the feature sequence with all other elements of the sequence.
+SSMs can be computed over different input features such as 'motiongrams', 'spectrogram', 'chromagram' and 'tempogram'.
+
+#### Arguments
+
+- `features` *str, optional* - Defines the type of features on which to compute SSM. Possible to compute SSM on 'motiongrams', 'spectrogram', 'chromagram' and 'tempogram'. Defaults to 'motiongrams'.
+- `filtertype` *str, optional* - 'Regular' turns all values below `thresh` to 0. 'Binary' turns all values below `thresh` to 0, above `thresh` to 1. 'Blob' removes individual pixels with erosion method. Defaults to 'Regular'.
+- `thresh` *float, optional* - Eliminates pixel values less than given threshold. Ranges from 0 to 1. Defaults to 0.05.
+- `blur` *str, optional* - 'Average' to apply a 10px * 10px blurring filter, 'None' otherwise. Defaults to 'None'.
+- `norm` *int, optional* - Normalize the columns of the feature sequence. Possible to compute Manhattan norm (1), Euclidean norm (2), Minimum norm (-np.inf), Maximum norm (np.inf), etc. Defaults to np.inf.
+- `threshold` *float, optional* - Only the columns with norm at least the amount of `threshold` indicated are normalized. Defaults to 0.001.
+- `cmap` *str, optional* - A Colormap instance or registered colormap name. The colormap maps the C values to colors. Defaults to 'gray_r'.
+- `use_median` *bool, optional* - If True the algorithm applies a median filter on the thresholded frame-difference stream. Defaults to False.
+- `kernel_size` *int, optional* - Size of the median filter (if `use_median=True`) or the erosion filter (if `filtertype='blob'`). Defaults to 5.
+- `target_name` *[type], optional* - Target output name for the SSM. Defaults to None.
+- `overwrite` *bool, optional* - Whether to allow overwriting existing files or to automatically increment target filenames to avoid overwriting. Defaults to False.
+
+#### Returns
+
+# if features='motiongrams':
+- `MgList` - An MgList pointing to the output SSM images (as MgImages).
+# else:
+- `MgImage` - An MgImage to the output SSM.
+
+## smooth_downsample_feature_sequence
+
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_ssm.py#L16)
+
+```python
+def smooth_downsample_feature_sequence(
+    X,
+    sr,
+    filt_len=41,
+    down_sampling=10,
+    w_type='boxcar',
+):
+```
+
+Smoothes and downsamples a feature sequence. Smoothing is achieved by convolution with a filter kernel
+
+#### Arguments
+
+- `X` *np.ndarray* - Feature sequence.
+- `sr` *int* - Sampling rate.
+- `filt_len` *int, optional* - Length of smoothing filter. Defaults to 41.
+- `down_sampling` *int, optional* - Downsampling factor. Defaults to 10.
+- `w_type` *str, optional* - Window type of smoothing filter. Defaults to 'boxcar'.
+
+#### Returns
+
+- `X_smooth` *np.ndarray* - Smoothed and downsampled feature sequence.
+- `sr_feature` *scalar* - Sampling rate of `X_smooth`.
diff --git a/docs/musicalgestures/_videoadjust.md b/docs/musicalgestures/_videoadjust.md
@@ -37,7 +37,7 @@ Applies contrast and brightness adjustments on the source video using ffmpeg.
 
 ## fixed_frames_ffmpeg
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_videoadjust.py#L98)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/_videoadjust.py#L99)
 
 ```python
 def fixed_frames_ffmpeg(

diff --git a/docs/musicalgestures/index.md b/docs/musicalgestures/index.md
@@ -30,6 +30,7 @@
         - [Pose](_pose.md#pose)
         - [Show](_show.md#show)
         - [Show Window](_show_window.md#show-window)
+        - [Ssm](_ssm.md#ssm)
         - [Utils](_utils.md#utils)
         - [Videoadjust](_videoadjust.md#videoadjust)
         - [Videograms](_videograms.md#videograms)
@@ -39,7 +40,7 @@
 
 ## Examples
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L147)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L148)
 
 ```python
 class Examples():
@@ -84,7 +85,7 @@ These preprocesses will apply upon creating the MgVideo. Further processes are a
 
 ### MgVideo().get_video
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L124)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L125)
 
 ```python
 def get_video():
@@ -94,7 +95,7 @@ Creates a video attribute to the Musical Gestures object with the given correct
 
 ### MgVideo().info
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L112)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L113)
 
 ```python
 def info(type='video'):
@@ -104,7 +105,7 @@ Retrieves the information related to video, audio and format.
 
 ### MgVideo().test_input
 
-[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L108)
+[[find in source code]](https://github.com/fourMs/MGT-python/blob/master/musicalgestures/__init__.py#L109)
 
 ```python
 def test_input():

diff --git a/setup.py b/setup.py
@@ -12,7 +12,7 @@
 setup(
     name='musicalgestures',
     packages=['musicalgestures'],
-    version='v1.2.3',
+    version='v1.2.4',
     license='GNU General Public License v3 (GPLv3)',
     description='Musical Gestures Toolbox for Python',
     long_description=README,
@@ -23,7 +23,7 @@
     author='University of Oslo fourMs Lab',
     author_email='[email protected]',
     url='https://github.com/fourMs/MGT-python',
-    download_url='https://github.com/fourMs/MGT-python/archive/v1.2.3.tar.gz',
+    download_url='https://github.com/fourMs/MGT-python/archive/v1.2.4.tar.gz',
     keywords=['Computer Vision', 'Motion Analysis',
               'Musical Gestures', 'Video-Analysis'],
     install_requires=[