dataCompilation

dataCompilation

data_compilation(y, original_sr, hop_length, ...)

Compile per-note perceptual descriptors from an aligned audio-score pair and write the results to disk in the appropriate format (.krn, .mei, or .csv).
pyampact.dataCompilation.data_compilation(y, original_sr, hop_length, winms, tsr, spec, nmat, piece, audio_file_path, force_pyin=False)[source]

Compile per-note perceptual descriptors from an aligned audio-score pair and write the results to disk in the appropriate format (.krn, .mei, or .csv).

F0 estimation strategy is selected automatically based on the number of parts in the score: monophonic pieces use pyin directly; polyphonic pieces attempt pitch-separated F0 estimation via the reassigned spectrogram and fall back to pyin on failure. Set force_pyin=True to override and use pyin for all pieces regardless of polyphony.

Parameters:

  • y (ndarray) – Audio time series at the original sample rate.

  • original_sr (int) – Sample rate of y.

  • hop_length (int) – Hop size in samples at tsr used during alignment (e.g. 32).

  • winms (float) – Analysis window size in milliseconds (e.g. 100).

  • tsr (int) – Target sample rate used during alignment (e.g. 4000).

  • spec (ndarray) – Magnitude spectrogram produced by alignment, shape (freq x frames).

  • nmat (dict) – Note matrix dict returned by run_alignment, keyed by part name. Each value is a DataFrame with at minimum ONSET_SEC, OFFSET_SEC, and MIDI columns.

  • piece (Score) – Score object returned by run_alignment / load_score.

  • audio_file_path (str) – Path to the source audio file. Used to derive the output folder name (output_files/output_<stem>/) and filename stem.

  • force_pyin (bool, optional) – If True, use pyin F0 estimation for all notes regardless of whether the piece is monophonic or polyphonic. Default is False (auto-detect).

Returns:

  • nmat (dict) – The input note matrix dict with perceptual descriptor columns appended to each part DataFrame, including: f0Vals, meanf0, ppitch1, ppitch2, jitter, vibratoDepth, vibratoRate, pwrVals, meanPwr, shimmer, specCentVals, meanSpecCent, specBandwidthVals, meanSpecBandwidth, specContrastVals, meanSpecContrast, specFlatnessVals, meanSpecFlatness, specRolloffVals, meanSpecRolloff.

  • fileOutput (str) – Path to the primary output file written to disk: a .krn file for Humdrum kern scores, a .csv file for Tony CSV scores, or a .mei file (with companion .csv) for all other formats.

Notes

Spectral features (centroid, bandwidth, contrast, flatness, rolloff) are precomputed once over the full spectrogram and sliced per note to avoid redundant computation. F0 and RMS power are computed at original_sr using window and hop sizes derived from the alignment spectrogram dimensions rather than the caller-supplied hop_length, which ensures consistency with the DTW alignment grid.

pyampact.dataCompilation.export_selected_columns(nmat, columns, audio_file_path=None, output_path=None)[source]

Export a user-defined subset of descriptor columns from a note matrix to CSV.

Parameters:

  • nmat (pd.DataFrame) – Note matrix containing selected olumns.

  • columns (list of str) – Column names to include in the exported CSV.

  • audio_file_path (str, optional) – Path to the source audio file. When provided, the output is written to output_files/output_<stem>/<stem>_selected.csv alongside the other pyAMPACT output files for that recording.

  • output_path (str, optional) – Explicit destination path for the CSV file. Takes precedence over the auto-derived path when both audio_file_path and output_path are given. If neither is provided, defaults to ./output_selected_data.csv.

Return type:

None

pyampact.dataCompilation.plot_piano_roll(piece, nmat, audio_file_path, target_sr, hop_length, verbose=False)[source]

Build a piano-roll image from aligned note data and save it alongside the other output files for this audio file.

The piano roll is painted in audio-seconds (x-axis) vs MIDI pitch (y-axis). Spine annotations present in the score (keys, harm, chord/harte, function) are extracted, remapped from quarter-note offsets to audio seconds, and printed to stdout for inspection — exactly as the original exampleScript did.

Parameters:

  • piece (Score) – The Score object returned by run_alignment / load_score.

  • nmat (dict) – The aligned note-matrix dict returned by data_compilation.

  • audio_file_path (str) – Path to the original audio file — used to derive the output folder name.

  • target_sr (int) – Target sample rate used during alignment (e.g. 4000).

  • hop_length (int) – Hop size in samples at target_sr used during alignment (e.g. 32).

  • verbose (boolean) – If true then print the piano roll specs

Returns:

  • pr (ndarray (128 × n_cols, float32)) – The raw piano-roll matrix, in case the caller wants to post-process it.

  • audio_axis (pd.Index) – The time axis (seconds) corresponding to the columns of pr.