MusicSpiralRepresentation

_get_piece_by_measure_m21_from_path(path; start_measure=1)

Fallback helper: parse a score file with music21 (via PyCall) and run the legacy get_piece_by_measure_m21. Used only when the native EzXML parser fails.

funhar_seq(kseq, fun_key)
Returns a sequence of Roman numerals given a reference for the Tonic Key.

get_Major_chord(k; w=[0.536, 0.274, 0.19], r=1, h=sqrt(2/15))

Returns the location (x,y,z) of a Major chord given by a linear combination
of a triad constructed from a fundamental note "k", the fifth (k+1) and the third (k+4)
in the spiral representation. The vector "w" contains the weights used for each term.

get_Major_key(k; o=[0.536, 0.274, 0.19], w=[0.536, 0.274, 0.19], r=1, h=sqrt(2/15))

Returns the location (x,y,z) of a Major Key given by a linear combination
of chord triads constructed from the major chords of a fundamental "tonic" note "k",
the dominant/fifth (k+1) and the subdominant/minor third (k-3) in the spiral representation.
The vector "o" contains the weights used for each chord and "w" are the weights on each note in the chord.

get_center_effect(chunk_notes; r=1, h=sqrt(2/15), 
                all_keys=all_keys, pos_all_keys=pos_all_keys, 
                sbeat_w=[[1.],[1.]], lin_w=1)

Computes the coordinates (x,y,z) for the center of effect (mass)
for a given set of notes, these notes can be in different formats:
Notes are always represented in MIDI notation, note durations can
be in any numeric format.

    Matrix: From the DataFrame built with get_xml_df or get_csv_df
    1d - Array: [n1,n2,...,nm], where each element represents a note in MIDI notation
    two 1d - Array: [n1,n2,...,nm], [d1,d2,...,dm], with the set of n
    representing the notes in MIDI notation and d each of their durations.

get_cfpitch(pitch_seq)

Converts a pitch sequence of MIDI values (0-127) into a pitch sequence ordered by fifths
to be consistent with the cylindrical representation, starting in C=0, G=1, ..., etc.

get_cfpitch_mod12(pitch_seq)

Converts a pitch sequence of MIDI values (0-127) into a pitch sequence in mod12 ordered by fifths
to be consistent with the cylindrical representation, starting in C=0, G=1, ..., etc.

get_local_lin_w(ptcs, factor)

Returns a list of pitches and their respective weights from a sequence of pitches (ptcs)
and a weighting factor (factor), the weighting gives more importance to lower notes
within the 1-factor range.

get_minor_chord(k; u=[0.536, 0.274, 0.19], r=1, h=sqrt(2/15))

Returns the location (x,y,z) of a Minor chord given by a linear combination
of a triad constructed from a fundamental note "k", the fifth (k+1) and the minor third (k-3)
in the spiral representation. The vector "u" contains the weights used for each term.

get_minor_key(k; v=[0.536, 0.274, 0.19], w=[0.536, 0.274, 0.19],
u=[0.536, 0.274, 0.19], a=0.75, b=0.75, r=1, h=sqrt(2/15))

Returns the location (x,y,z) of a Minor Key given by a linear combination
of chord triads constructed from the major chords of a fundamental note "k",
the possible "dominant" triad (k+1) and the possible "subdominant" triad (k-3) in the spiral representation.
The vector "v" contains the weights used for each chord and "w" are the weights on each note in the major chords.
"u" are the weights for the minor chords. The dominant and subdominant minor/major chords are weighted by "a" and "b".

get_onon_notes(s)

get_piece_by_measure_csv(s; qdiv=32, abs_time=true)

Returns a vector of two dimensional arrays of the basic information of the piece for analyzing its properties,
input "s" should be a CSV table from a CSV file converted from a MIDI file with the midicsv script available for free
in: https://www.fourmilab.ch/webtools/midicsv/ .

The first output consist of a vector which components represent each measure of the music piece,
each measure contains four columns; Beat: number of beat where the note starts (beat or halfbeat)
Measure: the fraction of the measure (n/d), Duration: the duration of the note in midiclocks, if abs_time=true
the output returns the time in ms where the note started and ended before the duration of the note,
Pitch: the pitch of the note represented in MIDI notation (0-127).

The second output corresponds to the total number of notes in the piece and the number of notes that
fall outside the threshold given (1/qdiv), most of the time if notes fall outside this threshold is because
the MIDI was sequenced (recorded) instead of generated with a music score software.

function get_piece_by_measure_m21(m21_data; start_measure=1)

Returns an array with the information of pitches and duration on each measure in the following format:

| #measure | time signature | start_quarter | end_quarter | duration (in quarters) | pitch (0-127) |

get_piece_by_measure_mid(filepath; abs_time=true, start_measure=1, ignore_drums=true)

Parse a raw `.mid` file with MIDI.jl and return a flat `N×6` matrix in the same
layout as `get_piece_by_measure_m21`:

| #measure | time signature | start | end | duration | pitch (0-127) |

The time base is tick-exact (derived from the file's ticks-per-quarter and its
time-signature / tempo meta events), so no `qdiv` beat-snapping tolerance is needed.

- `abs_time=true`  → start/end/duration are in **milliseconds** (matches the CSV path,
  honoring all tempo changes).
- `abs_time=false` → start/end/duration are in **absolute quarter notes** (matches the
  XML path); this is tempo-independent.

`start_measure` offsets the reported measure numbers (matching `get_piece_by_measure_m21`).
`ignore_drums=true` drops MIDI channel 10 (0-indexed channel 9), whose pitches are
percussion-map indices rather than real pitches.

get_piece_by_measure_xml(filepath; start_measure=1)

Parse a MusicXML file (.musicxml, .xml, or .mxl) natively with EzXML and return a flat N×6 matrix in the same layout as get_piece_by_measure_m21:

| #measure | time signature | start_quarter | end_quarter | duration (quarters) | pitch (0-127) |

Notes from all parts are merged; the time-signature timeline is taken from the first part (matching the previous music21 behavior). Durations are exact in quarter notes (<duration>/<divisions>); chords share an onset, rests and unpitched notes are skipped, tied noteheads are kept separate, and <forward>/ <backup> shift the within-measure offset for multi-voice parts.

get_pitch(k; r=1, h=sqrt(2/15))

Returns the location (x,y,z) of a pitch "k"
in the spiral representation, pitches are in module 12
the variable "r" is the radius of the cylinder
and "h" is the vertical distance between thirds.

get_rank_freq(series)

Returns a 2-Dimensional Array of symbols and their respective frequencies
from a series of data. The output is ordered by rank (most to least frequent).

pitch_to_midi(pitch_elem) -> Int

Convert a MusicXML <pitch> element to a MIDI note number (matching music21's .ps):

MIDI = 12 * (octave + 1) + step_semitone + alter

read_musicxml(filepath) -> EzXML.Document

Read a .musicxml, .xml, or .mxl file and return the parsed XML document. .mxl files are ZIP archives; the inner score is located by reading the full-path of <rootfile> in META-INF/container.xml (with a fallback to the first non-META-INF XML entry).