maialib 1.9.3__cp38-cp38-musllinux_1_2_x86_64.whl → 1.9.5__cp38-cp38-musllinux_1_2_x86_64.whl

maialib/maiacore/maiacore.pyi

@@ -93,7 +93,7 @@ class Chord:
     @typing.overload
     def getHarmonicDensity(self, lowerBoundPitch: str = '', higherBoundPitch: str = '') -> float:
         ...
-    def getHarmonicSpectrum(self, numPartialsPerNote: int = 6, amplCallback: typing.Callable[[list[float]], list[float]] = None) -> tuple[list[float], list[float]]:
+    def getHarmonicSpectrum(self, numPartialsPerNote: int = 6, amplCallback: typing.Callable[[list[float]], list[float]] = None, partialsDecayExpRate: float = 0.8799999952316284) -> tuple[list[float], list[float]]:
         ...
     def getIntervals(self, firstNoteAsReference: bool = False) -> list[Interval]:
         ...
@@ -139,9 +139,9 @@ class Chord:
         ...
     def getRoot(self) -> Note:
         ...
-    def getSetharesDissonance(self, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: typing.Callable[[list[float]], list[float]] = None, dissCallback: typing.Callable[[list[float]], float] = None) -> float:
+    def getSetharesDissonance(self, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: typing.Callable[[list[float]], list[float]] = None, partialsDecayExpRate: float = 0.8799999952316284, dissCallback: typing.Callable[[list[float]], float] = None) -> float:
         ...
-    def getSetharesDyadsDataFrame(self, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: typing.Callable[[list[float]], list[float]] = None) -> typing.Any:
+    def getSetharesDyadsDataFrame(self, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: typing.Callable[[list[float]], list[float]] = None, partialsDecayExpRate: float = 0.8799999952316284) -> typing.Any:
         ...
     def getStackDataFrame(self, enharmonyNotes: bool = False) -> typing.Any:
         ...
@@ -946,7 +946,7 @@ class Note:
         ...
     def getFrequency(self, equalTemperament: bool = True, freqA4: float = 440.0) -> float:
         ...
-    def getHarmonicSpectrum(self, numPartials: int = 6, amplCallback: typing.Callable[[list[float]], list[float]] = None) -> tuple[list[float], list[float]]:
+    def getHarmonicSpectrum(self, numPartials: int = 6, amplCallback: typing.Callable[[list[float]], list[float]] = None, partialsDecayExpRate: float = 0.8799999952316284) -> tuple[list[float], list[float]]:
         ...
     def getLongType(self) -> str:
         ...
@@ -1411,4 +1411,4 @@ C: ClefSign  # value = <ClefSign.C: 2>
 F: ClefSign  # value = <ClefSign.F: 1>
 G: ClefSign  # value = <ClefSign.G: 0>
 P: ClefSign  # value = <ClefSign.P: 3>
-__version__: str = '"1.9.3"'
+__version__: str = '"1.9.5"'

maialib/maiapy/sethares_dissonance.py

@@ -67,16 +67,69 @@ def _dissmeasure(fvec: List[float], amp: List[float], model: str = 'min') -> flo
     return D, fr_pairs, am_pairs
 
 
-def plotSetharesDissonanceCurve(fundamentalFreq: float = 440, numPartials: int = 6, ratioLowLimit: float = 1.0, ratioHighLimit: float = 2.3, ratioStepIncrement: float = 0.001, amplCallback: Optional[Callable[[List[float]], List[float]]] = None) -> Tuple[go.Figure, pd.DataFrame]:
+def plotSetharesDissonanceCurve(fundamentalFreq: float = 440, numPartials: int = 6, ratioLowLimit: float = 1.0, ratioHighLimit: float = 2.3, ratioStepIncrement: float = 0.001, amplCallback: Optional[Callable[[List[float]], List[float]]] = None, partialsDecayExpRate: float = 0.88) -> Tuple[go.Figure, pd.DataFrame]:
     """
-    Compute the Sethares Dissonance Curve of a given base frequency
-
-    Return
-        A tuple that contains a Plotly figure, and the pair 'ratios' and 'dissonance' lists
+    Generate and return the sensory dissonance curve (Sethares) for a harmonic spectrum.
+
+    Parameters
+    ----------
+    fundamentalFreq : float, default=440
+        Base frequency (f₀) in Hz on which the partials are built.
+
+    numPartials : int, default=6
+        Number of harmonics (partials) to include.
+
+    ratioLowLimit : float, default=1.0
+        Lower bound of the frequency ratio axis (intervals).
+
+    ratioHighLimit : float, default=2.3
+        Upper bound of the frequency ratio axis.
+
+    ratioStepIncrement : float, default=0.001
+        Step size between successive frequency ratios in the dissonance curve.
+
+    amplCallback : Optional[Callable[[List[float]], List[float]]], default=None
+        Optional function that receives a list of partial frequencies and returns
+        corresponding amplitudes. If None, amplitudes decay exponentially by
+        `partialsDecayExpRate`.
+
+    partialsDecayExpRate : float, default=0.88
+        Exponential decay rate for harmonics when `amplCallback` is None:
+        amplitude_i = (partialsDecayExpRate)**i.
+
+    Returns
+    -------
+    fig : go.Figure
+        Plotly figure of the sensory dissonance curve with a log-scaled frequency ratio
+        axis. Includes vertical lines for musically notable intervals (e.g., 3/2, 5/4).
+
+    df : pandas.DataFrame
+        DataFrame with columns:
+            - 'ratio': frequency ratio values
+            - 'dissonance': sensory dissonance computed for each ratio
+            - 'freqs': frequency pair vectors used for calculation
+            - 'amps': amplitude pair vectors used in calculation
+
+    Behavior
+    --------
+    1. Constructs frequency vector `freqs` with integer multiples of `fundamentalFreq`.
+    2. Computes amplitude vector `amps` via `amplCallback`, or using exponential decay.
+    3. Validates matching lengths for `freqs` and `amps`, raising ValueError if mismatched.
+    4. Constructs a `ratios` array from `ratioLowLimit` to `ratioHighLimit`.
+    5. For each ratio r:
+       - Concatenates `freqs` with r × `freqs`; likewise for amplitudes.
+       - Applies `_dissmeasure` to compute sensory dissonance, frequency pairs, and amplitude pairs.
+    6. Builds a Plotly figure plotting dissonance vs. ratio and overlays lines at common musical intervals.
+    7. Returns the figure and a pandas DataFrame for further analysis.
+
+    Exceptions
+    ----------
+    ValueError:
+        Raised if the output of `amplCallback` (if provided) does not match `numPartials` in length.
     """
     freqs = fundamentalFreq * np.array(list(range(1, numPartials+1)))
-    amps = 0.88**np.array(list(range(0, numPartials))
-                          ) if amplCallback == None else amplCallback(freqs)
+    amps = partialsDecayExpRate**np.array(list(range(0, numPartials))
+                                          ) if amplCallback == None else amplCallback(freqs)
 
     if len(freqs) != len(amps):
         raise ValueError(
@@ -190,6 +243,7 @@ def _setharesDissonanceDataFrameInterpolation(df: pd.DataFrame, interpolatePoint
 
 
 def plotScoreSetharesDissonance(score: mc.Score, plotType='line', lineShape='linear', numPartialsPerNote: int = 6, useMinModel: bool = True,
+                                partialsDecayExpRate: float = 0.88,
                                 amplCallback: Optional[Callable[[
                                     List[float]], List[float]]] = None,
                                 dissCallback: Optional[Callable[[List[float]], float]] = None, **kwargs) -> Tuple[go.Figure, pd.DataFrame]:
@@ -202,6 +256,7 @@ def plotScoreSetharesDissonance(score: mc.Score, plotType='line', lineShape='lin
        numPartialsPerNote (int): Amount of spectral partials for each note
        useMinModel (bool): Sethares dissonance values can be computed using the 'minimal amplitude' model
                     or the 'product amplitudes' model. The 'min' model is a more recent approach
+       partialsDecayExpRate (float): Partials decay exponential rate (default: 0.88)
        amplCallback: Custom user function callback to generate the amplitude of each spectrum partial
        dissCallback: Custom user function callback to receive all paired partial dissonances and computes 
                      a single total dissonance value output
@@ -233,7 +288,7 @@ def plotScoreSetharesDissonance(score: mc.Score, plotType='line', lineShape='lin
     df = score.getChordsDataFrame(kwargs)
 
     df["dissonance"] = df.apply(lambda row: row.chord.getSetharesDissonance(
-        numPartialsPerNote, useMinModel, amplCallback, dissCallback), axis=1)
+        numPartialsPerNote, useMinModel, amplCallback, partialsDecayExpRate, dissCallback), axis=1)
     df["chordNotes"] = df.apply(lambda row: ', '.join(
         [str(x.getPitch()) for x in row.chord.getNotes()]), axis=1)
     df["chordSize"] = df.apply(lambda row: row.chord.size(), axis=1)
@@ -282,7 +337,8 @@ def plotScoreSetharesDissonance(score: mc.Score, plotType='line', lineShape='lin
 
 
 def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: Optional[Callable[[
-        List[float]], List[float]]] = None, dissonanceThreshold: float = 0.1, dissonanceDecimalPoint: int = 2) -> Tuple[plotly.graph_objs._figure.Figure, pd.DataFrame]:
+    List[float]], List[float]]] = None, partialsDecayExpRate: float = 0.88, dissonanceThreshold: float = 0.1, dissonanceDecimalPoint: int = 2, showValues: bool = False,
+        valuesDecimalPlaces: int = 2) -> Tuple[plotly.graph_objs._figure.Figure, pd.DataFrame]:
     """Plot chord dyads Sethares dissonance heatmap
 
     Args:
@@ -293,8 +349,11 @@ def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote:
        useMinModel (bool): Sethares dissonance values can be computed using the 'minimal amplitude' model
                     or the 'product amplitudes' model. The 'min' model is a more recent approach
        amplCallback: Custom user function callback to generate the amplitude of each spectrum partial
+       partialsDecayExpRate (float): Partials decay exponential rate (default: 0.88)
        dissonanceThreshold (float): Dissonance threshold to skip small dissonance values
        dissonanceDecimalPoint (int): Round chord dissonance value in the plot title
+       showValues (bool): If True, show numerical values inside heatmap cells
+       valuesDecimalPlaces (int): Number of decimal places to display in cell values
 
     Returns:
        A list: [Plotly Figure, The plot data as a Pandas Dataframe]
@@ -310,33 +369,64 @@ def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote:
     >>> fig.show()
     """
     df = chord.getSetharesDyadsDataFrame(
-        numPartialsPerNote=numPartialsPerNote, useMinModel=useMinModel, amplCallback=amplCallback)
+        numPartialsPerNote=numPartialsPerNote, useMinModel=useMinModel, amplCallback=amplCallback, partialsDecayExpRate=partialsDecayExpRate)
     dfFiltered = df[df.dissonance > dissonanceThreshold]
 
-    # Pivot the dataframe to create a matrix with baseFreq on X and targetFreq on Y
+    # Pivot para matriz (targetFreq como linhas, baseFreq como colunas)
     matrix_df = dfFiltered.pivot(
-        index='targetFreq', columns='baseFreq', values='dissonance')
+        index='targetFreq', columns='baseFreq', values='dissonance'
+    )
+
+    # Reordena linhas e colunas para consistência
+    matrix_df = matrix_df.reindex(
+        index=sorted(matrix_df.index),
+        columns=sorted(matrix_df.columns)
+    )
+
+    # Índices para o heatmap uniforme
+    x_ticks = list(range(len(matrix_df.columns)))
+    y_ticks = list(range(len(matrix_df.index)))
 
-    # Create a heatmap using Plotly
-    fig = px.imshow(matrix_df,
-                    labels=dict(x="Base Frequency (Hz)",
-                                y="Target Frequency (Hz)", color="Dissonance"),
-                    color_continuous_scale='Inferno')
+    # Labels reais (frequências)
+    x_labels = [round(v, 0) for v in matrix_df.columns]
+    y_labels = [round(v, 0) for v in matrix_df.index]
 
-    # Extract unique frequencies for x and y ticks
-    x_ticks = sorted(matrix_df.columns.unique())  # baseFreq
-    y_ticks = sorted(matrix_df.index.unique())    # targetFreq
+    # Formatação do texto (caso showValues=True)
+    if showValues:
+        text_format = f".{valuesDecimalPlaces}f"
+    else:
+        text_format = False
+
+    # Criar heatmap com quadrados iguais
+    fig = px.imshow(
+        matrix_df.values,
+        labels=dict(x="Base Frequency (Hz)",
+                    y="Target Frequency (Hz)", color="Dissonance"),
+        color_continuous_scale="Inferno",
+        origin="lower",   # força o eixo Y a começar por baixo
+        text_auto=text_format
+    )
 
-    roundedXTicksValues = [round(num, 0) for num in x_ticks]
-    roundedYTicksValues = [round(num, 0) for num in y_ticks]
+    # Ajusta ticks para mostrar frequências reais
+    fig.update_xaxes(
+        tickmode="array",
+        tickvals=x_ticks,
+        ticktext=x_labels
+    )
+    fig.update_yaxes(
+        tickmode="array",
+        tickvals=y_ticks,
+        ticktext=y_labels,
+    )
 
-    fig.update_xaxes(type='linear', tickvals=x_ticks,
-                     ticktext=roundedXTicksValues)
-    fig.update_yaxes(type='linear', tickvals=y_ticks,
-                     ticktext=roundedYTicksValues, autorange=True)
+    # Mantém os quadrados sempre iguais
+    fig.update_yaxes(scaleanchor="x", scaleratio=1)
 
+    # Título
     roundedDissonanceValue = round(df.dissonance.sum(), dissonanceDecimalPoint)
     fig.update_layout(
-        title=f'<b>Chord Dyads Sethares Dissonance Heatmap</b><br><i>Chord Dissonance={str(roundedDissonanceValue)}</i>', title_x=0.5)
+        title=f'<b>Chord Dyads Sethares Dissonance Heatmap</b><br><i>Chord Dissonance={roundedDissonanceValue}</i>',
+        title_x=0.5
+    )
 
     return fig, dfFiltered

maialib/maiapy/sethares_dissonance.pyi

@@ -4,14 +4,67 @@ import plotly.graph_objects as go
 from maialib import maiacore as mc
 from typing import Callable
 
-def plotSetharesDissonanceCurve(fundamentalFreq: float = 440, numPartials: int = 6, ratioLowLimit: float = 1.0, ratioHighLimit: float = 2.3, ratioStepIncrement: float = 0.001, amplCallback: Callable[[list[float]], list[float]] | None = None) -> tuple[go.Figure, pd.DataFrame]:
+def plotSetharesDissonanceCurve(fundamentalFreq: float = 440, numPartials: int = 6, ratioLowLimit: float = 1.0, ratioHighLimit: float = 2.3, ratioStepIncrement: float = 0.001, amplCallback: Callable[[list[float]], list[float]] | None = None, partialsDecayExpRate: float = 0.88) -> tuple[go.Figure, pd.DataFrame]:
     """
-    Compute the Sethares Dissonance Curve of a given base frequency
+    Generate and return the sensory dissonance curve (Sethares) for a harmonic spectrum.
 
-    Return
-        A tuple that contains a Plotly figure, and the pair 'ratios' and 'dissonance' lists
+    Parameters
+    ----------
+    fundamentalFreq : float, default=440
+        Base frequency (f₀) in Hz on which the partials are built.
+
+    numPartials : int, default=6
+        Number of harmonics (partials) to include.
+
+    ratioLowLimit : float, default=1.0
+        Lower bound of the frequency ratio axis (intervals).
+
+    ratioHighLimit : float, default=2.3
+        Upper bound of the frequency ratio axis.
+
+    ratioStepIncrement : float, default=0.001
+        Step size between successive frequency ratios in the dissonance curve.
+
+    amplCallback : Optional[Callable[[List[float]], List[float]]], default=None
+        Optional function that receives a list of partial frequencies and returns
+        corresponding amplitudes. If None, amplitudes decay exponentially by
+        `partialsDecayExpRate`.
+
+    partialsDecayExpRate : float, default=0.88
+        Exponential decay rate for harmonics when `amplCallback` is None:
+        amplitude_i = (partialsDecayExpRate)**i.
+
+    Returns
+    -------
+    fig : go.Figure
+        Plotly figure of the sensory dissonance curve with a log-scaled frequency ratio
+        axis. Includes vertical lines for musically notable intervals (e.g., 3/2, 5/4).
+
+    df : pandas.DataFrame
+        DataFrame with columns:
+            - 'ratio': frequency ratio values
+            - 'dissonance': sensory dissonance computed for each ratio
+            - 'freqs': frequency pair vectors used for calculation
+            - 'amps': amplitude pair vectors used in calculation
+
+    Behavior
+    --------
+    1. Constructs frequency vector `freqs` with integer multiples of `fundamentalFreq`.
+    2. Computes amplitude vector `amps` via `amplCallback`, or using exponential decay.
+    3. Validates matching lengths for `freqs` and `amps`, raising ValueError if mismatched.
+    4. Constructs a `ratios` array from `ratioLowLimit` to `ratioHighLimit`.
+    5. For each ratio r:
+       - Concatenates `freqs` with r × `freqs`; likewise for amplitudes.
+       - Applies `_dissmeasure` to compute sensory dissonance, frequency pairs, and amplitude pairs.
+    6. Builds a Plotly figure plotting dissonance vs. ratio and overlays lines at common musical intervals.
+    7. Returns the figure and a pandas DataFrame for further analysis.
+
+    Exceptions
+    ----------
+    ValueError:
+        Raised if the output of `amplCallback` (if provided) does not match `numPartials` in length.
     """
-def plotScoreSetharesDissonance(score: mc.Score, plotType: str = 'line', lineShape: str = 'linear', numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: Callable[[list[float]], list[float]] | None = None, dissCallback: Callable[[list[float]], float] | None = None, **kwargs) -> tuple[go.Figure, pd.DataFrame]:
+def plotScoreSetharesDissonance(score: mc.Score, plotType: str = 'line', lineShape: str = 'linear', numPartialsPerNote: int = 6, useMinModel: bool = True, partialsDecayExpRate: float = 0.88, amplCallback: Callable[[list[float]], list[float]] | None = None, dissCallback: Callable[[list[float]], float] | None = None, **kwargs) -> tuple[go.Figure, pd.DataFrame]:
     '''Plot 2D line graph of the Sethares Dissonance over time
 
     Args:
@@ -21,6 +74,7 @@ def plotScoreSetharesDissonance(score: mc.Score, plotType: str = 'line', lineSha
        numPartialsPerNote (int): Amount of spectral partials for each note
        useMinModel (bool): Sethares dissonance values can be computed using the \'minimal amplitude\' model
                     or the \'product amplitudes\' model. The \'min\' model is a more recent approach
+       partialsDecayExpRate (float): Partials decay exponential rate (default: 0.88)
        amplCallback: Custom user function callback to generate the amplitude of each spectrum partial
        dissCallback: Custom user function callback to receive all paired partial dissonances and computes 
                      a single total dissonance value output
@@ -42,7 +96,7 @@ def plotScoreSetharesDissonance(score: mc.Score, plotType: str = 'line', lineSha
     >>> ml.plotScoreSetharesDissonance(myScore, numPoints=15)
     >>> ml.plotScoreSetharesDissonance(myScore, measureStart=10, measureEnd=20)
     '''
-def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: Callable[[list[float]], list[float]] | None = None, dissonanceThreshold: float = 0.1, dissonanceDecimalPoint: int = 2) -> tuple[plotly.graph_objs._figure.Figure, pd.DataFrame]:
+def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote: int = 6, useMinModel: bool = True, amplCallback: Callable[[list[float]], list[float]] | None = None, partialsDecayExpRate: float = 0.88, dissonanceThreshold: float = 0.1, dissonanceDecimalPoint: int = 2, showValues: bool = False, valuesDecimalPlaces: int = 2) -> tuple[plotly.graph_objs._figure.Figure, pd.DataFrame]:
     '''Plot chord dyads Sethares dissonance heatmap
 
     Args:
@@ -53,8 +107,11 @@ def plotChordDyadsSetharesDissonanceHeatmap(chord: mc.Chord, numPartialsPerNote:
        useMinModel (bool): Sethares dissonance values can be computed using the \'minimal amplitude\' model
                     or the \'product amplitudes\' model. The \'min\' model is a more recent approach
        amplCallback: Custom user function callback to generate the amplitude of each spectrum partial
+       partialsDecayExpRate (float): Partials decay exponential rate (default: 0.88)
        dissonanceThreshold (float): Dissonance threshold to skip small dissonance values
        dissonanceDecimalPoint (int): Round chord dissonance value in the plot title
+       showValues (bool): If True, show numerical values inside heatmap cells
+       valuesDecimalPlaces (int): Number of decimal places to display in cell values
 
     Returns:
        A list: [Plotly Figure, The plot data as a Pandas Dataframe]