API Reference

This section is generated from the docstrings in the TOVIS toolbox code.

Feature

Feature extraction utilities for TOVIS.

tovis.feature.compute_chromagram(audio, sample_rate=22050, *, backend='CQT', window_length=4096, hop_length=2048, estimate_tuning=False, gamma=None, start_time=None, end_time=None, transcription_checkpoint=None, transcription_device='cpu', smoothing_length_seconds=None, output_feature_rate=None, smoothing_window_type='boxcar', norm='2', norm_threshold=0.001)[source]

Compute a 12-bin chromagram from a mono audio signal.

Parameters:

  • audio (ndarray) – Mono audio signal.

  • sample_rate (int) – Audio sample rate in Hz.

  • backend (str) – Chroma backend. Options are "STFT", "CQT", "IIR", "VQT", "ONSETS_AND_FRAMES", and "DEEP_CHROMA".

  • window_length (int) – Analysis window length for STFT and IIR features.

  • hop_length (int) – Hop length in audio samples.

  • estimate_tuning (bool) – If true, estimate global tuning and pass it to the chroma backend.

  • gamma (float | None) – Optional logarithmic compression, applied as log(1 + gamma * X).

  • start_time (float | None) – Optional start time in seconds for all backends.

  • end_time (float | None) – Optional end time in seconds for all backends.

  • transcription_checkpoint (str | Path | None) – Required checkpoint file path for backend="ONSETS_AND_FRAMES" or backend="DEEP_CHROMA". No default location is searched. Unused for other backends.

  • transcription_device (str) – Torch device for transcription.

  • smoothing_length_seconds (float | None) – Optional temporal smoothing-window duration in seconds. The nearest integer number of source feature frames is used; see smooth_resample_feature_sequence().

  • output_feature_rate (float | None) – Optional output frame rate in Hz. The chromagram is linearly interpolated onto a regular grid at exactly this rate; see smooth_resample_feature_sequence().

  • smoothing_window_type (str) – Window type passed to smooth_resample_feature_sequence().

  • norm (str | None) – Optional frame-wise output normalization. Supports "1", "2", "max", and "z"; see normalize_feature_sequence().

  • norm_threshold (float) – Threshold passed to normalize_feature_sequence().

Returns:

Chromagram of shape (12, n_frames) and its frame rate in Hz.

Return type:

chromagram, feature_rate

tovis.feature.compute_chromagram_from_file(filename, sample_rate=22050, *, backend='CQT', window_length=4096, hop_length=2048, estimate_tuning=False, gamma=None, start_time=None, end_time=None, transcription_checkpoint=None, transcription_device='cpu', smoothing_length_seconds=None, output_feature_rate=None, smoothing_window_type='boxcar', norm='2', norm_threshold=0.001)[source]

Load an audio file and compute a chromagram.

Audio is loaded with librosa.load and passed to compute_chromagram. If start_time and/or end_time are given, only that time span is loaded from disk.

Parameters:

  • filename (str | Path) – Path to the audio file.

  • sample_rate (int) – Input sample rate for librosa chroma backends.

  • backend (str) – Chroma backend passed to compute_chromagram.

  • window_length (int) – Analysis window length for STFT and IIR features.

  • hop_length (int) – Hop length in audio samples.

  • estimate_tuning (bool) – If true, estimate global tuning for librosa chroma backends.

  • gamma (float | None) – Optional logarithmic compression factor.

  • start_time (float | None) – Optional start time in seconds.

  • end_time (float | None) – Optional end time in seconds.

  • transcription_checkpoint (str | Path | None) – Required checkpoint file path for backend="ONSETS_AND_FRAMES" or backend="DEEP_CHROMA". No default location is searched. Unused for other backends.

  • transcription_device (str) – Torch device for transcription.

  • smoothing_length_seconds (float | None) – Optional temporal smoothing-window duration in seconds; see smooth_resample_feature_sequence().

  • output_feature_rate (float | None) – Optional output frame rate in Hz; interpolation is performed on a regular time grid at exactly this rate; see smooth_resample_feature_sequence().

  • smoothing_window_type (str) – Window type passed to smooth_resample_feature_sequence().

  • norm (str | None) – Optional frame-wise chroma normalization; see normalize_feature_sequence().

  • norm_threshold (float) – Threshold passed to normalize_feature_sequence().

Returns:

Chromagram of shape (12, n_frames) and its frame rate in Hz.

Return type:

chromagram, feature_rate

tovis.feature.compute_chromagram_from_annotations(note_annotations=None, feature_rate=None, *, filename=None, start_column='start', end_column='end', pitch_column='pitch', start_time=None, end_time=None, smoothing_length_seconds=None, output_feature_rate=None, smoothing_window_type='boxcar', norm='2', norm_threshold=0.001, kwargs_csv_reader=None)[source]

Compute a chromagram from symbolic note annotations.

Parameters:

  • note_annotations (DataFrame | None) – DataFrame containing note events. By default, TOVIS expects columns start, end, and pitch.

  • feature_rate (float | None) – Output frame rate in Hz.

  • filename (str | Path | None) – Optional CSV file to load when note_annotations is not provided. Loaded with read_csv().

  • start_column (str) – Column name for note start time.

  • end_column (str) – Column name for note end time.

  • pitch_column (str) – Column name for MIDI pitch.

  • start_time (float | None) – Optional start time in seconds. If omitted, it is inferred from the annotation.

  • end_time (float | None) – Optional end time in seconds. If omitted, it is inferred from the annotation.

  • smoothing_length_seconds (float | None) – Optional temporal smoothing-window duration in seconds. The nearest integer number of source feature frames is used; see smooth_resample_feature_sequence().

  • output_feature_rate (float | None) – Optional output frame rate in Hz. The chromagram is linearly interpolated onto a regular grid at exactly this rate; see smooth_resample_feature_sequence().

  • smoothing_window_type (str) – Window type passed to smooth_resample_feature_sequence().

  • norm (str | None) – Optional frame-wise chroma normalization; see normalize_feature_sequence().

  • norm_threshold (float) – Threshold passed to normalize_feature_sequence().

  • kwargs_csv_reader (Mapping[str, Any] | None) – Optional keyword arguments passed to read_csv().

Returns:

Chromagram of shape (12, n_frames) and its frame rate in Hz.

Return type:

chromagram, feature_rate

Scale

Scale and local-key analysis utilities for TOVIS.

tovis.scale.get_scale_labels(version='absolute_diatonic', *, global_key='C')[source]

Return labels for the 12 major-scale templates.

Parameters:

  • version (str) – Label set. Options are "absolute_diatonic", which returns circle-of-fifths labels relative to C such as "0", "1b", and "1#"; and "relative_diatonic", which returns signed circle-of-fifths distances relative to global_key such as "0", "+1", and "-1".

  • global_key (str) – Key used as the zero point for version="relative_diatonic". Ignored by version="absolute_diatonic".

Returns:

Twelve labels ordered by chromatic pitch class from C to B.

Return type:

list of str

tovis.scale.get_templates(version='triads_enhanced')[source]

Return a root-position major-scale template.

Parameters:

version (str) – Template weighting scheme. "binary" marks diatonic pitch classes, "triads_enhanced" emphasizes tonic-triad tones, and "krumhansl" uses a perceptual weighting.

Returns:

Column vector of shape (12, 1) for the C major template.

Return type:

numpy.ndarray

tovis.scale.generate_template_matrix(templates)[source]

Generate a template matrix by cyclically shifting 12-bin templates.

Every input template is transposed through all twelve chromatic roots.

Parameters:

templates (ndarray) – Template vector or matrix of shape (12,) or (12, n_templates).

Returns:

Matrix of shape (12, 12 * n_templates). For a single major-scale template, columns correspond to C, Db, D, …, B.

Return type:

template_matrix

tovis.scale.scale_analysis_templates(chromagram, templates=None, *, template_version=None, method='exp_product', apply_output_normalization=True, norm='2', norm_threshold=1e-12, chroma_floor=0.001, apply_softmax_rescaling=False, softmax_eta=1.0)[source]

Estimate scale likelihoods from a chromagram using scale templates.

The chromagram frames and template vectors are L2-normalized before comparison. With method="inner_product", the likelihood is the inner product \(L_k(n)=t_k^\mathsf{T}x_n\). With method="exp_product", it is the exponent-weighted product \(L_k(n)=\prod_p x_n(p)^{t_k(p)}\).

Parameters:

  • chromagram (ndarray) – Chromagram of shape (12, n_frames).

  • templates (ndarray | None) – Template matrix of shape (12, n_templates). Required unless template_version is supplied.

  • template_version (str | None) – Optional built-in template version. Options are "binary", "triads_enhanced", and "krumhansl". If given, a twelve-transposition template matrix is generated internally and templates is ignored.

  • method (str) – Template comparison method. Options are "inner_product" and "exp_product" as defined above.

  • apply_output_normalization (bool) – If true, normalize each output frame.

  • norm (str) – Output frame normalization when apply_output_normalization is true. Options are "1", "2", "max", "z", and None; see normalize_feature_sequence().

  • norm_threshold (float) – Threshold passed to normalize_feature_sequence() for output normalization.

  • chroma_floor (float | None) – Optional minimum chroma value used by the "exp_product" method after input normalization: \(x\leftarrow\max(x,\mathtt{chroma\_floor})\). This prevents hard zeros from collapsing complete likelihood frames.

  • apply_softmax_rescaling (bool) – If true, apply softmax rescaling to the output after optional normalization.

  • softmax_eta (float) – Softmax sharpness parameter \(\eta\) in \(\operatorname{softmax}(\eta L)\).

Returns:

Scale likelihood matrix of shape (n_templates, n_frames).

Return type:

scale_likelihood

tovis.scale.softmax_rescaling(x, *, eta=1.0, axis=0)[source]

Apply numerically stable softmax rescaling.

Computes \(y_i=\exp(\eta x_i)/\sum_j\exp(\eta x_j)\) along axis.

Parameters:

  • x (ndarray) – Input array.

  • eta (float) – Sharpness factor \(\eta\). Larger positive values concentrate mass around larger inputs; 0 produces a uniform distribution.

  • axis (int) – Axis along which the softmax is computed.

Returns:

Softmax-normalized array with the same shape as x.

Return type:

numpy.ndarray

Structure

Structure-analysis utilities based on transposition-invariant SSMs.

tovis.structure.get_ssm_ti(feature_sequence, feature_rate, *, reference_sequence=None, shifts=None, smoothing_length_seconds=None, tempo_deviation=0.0, num_tempo_rel=20, direction='both', norm='2', norm_threshold=0.001, thresh=0.2, threshold_strategy='relative', scale=False, penalty=0.0, min_similarity_for_index=None)[source]

Compute a transposition-invariant similarity matrix.

For feature frames \(x_n\) and cyclically shifted reference frames \(y_m^{(s)}\), the unprocessed similarity is \(S_s(n,m) = x_n^\mathsf{T} y_m^{(s)}\). The output retains \(\max_s S_s(n,m)\) and the maximizing shift at each cell. Optional diagonal smoothing allows corresponding passages to differ in local tempo.

Parameters:

  • feature_sequence (ndarray) – Feature matrix of shape (n_features, n_frames).

  • feature_rate (float) – Frame rate of feature_sequence and reference_sequence in Hz.

  • reference_sequence (ndarray | None) – Optional second feature matrix at the same frame rate. If omitted, feature_sequence is compared with itself.

  • shifts (Sequence[int] | None) – Cyclic feature-axis shifts (transpositions) to evaluate. If omitted, all n_features shifts are evaluated. For 12-bin chroma features, these are the twelve semitone transpositions.

  • smoothing_length_seconds (float | None) – Optional duration of diagonal path smoothing in seconds. The nearest positive integer number of SSM frames is used.

  • tempo_deviation (float) – Maximum relative tempo deviation from the main diagonal. For example, 0.3 allows tempo ratios from 0.7 to 1.3.

  • num_tempo_rel (int) – Number of relative-tempo values between the lower and upper deviation limits. Ignored when tempo_deviation is 0.

  • direction (str) – Diagonal-smoothing direction. Options are "forward", "backward", and "both".

  • norm (str | None) – Optional frame-wise feature normalization before similarity computation. Options are "1", "2", "max", "z", and None; see normalize_feature_sequence().

  • norm_threshold (float) – Threshold passed to normalize_feature_sequence() for feature normalization.

  • thresh (float | None) – Optional similarity threshold. If None, no thresholding is applied.

  • threshold_strategy (str) – Thresholding method. Options are "relative", which rejects the lowest fraction thresh of matrix cells, and "absolute", which rejects cells satisfying \(S < \mathtt{thresh}\).

  • scale (bool) – If true and thresh is set, map retained values by \((S-t)/(S_\mathrm{max}-t)\), where \(t\) is the effective threshold, yielding values in [0, 1]. If thresh is None, positive values are divided by their maximum.

  • penalty (float) – Value assigned to cells rejected by thresholding.

  • min_similarity_for_index (float | None) – If given, transposition indices at cells whose final ssm_ti value is below this value are set to -1.

Returns:

Transposition-invariant similarity matrix and transposition-index matrix, both shaped (n_frames, n_reference_frames).

Return type:

ssm_ti, index_ti

tovis.structure.crop_ssm_ti(ssm_ti, index_ti=None, *, feature_rate=1.0, x_range=None, y_range=None)[source]

Crop a similarity matrix and, optionally, its index matrix in time.

Parameters:

  • ssm_ti (ndarray) – Similarity matrix of shape (n_frames_y, n_frames_x).

  • index_ti (ndarray | None) – Optional transposition-index matrix with the same shape as ssm_ti.

  • feature_rate (float) – Frame rate of both SSM axes in Hz. Time limits are mapped to frame indices by nearest-integer rounding.

  • x_range (Sequence[float] | None) – Optional [start, end] time interval in seconds for columns. The end value is exclusive, as in normal Python slicing.

  • y_range (Sequence[float] | None) – Optional [start, end] time interval in seconds for rows. The end value is exclusive, as in normal Python slicing.

Returns:

Cropped similarity matrix, or a pair (ssm_crop, index_crop) when index_ti is provided.

Return type:

numpy.ndarray or tuple

tovis.structure.get_optimizing_path(ssm_ti, *, method='dtw')[source]

Compute an optimizing path through a similarity matrix.

Parameters:

  • ssm_ti (ndarray) – Similarity matrix.

  • method (str) – Path objective. "dtw" computes a full dynamic-time-warping path using cost \(C=-S\); "partial_matching" selects an order-preserving subset of cell pairs maximizing the sum of their similarities, with skipped rows and columns contributing zero.

Returns:

Path as (row, column) index pairs.

Return type:

numpy.ndarray

tovis.structure.get_ssm_index_ti_at_path(ssm_ti, index_ti, path, *, normalize_ssm=True)[source]

Extract similarity values and transposition indices along a path.

Parameters:

  • ssm_ti (ndarray) – Similarity matrix.

  • index_ti (ndarray) – Transposition-index matrix with the same shape as ssm_ti.

  • path (ndarray) – Path as (row, column) index pairs.

  • normalize_ssm (bool) – If true, transform extracted values by \((S-S_\mathrm{min})/(S_\mathrm{max}-S_\mathrm{min})\). Constant-valued paths are returned as zeros.

Returns:

Similarity values and transposition indices sampled along path.

Return type:

ssm_path, index_path

Utilities

Utility helpers for TOVIS.

tovis.utils.read_csv(filename, *, sep=';', **kwargs)[source]

Read a CSV file into a pandas DataFrame.

TOVIS annotation files use semicolons by default.

Parameters:

  • filename (str | Path) – Path to the CSV file.

  • sep (str) – Column separator passed to pandas.read_csv.

  • **kwargs – Additional keyword arguments passed to pandas.read_csv.

Returns:

Loaded table.

Return type:

pandas.DataFrame

tovis.utils.shorten_annotation(annotation, *, label_column='structure')[source]

Shorten common sonata-form labels in a structure annotation.

The input DataFrame is not modified. Replacement is substring-based; for example, "Exposition_FirstGroup" becomes "E_G1".

Parameters:

  • annotation (DataFrame) – Structure annotation table.

  • label_column (str) – Column containing structure labels.

Returns:

Copy of annotation with shortened labels.

Return type:

pandas.DataFrame

tovis.utils.get_exp_and_repr_limits(structure_annotation, *, start_column='start', end_column='end', label_column='structure')[source]

Return the first exposition and recapitulation limits.

Parameters:

  • structure_annotation (DataFrame) – Structure annotation table.

  • start_column (str) – Column containing segment start positions.

  • end_column (str) – Column containing segment end positions.

  • label_column (str) – Column containing structure labels.

Returns:

Two [start, end] lists. A list is empty when the corresponding section is not present.

Return type:

limits_exp, limits_repr

tovis.utils.key_to_relative_major(keys, *, suffix_maj='', suffix_min='m', output='label')[source]

Convert key labels to their diatonic center.

Minor keys are mapped to their relative major. By default, the result is a pitch-class label such as "C" or "Ab". Use output="number" for numeric pitch classes.

Parameters:

  • keys (str | Sequence[str]) – Key label or sequence of key labels. Labels may use ":maj" / ":min" suffixes or configurable suffixes such as "m" for minor.

  • suffix_maj (str) – Suffix interpreted as major when labels do not contain a colon.

  • suffix_min (str) – Suffix interpreted as minor when labels do not contain a colon.

  • output (str) – "label" returns flat-spelled key labels; "number" returns pitch classes in 0..11.

Returns:

Relative-major labels or pitch-class numbers. The return type follows the input shape: a single key returns a single value, a sequence returns a list.

Return type:

str or int or list

tovis.utils.key_label_to_pitch_class(label)[source]

Convert an ASCII key label to a pitch class.

Parameters:

label (str) – Key or pitch-class label such as "C", "F#", "Ab:maj", or "A:min".

Returns:

Pitch class in 0..11 with C equal to 0.

Return type:

int

tovis.utils.pitch_class_to_key_label(pitch_class)[source]

Convert a pitch class to a flat-spelled key label.

Parameters:

pitch_class (int) – Pitch class number. Values are interpreted modulo 12.

Returns:

Flat-spelled label such as "C", "Db", or "Ab".

Return type:

str

tovis.utils.normalize_feature_sequence(features, *, norm='2', threshold=0.001)[source]

Normalize feature frames with small-frame thresholding.

For each frame \(x\), "1", "2", and "max" compute \(x/\lVert x\rVert_1\), \(x/\lVert x\rVert_2\), and \(x/\lVert x\rVert_\infty\), respectively. "z" computes \((x-\mu_x)/\sigma_x\).

Parameters:

  • features (ndarray) – Feature matrix with time along the second axis.

  • norm (str | None) – Normalization operation. Options are "1", "2", "max", "z", and None (return the input values unchanged).

  • threshold (float) – Denominator threshold. Frames satisfying \(d \leq \mathtt{threshold}\) are returned as zero frames, where \(d\) is the selected norm or standard deviation.

Returns:

Frame-normalized feature matrix.

Return type:

numpy.ndarray

tovis.utils.smooth_resample_feature_sequence(features, feature_rate, *, smoothing_length_seconds=None, output_feature_rate=None, smoothing_window_type='boxcar')[source]

Smooth and resample a feature sequence along its time axis.

Smoothing is convolution with a unit-sum window. Resampling uses linear interpolation on a regular grid with spacing 1 / output_feature_rate seconds.

Parameters:

  • features (ndarray) – Feature matrix of shape (n_features, n_frames).

  • feature_rate (float) – Input frame rate in Hz.

  • smoothing_length_seconds (float | None) – Optional smoothing-window duration in seconds. The nearest positive integer number of input frames, obtained by rounding smoothing_length_seconds * feature_rate, is used. None skips smoothing.

  • output_feature_rate (float | None) – Optional output frame rate in Hz. Values are linearly interpolated onto a regular output time grid at exactly this rate. None preserves the input frame grid.

  • smoothing_window_type (str) – Window specification accepted by scipy.signal.get_window; common choices include "boxcar", "hann", and "hamming".

Returns:

Smoothed and resampled feature matrix and its frame rate in Hz.

Return type:

features_out, feature_rate_out

tovis.utils.time_to_measures(features, sync_annotation, feature_rate=None, *, columns=None, output_columns=None, inplace=False, frames_per_measure=10, axis=1, time_column='time', measure_column='measure', time_start=None, start_measure=None, end_measure=None)[source]

Convert seconds to measures or resample time-based features.

DataFrame inputs are converted column-wise. Scalar and one-dimensional inputs are interpreted as time points in seconds and are converted directly to measure positions. Two-dimensional or higher inputs are interpreted as feature arrays with one temporal axis; feature values are then linearly interpolated onto a regular measure grid.

Parameters:

  • features (DataFrame | ndarray | Sequence[float] | float) – DataFrame, time point, sequence of time points, or feature array with one temporal axis in seconds.

  • sync_annotation (DataFrame) – DataFrame with columns mapping time in seconds to measure.

  • feature_rate (float | None) – Frame rate of the input feature sequence in Hz. Required only when features is a feature array.

  • columns (Sequence[str] | None) – DataFrame columns containing time positions in seconds. If omitted for DataFrame input, time_column is converted.

  • output_columns (Sequence[str] | None) – Output column names for DataFrame conversion. If omitted, converted values overwrite columns.

  • inplace (bool) – If true, modify a DataFrame input in place. Otherwise a copy is returned.

  • frames_per_measure (int) – Number of output frames per measure.

  • axis (int) – Temporal axis of features. For a standard feature matrix shaped (n_features, n_frames), use 1.

  • time_column (str) – Column name for physical time in sync_annotation.

  • measure_column (str) – Column name for measure position in sync_annotation.

  • time_start (float | None) – Time in seconds of the first feature frame. None uses zero. Ignored for DataFrame, scalar, and one-dimensional inputs.

  • start_measure (float | None) – Optional first output measure. If omitted, the feature sequence and sync annotation overlap is used.

  • end_measure (float | None) – Optional last output measure. If omitted, the feature sequence and sync annotation overlap is used.

Returns:

Converted DataFrame for DataFrame input. Converted measure position for scalar input, converted measure positions for one-dimensional input, or (features_measure, measure_axis) for feature-array input.

Return type:

pandas.DataFrame or float or numpy.ndarray or tuple

tovis.utils.measures_to_time(features, sync_annotation, *, columns=None, output_columns=None, inplace=False, frames_per_measure=10, feature_rate=None, axis=1, time_column='time', measure_column='measure', measure_start=None, start_time=None, end_time=None)[source]

Convert measures to seconds or resample measure-based features.

DataFrame inputs are converted column-wise. Scalar and one-dimensional inputs are interpreted as measure positions and are converted directly to seconds. Two-dimensional or higher inputs are interpreted as feature arrays with one temporal axis in measures. measure_start should then match the first measure position of the feature array. If omitted, the first measure in sync_annotation is used. Both the measure/time map and feature values are interpolated linearly.

Parameters:

  • features (DataFrame | ndarray | Sequence[float] | float) – DataFrame, measure position, sequence of measure positions, or feature array with one temporal axis in measures.

  • sync_annotation (DataFrame) – DataFrame mapping measure positions to physical time in seconds.

  • columns (Sequence[str] | None) – DataFrame columns containing measure positions. If omitted for DataFrame input, measure_column is converted.

  • output_columns (Sequence[str] | None) – Output column names for DataFrame conversion. If omitted, converted values overwrite columns.

  • inplace (bool) – If true, modify a DataFrame input in place. Otherwise a copy is returned.

  • frames_per_measure (int) – Number of input frames per measure.

  • feature_rate (float | None) – Output frame rate in Hz. If omitted, a rate is inferred from the median local tempo.

  • axis (int) – Temporal axis of features. For a standard feature matrix shaped (n_features, n_frames), use 1.

  • time_column (str) – Column name for physical time in sync_annotation.

  • measure_column (str) – Column name for measure position in sync_annotation.

  • measure_start (float | None) – Measure position of the first input frame.

  • start_time (float | None) – Optional first output time in seconds.

  • end_time (float | None) – Optional last output time in seconds.

Returns:

Converted DataFrame for DataFrame input. Converted time in seconds for scalar input, converted times for one-dimensional input, or (features_time, time_axis) for feature-array input.

Return type:

pandas.DataFrame or float or numpy.ndarray or tuple

tovis.utils.get_tempo_curve(measure_annotation, *, time_column='time', measure_column='measure', smoothing_length_measures=None, smoothing_method='mean')[source]

Compute a local tempo curve from time/measure annotations.

For consecutive annotation points, tempo is \((m_{i+1}-m_i)/(t_{i+1}-t_i)\) measures per second and is assigned to the interval midpoint. The midpoint axis is returned in seconds and measures.

Parameters:

  • measure_annotation (DataFrame) – Annotation table containing time/measure mapping points.

  • time_column (str) – Column name for physical time.

  • measure_column (str) – Column name for measure position.

  • smoothing_length_measures (float | None) – Optional smoothing-window length in measures. For each tempo sample at measure position \(m_i\), samples within smoothing_length_measures / 2 measures are aggregated. None leaves the curve unsmoothed.

  • smoothing_method (str) – Aggregation method for smoothing. Options are "mean" and "median".

Returns:

Midpoint axes in seconds and measures, plus local tempo in measures per second.

Return type:

axis_seconds, axis_measures, tempo

Visualization

Visualization utilities for TOVIS.

tovis.visualization.get_transposition_index_colors()[source]

Return colors for inactive cells and the 12 transposition indices.

Returns:

Thirteen colors. The first color corresponds to index -1 and the remaining colors correspond to transposition indices 0 to 11.

Return type:

list of str

tovis.visualization.get_transposition_index_cmap()[source]

Return a discrete colormap for transposition-index plots.

Return type:

ListedColormap

tovis.visualization.get_major_minor_contrast_cmap()[source]

Return a red-black-blue colormap for major/minor contrast plots.

Return type:

LinearSegmentedColormap

tovis.visualization.transposition_index_to_rgba(index_ti, ssm_ti, *, alpha_min=0.0)[source]

Convert transposition indices and similarities to an RGBA image.

The RGB channels encode the transposition index. The alpha channel encodes the similarity value, normalized continuously between the finite minimum and maximum of nonnegative similarities.

Parameters:

  • index_ti (ndarray) – Transposition-index matrix with values from -1 to 11.

  • ssm_ti (ndarray) – Similarity matrix with the same shape as index_ti.

  • alpha_min (float) – Minimum alpha value assigned to finite nonnegative similarity values. Use a small value such as 0.15 when very weak cells should remain faintly visible.

Returns:

RGBA image of shape (n_rows, n_columns, 4).

Return type:

numpy.ndarray

tovis.visualization.overlay_measure_annotations(measure_annotation=None, *, filename=None, measure_annotation_hop=10, ax=None, direction='vertical', labels=True, label_location='bottom', time_column='time', measure_column='measure', kwargs_csv_reader=None, kwargs_lines=None, kwargs_labels=None)[source]

Overlay measure positions on an existing axis.

The function draws one line per selected measure annotation and optionally labels it with the measure number. Existing x- and y-axis limits are restored after drawing, so overlays respect the visible region of the underlying plot.

Parameters:

  • measure_annotation (DataFrame | None) – Annotation table containing measure positions. By default, TOVIS expects columns time and measure.

  • filename (str | Path | None) – Optional CSV file to load when measure_annotation is not provided. Loaded with read_csv().

  • measure_annotation_hop (int) – Plot every n-th measure annotation. Must be at least 1.

  • ax (Axes | None) – Matplotlib axis on which the overlay is drawn.

  • direction (str) – "vertical" draws time positions along the x-axis; "horizontal" draws time positions along the y-axis.

  • labels (bool) – If true, draw measure-number labels in addition to the lines.

  • label_location (str) – Label anchor within the axis, either "bottom" or "top".

  • time_column (str) – Column name for the physical time values.

  • measure_column (str) – Column name for measure numbers.

  • kwargs_csv_reader (Mapping[str, Any] | None) – Optional keyword arguments passed to read_csv().

  • kwargs_lines (Mapping[str, Any] | None) – Optional keyword arguments passed to Matplotlib line drawing.

  • kwargs_labels (Mapping[str, Any] | None) – Optional keyword arguments passed to Matplotlib text drawing.

Returns:

The input axis with the measure overlay added.

Return type:

matplotlib.axes.Axes

tovis.visualization.overlay_structure_annotations(structure_annotation=None, *, filename=None, ax=None, direction='vertical', labels=True, label_location='top', shorten_annotation=False, start_column='start', label_column='structure', kwargs_csv_reader=None, kwargs_lines=None, kwargs_labels=None)[source]

Overlay formal-structure boundaries on an existing axis.

The function draws structure-start boundaries and optionally labels them with the corresponding structure names. Existing axis limits are restored after drawing.

Parameters:

  • structure_annotation (DataFrame | None) – Annotation table. By default, TOVIS expects start and structure columns.

  • filename (str | Path | None) – Optional CSV file to load when structure_annotation is not provided. Loaded with read_csv().

  • ax (Axes | None) – Matplotlib axis on which the overlay is drawn.

  • direction (str) – "vertical" draws boundary positions along the x-axis; "horizontal" draws boundary positions along the y-axis.

  • labels (bool) – If true, draw structure labels in addition to the boundary lines.

  • label_location (str) – Label anchor within the axis, either "bottom" or "top".

  • shorten_annotation (bool) – If true, shorten common sonata-form labels using shorten_annotation() before plotting.

  • start_column (str) – Column name for boundary positions.

  • label_column (str) – Column name for structure labels.

  • kwargs_csv_reader (Mapping[str, Any] | None) – Optional keyword arguments passed to read_csv().

  • kwargs_lines (Mapping[str, Any] | None) – Optional keyword arguments passed to Matplotlib line drawing.

  • kwargs_labels (Mapping[str, Any] | None) – Optional keyword arguments passed to Matplotlib text drawing.

Returns:

The input axis with the structure overlay added.

Return type:

matplotlib.axes.Axes

tovis.visualization.overlay_localkey_annotations(localkey_annotation=None, *, filename=None, ax=None, direction='horizontal', start_column='start', end_column='end', localkey_column='localkey', scale_label_version='absolute_diatonic', sort_by_fifths=False, global_key=None, fill=False, major_color='blue', minor_color='red', kwargs_csv_reader=None, kwargs_boxes=None)[source]

Overlay local-key annotations as boxes on a scale-likelihood plot.

Each annotation row is drawn as an unfilled rectangle spanning start to end in time and one scale row in the plot. Major keys are framed in blue by default and minor keys in red. Minor keys are placed on the row of their relative major, matching the diatonic scale-likelihood representation where, for example, C major and A minor share one row.

Parameters:

  • localkey_annotation (DataFrame | None) – Annotation table. By default, TOVIS expects start, end, and localkey columns.

  • filename (str | Path | None) – Optional CSV file to load when localkey_annotation is not provided. Loaded with read_csv().

  • ax (Axes | None) – Matplotlib scale-likelihood axis on which the boxes are drawn.

  • direction (str) – Direction of the scale-likelihood plot, either "horizontal" or "vertical".

  • start_column (str) – Column name for annotation start positions in the plot’s time unit.

  • end_column (str) – Column name for annotation end positions in the plot’s time unit.

  • localkey_column (str) – Column name for local-key labels such as "C:maj", "A:min", "C", or "Am".

  • scale_label_version (str) – Label version used by the underlying scale-likelihood plot. Options are "absolute_diatonic" and "relative_diatonic".

  • sort_by_fifths (bool) – If true, place boxes on rows sorted by circle-of-fifths order, matching plot_scale_likelihood(sort_by_fifths=True).

  • global_key (str | None) – Optional global key used when scale_label_version is "relative_diatonic" or when fifths sorting is centered.

  • fill (bool) – If true, fill boxes with a transparent version of the major/minor color. If false, draw frames only.

  • major_color (str) – Box edge color for major local keys.

  • minor_color (str) – Box edge color for minor local keys.

  • kwargs_csv_reader (Mapping[str, Any] | None) – Optional keyword arguments passed to read_csv().

  • kwargs_boxes (Mapping[str, Any] | None) – Optional keyword arguments passed to matplotlib.patches.Rectangle.

Returns:

The input axis with local-key boxes added.

Return type:

matplotlib.axes.Axes

tovis.visualization.make_diamond_marker(x_vals, y_vals, *, marker_slope=0.5, n_points=100)[source]

Create polygon coordinates for a slanted diamond correspondence marker.

The marker connects two time intervals, one on the x-axis and one on the y-axis of an SSM-style plot. Its main direction follows the line from (x_vals[0], y_vals[0]) to (x_vals[1], y_vals[1]); marker_slope controls how wide the marker opens around that direction.

Parameters:

  • x_vals (Sequence[float]) – Two x-axis positions, usually the start and end time of one formal part.

  • y_vals (Sequence[float]) – Two y-axis positions, usually the start and end time of a corresponding formal part.

  • marker_slope (float) – Relative opening of the diamond. Larger values produce a wider marker.

  • n_points (int) – Number of interpolation points per diamond side.

Returns:

Coordinates that can be passed to matplotlib.axes.Axes.plot.

Return type:

x_marker, y_marker

tovis.visualization.overlay_correspondence_annotations(ann_parts, ann_correspondences, *, ax=None, marker_slope=0.5, start_column='start', end_column='end', harmony_column='harmony', name_column='name', modulation_label='Mod', kwargs_csv_reader=None, kwargs_lines=None)[source]

Overlay structural correspondences on an SSM-TI axis.

ann_parts describes formal parts with start/end coordinates, a harmony label, and a unique part name. ann_correspondences describes groups of corresponding parts: each row lists part names that should be connected pairwise. Each directed pair is drawn as a slanted diamond on the SSM axis. The coordinate unit is not changed by this function; use time_to_measures() or measures_to_time() beforehand if the annotation table needs conversion.

The marker color encodes the transposition from the first part’s harmony to the second part’s harmony using get_transposition_index_colors(). If either harmony is equal to modulation_label or cannot be parsed, the marker is drawn in black.

Parameters:

  • ann_parts (DataFrame | str | Path) – DataFrame or CSV filename with part annotations.

  • ann_correspondences (DataFrame | str | Path) – DataFrame or CSV filename whose rows list corresponding part names.

  • ax (Axes | None) – Matplotlib SSM axis on which the correspondence markers are drawn.

  • marker_slope (float) – Relative opening of each diamond marker.

  • start_column (str) – Column in ann_parts containing part starts in the SSM axis unit.

  • end_column (str) – Column in ann_parts containing part ends in the SSM axis unit.

  • harmony_column (str) – Column in ann_parts containing harmony or key labels.

  • name_column (str) – Column in ann_parts containing unique part names.

  • modulation_label (str) – Harmony label used for modulatory parts. Pairs containing this label are drawn in black.

  • kwargs_csv_reader (Mapping[str, Any] | None) – Optional keyword arguments passed to read_csv().

  • kwargs_lines (Mapping[str, Any] | None) – Optional keyword arguments passed to Matplotlib line drawing.

Returns:

The input axis with correspondence annotations added.

Return type:

matplotlib.axes.Axes

tovis.visualization.overlay_lines(ax, *, direction='horizontal', positions=None, spacing=1.0, color='lightgray', linewidth=0.8, linestyle='-', alpha=0.7, zorder=0.0)[source]

Overlay reference lines on an existing axis.

By default, lines are drawn at unit-spaced positions halfway between integer tick locations, for example -0.5, 0.5, 1.5, .... Axis limits are preserved.

Parameters:

  • ax (Axes) – Matplotlib axis on which the lines are drawn.

  • direction (str) – Line orientation. "horizontal" draws lines at y-axis positions; "vertical" draws lines at x-axis positions.

  • positions (Sequence[float] | None) – Optional axis positions for the lines. If omitted, positions are generated from spacing.

  • spacing (float) – Distance between generated lines when positions is omitted.

  • color (str) – Line color.

  • linewidth (float) – Line width.

  • linestyle (str) – Matplotlib line style.

  • alpha (float) – Line opacity.

  • zorder (float) – Drawing order of the lines.

Returns:

The input axis with reference lines added.

Return type:

matplotlib.axes.Axes

tovis.visualization.plot_matrix(matrix, *, direction='horizontal', feature_rate=1.0, offset=0.0, frequency_rate=1.0, xlim=None, ylim=None, clim=None, title=None, xlabel='Time (seconds)', ylabel='', xlabels=None, ylabels=None, ytick_label_hop=1, force_ytick_labels=None, colorbar=True, colorbar_label='', ax=None, figsize=(8, 3), cmap='gray_r', interpolation='None', aspect='auto')[source]

Plot a feature matrix as an image.

By default, the first matrix axis is shown vertically and the second axis horizontally. With direction="vertical", the plot is rotated so that time runs vertically. The time axis is interpreted in seconds using feature_rate.

Parameters:

  • matrix (np.ndarray) – Matrix to display, usually shaped (n_features, n_frames).

  • direction (str) – Time-axis direction, either "horizontal" or "vertical".

  • feature_rate (float) – Number of matrix columns per second.

  • offset (float) – Time value of the first matrix frame in seconds.

  • frequency_rate (float) – Number of matrix rows per vertical-axis unit when ylabels is not provided.

  • xlim (Optional[Sequence[float]]) – Optional visible horizontal-axis limits.

  • ylim (Optional[Sequence[float]]) – Optional visible vertical-axis limits.

  • clim (Optional[Sequence[float]]) – Optional color limits passed to the image.

  • title (Optional[str]) – Axis title.

  • xlabel (str) – Horizontal-axis label.

  • ylabel (str) – Vertical-axis label.

  • xlabels (Optional[Sequence[str]]) – Optional labels for discrete x-axis positions.

  • ylabels (Optional[Sequence[str]]) – Optional labels for matrix rows.

  • ytick_label_hop (int) – Show only every n-th y-axis label. Must be at least 1.

  • force_ytick_labels (Optional[Sequence[str]]) – Labels that should be shown even if skipped by ytick_label_hop.

  • colorbar (bool) – If true, add a colorbar to the figure.

  • colorbar_label (str) – Label for the colorbar.

  • ax (Optional[plt.Axes]) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • cmap (str) – Colormap passed to matplotlib.axes.Axes.imshow.

  • interpolation (str) – Image interpolation passed to matplotlib.axes.Axes.imshow.

  • aspect (str) – Image aspect mode passed to matplotlib.axes.Axes.imshow.

Returns:

The Matplotlib figure, axis, and image artist.

Return type:

fig, ax, image

tovis.visualization.plot_cmy_overlay(features, labels=None, *, clip=True, legend=True, **kwargs)[source]

Plot two or three feature matrices as a CMY-style overlay.

For two inputs, high values are shown as cyan and magenta, with overlap in blue. For three inputs, high values are shown as cyan, magenta, and yellow. Matrices may have different numbers of frames; shorter matrices are zero-padded to the length of the longest input.

Parameters:

  • features (Sequence[np.ndarray]) – Two or three matrices with the same number of rows.

  • labels (Optional[Sequence[str]]) – Optional names used for the legend entries.

  • clip (bool) – If true, clip feature values to the interval [0, 1] before color mixing.

  • legend (bool) – If true and labels are provided, add a legend describing the color mixtures.

  • **kwargs – Additional keyword arguments forwarded to plot_matrix.

Returns:

The Matplotlib figure, axis, and image artist.

Return type:

fig, ax, image

tovis.visualization.plot_transposition_index_matrix(index_ti, *, ssm_ti=None, alpha_min=0.0, feature_rate=1.0, xlim=None, ylim=None, title='Transposition index matrix', xlabel='Time (seconds)', ylabel='Time (seconds)', colorbar=True, colorbar_label='Transposition index', ax=None, figsize=(8, 7), interpolation='none')[source]

Plot a transposition-index matrix.

The matrix is expected to contain integer transposition indices -1 to 11. Cells with value -1 are treated as inactive and shown with the first color of the transposition-index colormap. If ssm_ti is provided, transposition indices are encoded as RGB colors and similarity values are encoded continuously as alpha values.

Parameters:

  • index_ti (np.ndarray) – Transposition-index matrix of shape (n_rows, n_columns).

  • ssm_ti (Optional[np.ndarray]) – Optional similarity matrix with the same shape as index_ti. When provided, its values control the alpha channel of the image.

  • alpha_min (float) – Minimum alpha value for finite nonnegative similarity values in RGBA mode.

  • feature_rate (float) – Matrix frame rate in Hz for both axes.

  • xlim (Optional[Sequence[float]]) – Optional visible horizontal time limits in seconds.

  • ylim (Optional[Sequence[float]]) – Optional visible vertical time limits in seconds.

  • title (Optional[str]) – Plot title.

  • xlabel (str) – Horizontal-axis label.

  • ylabel (str) – Vertical-axis label.

  • colorbar (bool) – If true, add a discrete colorbar.

  • colorbar_label (str) – Label for the colorbar.

  • ax (Optional[plt.Axes]) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • interpolation (str) – Interpolation mode passed to imshow.

Returns:

The Matplotlib figure, axis, and image artist. The plotted matrix uses an equal x/y data aspect ratio.

Return type:

fig, ax, image

tovis.visualization.plot_features_and_ssm(index_ti, *, ssm_ti=None, features_x=None, features_y=None, feature_rate_ssm=1.0, feature_rate_x=None, feature_rate_y=None, ssm_offset_x=0.0, ssm_offset_y=0.0, features_offset_x=0.0, features_offset_y=0.0, feature_labels_x=None, feature_labels_y=None, alpha_min=0.0, title='Transposition index matrix', xlabel='Time X (seconds)', ylabel='Time Y (seconds)', feature_ylabel_x='', feature_xlabel_y='', colorbar=True, colorbar_label='Transposition index', figsize=(10, 9), feature_panel_ratio=0.3, corner_text=None, interpolation='none', kwargs_features_x=None, kwargs_features_y=None, kwargs_corner_text=None)[source]

Plot an SSM-TI with aligned feature matrices below and to its left.

The main upper-right axis shows the transposition-index matrix, optionally weighted by ssm_ti. features_x is plotted below and shares the SSM’s horizontal time axis. features_y is rotated by 90 degrees, plotted on the left, and shares the SSM’s vertical time axis. The SSM uses equal data scaling and its panel proportions follow its temporal shape.

Parameters:

  • index_ti (np.ndarray) – Transposition-index matrix shaped (n_frames_y, n_frames_x).

  • ssm_ti (Optional[np.ndarray]) – Optional similarity matrix with the same shape as index_ti. When provided, it controls the SSM-TI alpha channel.

  • features_x (Optional[np.ndarray]) – Optional feature matrix corresponding to SSM columns, shaped (n_features_x, n_frames_x_features).

  • features_y (Optional[np.ndarray]) – Optional feature matrix corresponding to SSM rows, shaped (n_features_y, n_frames_y_features).

  • feature_rate_ssm (float) – Frame rate of both SSM axes in Hz.

  • feature_rate_x (Optional[float]) – Frame rate of features_x in Hz. Defaults to feature_rate_ssm.

  • feature_rate_y (Optional[float]) – Frame rate of features_y in Hz. Defaults to feature_rate_ssm.

  • ssm_offset_x (float) – Time offset of the SSM x-axis in seconds.

  • ssm_offset_y (float) – Time offset of the SSM y-axis in seconds.

  • features_offset_x (float) – Time offset of features_x in seconds.

  • features_offset_y (float) – Time offset of features_y in seconds.

  • feature_labels_x (Optional[Sequence[str]]) – Optional row labels for the bottom feature matrix.

  • feature_labels_y (Optional[Sequence[str]]) – Optional feature labels for the rotated left feature matrix.

  • alpha_min (float) – Minimum alpha value passed to plot_transposition_index_matrix().

  • title (Optional[str]) – Title for the SSM-TI axis.

  • xlabel (str) – Horizontal time-axis label.

  • ylabel (str) – Vertical time-axis label.

  • feature_ylabel_x (str) – Vertical-axis label for the bottom feature matrix.

  • feature_xlabel_y (str) – Horizontal-axis label for the rotated left feature matrix.

  • colorbar (bool) – If true, add a discrete transposition-index colorbar.

  • colorbar_label (str) – Label for the transposition-index colorbar.

  • figsize (Tuple[float, float]) – Figure size.

  • feature_panel_ratio (float) – Size of each feature panel relative to the adjacent SSM dimension.

  • corner_text (Optional[str]) – Optional text displayed in the empty lower-left panel.

  • interpolation (str) – Interpolation mode used for the SSM-TI.

  • kwargs_features_x (Optional[Mapping[str, Any]]) – Optional keyword arguments passed to plot_matrix() for features_x.

  • kwargs_features_y (Optional[Mapping[str, Any]]) – Optional keyword arguments passed to plot_matrix() for the rotated features_y.

  • kwargs_corner_text (Optional[Mapping[str, Any]]) – Optional keyword arguments passed to the lower-left text artist.

Returns:

Figure; tuple containing the SSM, bottom-feature, and left-feature axes; and their image artists. A missing feature matrix returns None for its image artist while leaving its axis available.

Return type:

fig, axes, images

tovis.visualization.plot_transposition_index(index_ti_path, path, *, ssm_path=None, feature_rate=1.0, offset_time=0.0, sort_by_fifths=False, weighted_scatter=True, marker_size=50.0, ax=None, figsize=(8, 3), title=None, xlabel='Time (seconds)', ylabel='Transposition index', colorbar=True, colorbar_label='Transposition index', grid=True)[source]

Plot transposition indices sampled along an optimizing path.

Parameters:

  • index_ti_path (np.ndarray) – Transposition-index values along path. Entries with value -1 are inactive and omitted from the plot.

  • path (np.ndarray) – Optimizing path as (row, column) index pairs. The first path column is used as the time axis.

  • ssm_path (Optional[np.ndarray]) – Optional similarity values along the path. If weighted_scatter is true, these values control marker size.

  • feature_rate (float) – Path-index frame rate in Hz.

  • offset_time (float) – Constant offset added to the time axis in seconds.

  • sort_by_fifths (bool) – If true, arrange transposition indices by circle-of-fifths distance and place index 0 at the vertical center. Y-axis labels show relative diatonic steps from -6 to +5, and the y-axis label is set to "Rel. diatonic transposition".

  • weighted_scatter (bool) – If true, scale marker areas by ssm_path.

  • marker_size (float) – Maximum marker size.

  • ax (Optional[plt.Axes]) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • title (Optional[str]) – Plot title.

  • xlabel (str) – Horizontal-axis label.

  • ylabel (str) – Vertical-axis label.

  • colorbar (bool) – If true, add a discrete colorbar.

  • colorbar_label (str) – Label for the colorbar.

  • grid (bool) – If true, draw a grid.

Returns:

The Matplotlib figure, axis, and scatter artist.

Return type:

fig, ax, scatter

tovis.visualization.plot_features_and_alignment(features_x=None, features_y=None, path=None, ssm_path=None, index_ti_path=None, *, feature_rate_x=1.0, feature_rate_y=1.0, feature_rate_path=1.0, duration_x=None, duration_y=None, feature_labels_x=None, feature_labels_y=None, title_x='Sequence X', title_y='Sequence Y', xlabel_x='Time (seconds)', xlabel_y='Time (seconds)', ylabel_x='', ylabel_y='', alignment_hop=1, ssm_controls_alpha=False, ssm_controls_linewidth=True, linewidth_min=0.25, linewidth_max=3.0, alignment_alpha=0.8, colorbar=True, colorbar_label='Transposition index', figsize=(10, 7), height_ratios=(2.0, 1.0, 2.0), kwargs_features_x=None, kwargs_features_y=None)[source]

Plot two feature sequences and their transposition-aware alignment.

The top feature matrix corresponds to the columns of the SSM-TI, while the bottom feature matrix corresponds to its rows. Alignment lines connect paired frames from path across the middle axis. Their widths encode ssm_path and their colors encode index_ti_path.

Parameters:

  • features_x (Optional[np.ndarray]) – Optional feature matrix corresponding to SSM-TI columns, shaped (n_features_x, n_frames_x). If omitted, the top axis remains blank and duration_x must be provided.

  • features_y (Optional[np.ndarray]) – Optional feature matrix corresponding to SSM-TI rows, shaped (n_features_y, n_frames_y). If omitted, the bottom axis remains blank and duration_y must be provided.

  • path (Optional[np.ndarray]) – Alignment path as (row, column) index pairs. Pairs outside duration_x or duration_y are skipped with a warning.

  • ssm_path (Optional[np.ndarray]) – Similarity values sampled along path, typically returned by get_ssm_index_ti_at_path().

  • index_ti_path (Optional[np.ndarray]) – Transposition indices sampled along path, typically returned by get_ssm_index_ti_at_path().

  • feature_rate_x (float) – Feature rate of features_x in Hz.

  • feature_rate_y (float) – Feature rate of features_y in Hz.

  • feature_rate_path (float) – Frame rate of both path coordinates in Hz. Path positions are converted to seconds before being aligned with the feature plots.

  • duration_x (Optional[float]) – Duration of sequence X in seconds. Required when features_x is omitted; otherwise inferred from its frame count and feature rate. When explicitly provided, this value defines the full horizontal span.

  • duration_y (Optional[float]) – Duration of sequence Y in seconds. Required when features_y is omitted; otherwise inferred from its frame count and feature rate. When explicitly provided, this value defines the full horizontal span.

  • feature_labels_x (Optional[Sequence[str]]) – Optional row labels for features_x.

  • feature_labels_y (Optional[Sequence[str]]) – Optional row labels for features_y.

  • title_x (Optional[str]) – Title for the top feature axis.

  • title_y (Optional[str]) – Title for the bottom feature axis.

  • xlabel_x (str) – Horizontal-axis label for the top feature axis.

  • xlabel_y (str) – Horizontal-axis label for the bottom feature axis.

  • ylabel_x (str) – Vertical-axis label for the top feature axis.

  • ylabel_y (str) – Vertical-axis label for the bottom feature axis.

  • alignment_hop (int) – Draw every n-th alignment pair. Must be at least 1.

  • ssm_controls_alpha (bool) – If true, scale line opacity from zero to alignment_alpha according to ssm_path. Otherwise, all lines use alignment_alpha.

  • ssm_controls_linewidth (bool) – If true, scale line widths between linewidth_min and linewidth_max according to ssm_path. Otherwise, all lines use linewidth_max.

  • linewidth_min (float) – Line width assigned to the lowest similarity.

  • linewidth_max (float) – Line width assigned to the highest similarity.

  • alignment_alpha (float) – Opacity of the alignment lines.

  • colorbar (bool) – If true, add a discrete transposition-index colorbar.

  • colorbar_label (str) – Label for the transposition-index colorbar.

  • figsize (Tuple[float, float]) – Figure size.

  • height_ratios (Sequence[float]) – Relative heights of the top feature, alignment, and bottom feature axes.

  • kwargs_features_x (Optional[Mapping[str, Any]]) – Optional additional keyword arguments passed to plot_matrix() for the top feature matrix.

  • kwargs_features_y (Optional[Mapping[str, Any]]) – Optional additional keyword arguments passed to plot_matrix() for the bottom feature matrix.

Returns:

Figure; tuple containing the top, middle, and bottom axes; tuple of feature-image artists or None for blank axes; and the alignment-line collection.

Return type:

fig, axes, images, alignment_lines

tovis.visualization.plot_chromagram(chromagram, *, direction='horizontal', feature_rate=1.0, offset=0.0, xlim=None, clim=None, title='Chromagram', xlabel='Time (seconds)', ylabel='Pitch class', chroma_labels=('C', 'C#', 'D', 'D#', 'E', 'F', 'F#', 'G', 'G#', 'A', 'A#', 'B'), show_natural_pitch_labels=False, ytick_label_hop=1, grid_lines=True, overlay_labels=None, colorbar=True, colorbar_label='', ax=None, figsize=(10, 4), cmap='gray_r', interpolation='None')[source]

Plot a 12-bin chromagram.

If chromagram is a list of two or three matrices, a CMY overlay is drawn via plot_cmy_overlay. All matrices must have one row per chroma_labels entry. With direction="vertical", time runs along the y-axis and chroma labels are shown on the x-axis.

Parameters:

  • chromagram (Union[np.ndarray, Sequence[np.ndarray]]) – Chromagram matrix of shape (12, n_frames), or a list of two or three such matrices.

  • direction (str) – Time-axis direction, either "horizontal" or "vertical".

  • feature_rate (float) – Number of chromagram frames per second.

  • offset (float) – Time value of the first chromagram frame in seconds.

  • xlim (Optional[Sequence[float]]) – Optional visible time range in seconds.

  • clim (Optional[Sequence[float]]) – Optional color limits for single-matrix plots.

  • title (Optional[str]) – Axis title.

  • xlabel (str) – Horizontal-axis label.

  • ylabel (str) – Vertical-axis label.

  • chroma_labels (Sequence[str]) – Labels for the 12 chroma rows.

  • show_natural_pitch_labels (bool) – If true, label only the natural-pitch chroma rows: C, D, E, F, G, A, and B.

  • ytick_label_hop (int) – Show only every n-th y-axis label.

  • grid_lines (bool) – If true, overlay light reference lines between feature rows using overlay_lines(). Lines are horizontal for direction="horizontal" and vertical for direction="vertical".

  • overlay_labels (Optional[Sequence[str]]) – Optional legend labels for CMY overlays.

  • colorbar (bool) – If true, add a colorbar for single-matrix plots.

  • colorbar_label (str) – Label for the colorbar.

  • ax (Optional[plt.Axes]) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • cmap (str) – Colormap passed to plot_matrix.

  • interpolation (str) – Image interpolation passed to plot_matrix.

Returns:

The Matplotlib figure, axis, and image artist.

Return type:

fig, ax, image

tovis.visualization.plot_scale_likelihood(scale_likelihood=None, *, major_likelihood=None, minor_likelihood=None, mode_contrast=None, direction='horizontal', feature_rate=1.0, offset=0.0, xlim=None, clim=None, title='Scale likelihood', xlabel='Time (seconds)', ylabel='Scale', scale_label_version='absolute_diatonic', scale_labels=None, sort_by_fifths=False, global_key=None, ytick_label_hop=1, grid_lines=True, overlay_labels=None, colorbar=True, colorbar_label='', ax=None, figsize=(10, 4), cmap='gray_r', mode_contrast_cmap=None, mode_contrast_clim=(-1.0, 1.0), mode_contrast_colorbar_label='Major-minor contrast', interpolation='None')[source]

Plot a 12-bin scale-likelihood matrix.

The rows are labelled with scale labels from get_scale_labels unless explicit labels are provided. Lists of two or three matrices are shown as a CMY overlay. Optionally, rows can be reordered by circle-of-fifths distance. With direction="vertical", time runs along the y-axis and scale labels are shown on the x-axis.

Parameters:

  • scale_likelihood (Optional[Union[np.ndarray, Sequence[np.ndarray]]]) – Scale-likelihood matrix of shape (12, n_frames), or a list of two or three matrices to plot as a CMY overlay. In major/minor contrast mode, this matrix is used as the image alpha channel, so the ordinary diatonic likelihood remains visible as intensity.

  • major_likelihood (Optional[np.ndarray]) – Optional major-scale likelihood matrix. If provided together with minor_likelihood, the plotted hue is determined by major_likelihood - minor_likelihood.

  • minor_likelihood (Optional[np.ndarray]) – Optional minor-scale likelihood matrix. Must have the same shape as major_likelihood.

  • mode_contrast (Optional[np.ndarray]) – Optional precomputed major/minor contrast matrix for the plot hue. Values near -1 are plotted red, values near 0 black, and values near 1 blue.

  • direction (str) – Time-axis direction, either "horizontal" or "vertical".

  • feature_rate (float) – Number of scale-likelihood frames per second.

  • offset (float) – Time value of the first scale-likelihood frame in seconds.

  • xlim (Optional[Sequence[float]]) – Optional visible time range in seconds.

  • clim (Optional[Sequence[float]]) – Optional color limits for single-matrix plots.

  • title (Optional[str]) – Axis title.

  • xlabel (str) – Horizontal-axis label.

  • ylabel (str) – Vertical-axis label.

  • scale_label_version (str) – Label version passed to get_scale_labels when scale_labels is not provided. Options are "absolute_diatonic" and "relative_diatonic".

  • scale_labels (Optional[Sequence[str]]) – Optional explicit labels for the 12 scale rows.

  • sort_by_fifths (bool) – If true, reorder rows and labels around the circle of fifths.

  • global_key (Optional[str]) – Optional global key. For scale_label_version="relative_diatonic", this key is labelled as "0". When sort_by_fifths is true, it is also placed near the center of the vertical axis.

  • ytick_label_hop (int) – Show only every n-th y-axis label. If global_key is used, the centered label is always shown.

  • grid_lines (bool) – If true, overlay light reference lines between feature rows using overlay_lines(). Lines are horizontal for direction="horizontal" and vertical for direction="vertical".

  • overlay_labels (Optional[Sequence[str]]) – Optional legend labels for CMY overlays.

  • colorbar (bool) – If true, add a colorbar for single-matrix plots.

  • colorbar_label (str) – Label for the colorbar.

  • ax (Optional[plt.Axes]) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • cmap (str) – Colormap passed to plot_matrix.

  • mode_contrast_cmap (Optional[mcolors.Colormap]) – Colormap used when plotting major/minor contrast. If omitted, a red-black-blue colormap is used.

  • mode_contrast_clim (Sequence[float]) – Color limits for major/minor contrast plots. The default (-1, 1) maps minor evidence to red and major evidence to blue.

  • mode_contrast_colorbar_label (str) – Colorbar label used for major/minor contrast plots when colorbar_label is empty.

  • interpolation (str) – Image interpolation passed to plot_matrix.

Returns:

The Matplotlib figure, axis, and image artist.

Return type:

fig, ax, image

tovis.visualization.plot_tempo_curve(measure_annotation, *, time_column='time', measure_column='measure', x_axis='time', ax=None, use_twin_axis=False, figsize=(10, 3), title='Tempo curve', xlabel=None, ylabel='Measures per second', smoothing_length_measures=None, smoothing_method='mean', color='tab:blue', linewidth=1.5, grid=True)[source]

Plot a local tempo curve from time/measure annotations.

Tempo is computed as the finite-difference slope d(measure) / d(time) between adjacent annotation points and plotted at interval midpoints. Use x_axis="time" for seconds or x_axis="measure" for measure positions. If use_twin_axis is true, tempo is plotted on a right-side y-axis and that tempo axis is returned.

Parameters:

  • measure_annotation (DataFrame) – Annotation table containing physical time and measure-number columns.

  • time_column (str) – Column name for seconds; passed to get_tempo_curve().

  • measure_column (str) – Column name for measure positions; passed to get_tempo_curve().

  • x_axis (str) – Horizontal axis for the plot, either "time" or "measure".

  • ax (Axes | None) – Existing axis to draw into. If omitted, a new figure and axis are created.

  • use_twin_axis (bool) – If true, draw the tempo curve on a right-side y-axis created from ax.

  • figsize (Tuple[float, float]) – Figure size used when creating a new figure.

  • title (str | None) – Plot title.

  • xlabel (str | None) – Horizontal axis label.

  • ylabel (str) – Vertical axis label for tempo.

  • smoothing_length_measures (float | None) – Optional smoothing-window length in measures passed to get_tempo_curve().

  • smoothing_method (str) – Smoothing aggregation method passed to get_tempo_curve().

  • color (str) – Line color.

  • linewidth (float) – Line width.

  • grid (bool) – If true, draw a light grid on the base axis.

Returns:

The Matplotlib figure, the axis containing the tempo curve, and the tempo line artist.

Return type:

fig, tempo_ax, line

Transcription

These helpers require the optional transcription dependencies and compatible model checkpoints at runtime; see Installation.

Transcription helpers for TOVIS.

tovis.transcription.pianoroll_to_chromagram(pianoroll)[source]

Convert an 88-key piano roll to a 12-bin chromagram.

Parameters:

pianoroll (ndarray) – Piano-roll matrix of shape (88, n_frames). Rows are interpreted as consecutive MIDI pitches starting at MIN_MIDI.

Returns:

Chromagram of shape (12, n_frames).

Return type:

numpy.ndarray

tovis.transcription.transcribe_chromagram(audio, *, pipeline='onsets_and_frames', checkpoint, device='cpu')[source]

Transcribe audio with a neural backend and return a chromagram.

Parameters:

  • audio (ndarray) – Mono audio signal. The required sample rate depends on pipeline.

  • pipeline (str) – Neural transcription pipeline. Options are "onsets_and_frames" and "deep_chroma".

  • checkpoint (str | Path) – Required path to a compatible checkpoint file. No default checkpoint location is searched.

  • device (str) – Torch device used for inference.

Returns:

Chromagram of shape (12, n_frames) and its feature rate in Hz.

Return type:

chromagram, feature_rate

tovis.transcription.transcribe_deep_chroma_chromagram(audio, *, checkpoint, device='cpu')[source]

Transcribe audio with Deep Chroma and return a chromagram.

The input audio must be mono and sampled at DEEP_CHROMA_SAMPLE_RATE. The model directly predicts 12 pitch-class activations. checkpoint must explicitly specify a compatible checkpoint file.

Parameters:

  • audio (ndarray)

  • checkpoint (str | Path)

  • device (str)

Return type:

Tuple[ndarray, float]

tovis.transcription.transcribe_onsets_and_frames_chromagram(audio, *, checkpoint, device='cpu')[source]

Transcribe audio using an explicitly supplied onsets-and-frames checkpoint.

Parameters:

  • audio (ndarray)

  • checkpoint (str | Path)

  • device (str)

Return type:

Tuple[ndarray, float]

tovis.transcription.transcribe_onsets_and_frames_frame_predictions(audio, *, checkpoint, device='cpu')[source]

Return frame predictions from the onsets-and-frames model.

The input audio must be mono and sampled at ONSETS_AND_FRAMES_SAMPLE_RATE.

Parameters:

  • audio (ndarray) – Mono audio signal sampled at ONSETS_AND_FRAMES_SAMPLE_RATE.

  • checkpoint (str | Path) – Required path to a serialized onsets-and-frames transcriber checkpoint.

  • device (str) – Torch device used for inference.

Returns:

Frame-wise piano-roll activation matrix and its feature rate in Hz. The returned matrix follows the model convention (n_frames, 88).

Return type:

frame_prediction, feature_rate