Corpus

Corpus paths, loading helpers, and FANTASTIC-style corpus statistics.

compute_corpus_ngrams(melodies, n_range=(1, 5), phrase_gap=1.5, njobs=-1)

Compute n-gram frequencies across the entire corpus using multiprocessing.

Parameters:

• melodies (List[Melody]) – List of Melody objects to analyze

• n_range (Tuple[int, int]) – Inclusive range of n-gram lengths to consider (min, max)

• phrase_gap (float) – Phrase-gap threshold in quarter-note units used by tokenization.

• njobs (int | None)

Returns:

Dictionary containing corpus-wide n-gram statistics

Return type:

Dict

save_corpus_stats(stats, filename)

Save corpus statistics to a JSON file.

Parameters:

• stats (Dict) – Corpus statistics from compute_corpus_ngrams

• filename (str) – Path to save JSON file

Return type:

None

load_corpus_stats(filename)

Load corpus statistics from a JSON file.

Parameters:

filename (str) – Path to JSON file. If no extension is provided, .json will be added.

Returns:

Corpus statistics dictionary

Return type:

Dict

load_melody(idx, filename)

Load a single melody from a JSON file.

Parameters:

• idx (int) – Index of melody to load

• filename (str) – Path to JSON file

Returns:

Loaded melody object

Return type:

Melody

load_midi_melody(midi_path)

Load a melody from a MIDI file.

Parameters:

midi_path (str) – Path to MIDI file

Returns:

Loaded melody object, or None if the file could not be loaded

Return type:

Melody or None

load_melodies_from_directory(directory, file_type='json', njobs=-1)

Load melodies from a directory containing either JSON or MIDI files.

Parameters:

• directory (str) – Path to directory containing melody files

• file_type (str) – Type of files to load (“json” or “midi”)

• njobs (int | None)

Returns:

List of loaded melody objects

Return type:

List[Melody]

make_corpus_stats(midi_dir, output_file, n_range=(1, 5), phrase_gap=1.5)

Process a directory of MIDI files and save corpus statistics.

Parameters:

• midi_dir (str) – Path to directory containing MIDI files

• output_file (str) – Path where to save the corpus statistics JSON file

• n_range (Tuple[int, int], optional) – Inclusive range of n-gram lengths (min, max), by default (1, 5)

• phrase_gap (float, optional) – Phrase-gap threshold in quarter-note units used by tokenization.

Return type:

None

make_corpus_stats_from_json(json_file, output_file, n_range=(1, 5), phrase_gap=1.5)

Process a JSON file containing melody data and save corpus statistics.

Parameters:

• json_file (str) – Path to JSON file containing melody data

• output_file (str) – Path where to save the corpus statistics JSON file

• n_range (Tuple[int, int], optional) – Inclusive range of n-gram lengths (min, max), by default (1, 5)

• phrase_gap (float, optional) – Phrase-gap threshold in quarter-note units used by tokenization.

Return type:

None

get_corpus_path(corpus_name)

Get the path to a bundled corpus.

Parameters:

corpus_name (str) – Name of the corpus. Currently supports: ‘essen’, ‘pearce_default_idyom’.

Returns:

Path to the corpus directory

Return type:

Path

Raises:

• ValueError – If the corpus name is not recognized

• FileNotFoundError – If the corpus directory does not exist

get_corpus_files(corpus_name, max_files=None)

Get a list of MIDI files from a bundled corpus.

Parameters:

• corpus_name (str) – Name of the corpus. Currently supports: ‘essen’, ‘pearce_default_idyom’.

• max_files (int, optional) – Maximum number of files to return. If None, returns all files.

Returns:

List of MIDI file paths

Return type:

List[Path]

Raises:

• ValueError – If the corpus name is not recognized

• FileNotFoundError – If the corpus directory does not exist

list_available_corpora()

List all available bundled corpora.

Returns:

List of available corpus names

Return type:

List[str]