Package: Pattern Search (src.pattern_search)

Module: pattern_search.functions.py

This module contains the functions to search for specific musical patterns in a given score. The search can be performed with various combinations of considerations for transposition and rhythm. There are a total of six functions provided for the search.

The module depends on the pandas and music21 libraries for data manipulation and musical score parsing.

Functions

  • ‘pattern_search_without_transposition_without_rhythm’: Search for a specific musical pattern in a score without considering transposition and rhythm.

  • ‘pattern_search_with_transposition_without_rhythm’: Search for a specific musical pattern in a score considering transposition but not rhythm.

  • ‘pattern_search_without_transposition_with_rhythm’: Search for a specific musical pattern in a score considering rhythm but not transposition.

  • ‘pattern_search_with_transposition_with_rhythm’: Search for a specific musical pattern in a score considering both transposition and rhythm.

  • ‘pattern_search_only_rhythm’: Search for a specific musical pattern in a score considering only rhythm.

Examples

For usage examples, refer to the individual function docstrings.

iMaT.src.pattern_search.functions.pattern_search_only_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)[source]

Search for a specific musical pattern in a score considering only rhythm.

Parameters:

  • identifier (str) – Identifier for the selected score.

  • selected_score_deepcopy (music21.stream.Stream) – A deep copy of the selected musical score.

  • search_pattern (list) – A list representing the musical pattern to be searched.

  • search_pattern_clear_names (list) – A list of clear names for the search pattern.

Returns:

A dataframe containing the search results.

Return type:

pandas.DataFrame

Examples

>>> identifier = "example_score"
>>> selected_score = music21.converter.parse("example_score.mxl")
>>> selected_score_deepcopy = copy.deepcopy(selected_score)
>>> search_pattern = [1.0, 0.5, 0.5]
>>> search_pattern_clear_names = ["quarter", "eighth", "eighth"]
>>> pattern_search_only_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)
iMaT.src.pattern_search.functions.pattern_search_with_transposition_with_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)[source]

Search for a specific musical pattern in a score considering both transposition and rhythm.

Parameters:

  • identifier (str) – Identifier for the selected score.

  • selected_score_deepcopy (music21.stream.Stream) – A deep copy of the selected musical score.

  • search_pattern (list) – A list representing the musical pattern to be searched.

  • search_pattern_clear_names (list) – A list of clear names for the search pattern.

Returns:

A dataframe containing the search results.

Return type:

pandas.DataFrame

iMaT.src.pattern_search.functions.pattern_search_with_transposition_without_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)[source]

Search for a specific musical pattern in a score considering transposition but not rhythm.

Parameters:

  • identifier (str) – Identifier for the selected score.

  • selected_score_deepcopy (music21.stream.Stream) – A deep copy of the selected musical score.

  • search_pattern (list) – A list representing the musical pattern to be searched.

  • search_pattern_clear_names (list) – A list of clear names for the search pattern.

Returns:

A dataframe containing the search results.

Return type:

pandas.DataFrame

Examples

>>> identifier = "example_score"
>>> selected_score = music21.converter.parse("example_score.mxl")
>>> selected_score_deepcopy = copy.deepcopy(selected_score)
>>> search_pattern = ["C4", "E4", "G4"]
>>> search_pattern_clear_names = ["C", "E", "G"]
>>> pattern_search_with_transposition_without_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)
iMaT.src.pattern_search.functions.pattern_search_without_transposition_with_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)[source]

Search for a specific musical pattern in a score considering rhythm but not transposition.

Parameters:

  • identifier (str) – Identifier for the selected score.

  • selected_score_deepcopy (music21.stream.Stream) – A deep copy of the selected musical score.

  • search_pattern (list) – A list representing the musical pattern to be searched.

  • search_pattern_clear_names (list) – A list of clear names for the search pattern.

Returns:

A dataframe containing the search results.

Return type:

pandas.DataFrame

iMaT.src.pattern_search.functions.pattern_search_without_transposition_without_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)[source]

Search for a specific musical pattern in a score without considering transposition and rhythm.

Parameters:

  • identifier (str) – Identifier for the selected score.

  • selected_score_deepcopy (music21.stream.Stream) – A deep copy of the selected musical score.

  • search_pattern (list) – A list representing the musical pattern to be searched.

  • search_pattern_clear_names (list) – A list of clear names for the search pattern.

Returns:

A dataframe containing the search results.

Return type:

pandas.DataFrame

Examples

>>> identifier = "example_score"
>>> selected_score = music21.converter.parse("example_score.mxl")
>>> selected_score_deepcopy = copy.deepcopy(selected_score)
>>> search_pattern = ["C4", "E4", "G4"]
>>> search_pattern_clear_names = ["C", "E", "G"]
>>> pattern_search_without_transposition_without_rhythm(identifier, selected_score_deepcopy, search_pattern, search_pattern_clear_names)

Module: pattern_search.main.py

This module contains functions to perform pattern search in musical scores. It is a part of the pattern_search package and provides the main workflow for single musical piece pattern search along with related utilities and display functions.

Functions

  • ‘map_pattern_search_function_to_pattern_selection_function’: Returns the corresponding pattern selection function for a provided pattern search function.

  • ‘pattern_search_workflow_single_musical_piece’: Executes the workflow for pattern search in a single musical piece.

  • ‘display_results_func’: Displays the results of the pattern search in a graphical format using a scatter plot.

  • ‘helper_ignore_rests’: Provides an option to the user to decide whether to search patterns across rests or not.

  • ‘get_user_option_post_analysis’: Presents the user with post-analysis options (“repeat”, “export”, “display_results”, or “back”) and gets their selection.

Notes

This module uses various functions and objects from other modules of this package and dependencies such as music21, pandas, matplotlib, etc. to perform and represent the results of the musical pattern search.

The main function of this module is pattern_search_workflow_single_musical_piece which performs a pattern search in a selected musical piece and displays the results. The function map_pattern_search_function_to_pattern_selection_function maps pattern search functions to pattern selection functions. The function display_results_func generates a graphical representation of the results. The function helper_ignore_rests lets users decide if they want to search patterns across rests. The function get_user_option_post_analysis provides options to the user after the pattern search is complete.

iMaT.src.pattern_search.main.display_results_func(pattern_search_results: DataFrame, identifier: str, function_name: str)[source]
iMaT.src.pattern_search.main.get_user_option_post_analysis()[source]

Presents the user with post-analysis options (“repeat”, “export”, “display_results”, or “back”) and gets their selection. Returns the user’s selection as a string. Use the display_menu_request_selection() to display the possible options.

iMaT.src.pattern_search.main.helper_ignore_rests(selected_score_deepcopy)[source]
iMaT.src.pattern_search.main.map_pattern_search_function_to_pattern_selection_function(pattern_search_func: callable)[source]

Returns the corresponding pattern selection function for a provided pattern search function.

Parameters:

analysis_func (callable) – The pattern search function for which the corresponding pattern selection function is to be returned.

Returns:

The corresponding pattern selection function.

Return type:

function

iMaT.src.pattern_search.main.pattern_search_workflow_single_musical_piece(pattern_search_func: callable)[source]

Module: pattern_search.utils.py

Provides utility functions for selecting musical patterns based on notes, rhythm, or a combination of both in the pattern_search package. Each function prompts the user to make selections and constructs musical patterns accordingly.

Functions

  • ‘pattern_selection_notes_only’: Allows the user to select a pattern based on notes only.

  • ‘pattern_selection_rhythm_only’: Allows the user to select a pattern based on rhythm only.

  • ‘pattern_selection_notes_and_rhythm’: Allows the user to select a pattern based on both notes and rhythm.

Each function returns a tuple containing the list of music21.note.Note objects and a list of clear names, and handles errors using the handle_error function from the src.utils.error_handling module.

Notes

This module uses the music21 library, a toolkit for computer-aided musicology. music21’s note.Note objects are used to represent individual notes in a musical pattern.

This module also uses the src.cli.menu_constructors.display_menu_request_selection function to interactively display menus and handle user input.

Example

>>> from pattern_search import utils
>>> utils.pattern_selection_notes_and_rhythm()
([<music21.note.Note C quarterLength=0.5>], [['C', '0.5']])

See also

music21.note.Note, src.cli.menu_constructors.display_menu_request_selection, src.utils.error_handling.handle_error

iMaT.src.pattern_search.utils.pattern_selection_notes_and_rhythm()[source]

Allows the user to select a pattern based on both notes and rhythm.

The user can add notes and rhythms to the pattern, remove the last added pair, or complete the pattern selection. The rhythm values are converted to quarterLength attribute of note.Note objects.

Returns:

Tuple containing the list of note.Note objects with specified quarterLength and a list of clear names.

Return type:

tuple

Raises:

Exception – Any exception that occurs is caught and handled using handle_error.

See also

src.cli.menu_constructors.display_menu_request_selection, music21.note.Note, src.utils.error_handling.handle_error

Examples

>>> pattern_selection_notes_and_rhythm()
([<music21.note.Note C quarterLength=0.5>], [['C', '0.5']])
iMaT.src.pattern_search.utils.pattern_selection_notes_only()[source]

Allows the user to select a pattern based on notes only.

The user can add notes to the pattern, remove the last added note, or complete the pattern selection.

Returns:

Tuple containing the list of note.Note objects and a list of clear names.

Return type:

tuple

Raises:

Exception – Any exception that occurs is caught and handled using handle_error.

See also

src.cli.menu_constructors.display_menu_request_selection, music21.note.Note, src.utils.error_handling.handle_error

Examples

>>> pattern_selection_notes_only()
([<music21.note.Note C>], ['C'])
iMaT.src.pattern_search.utils.pattern_selection_rhythm_only()[source]

Allows the user to select a pattern based on rhythm only.

The user can add rhythms to the pattern, remove the last added rhythm, or complete the rhythm selection. The rhythm values are converted to quarterLength attribute of note.Note objects.

Returns:

Tuple containing the list of note.Note objects with specified quarterLength and a list of clear names.

Return type:

tuple

Raises:

Exception – Any exception that occurs is caught and handled using handle_error.

See also

src.cli.menu_constructors.display_menu_request_selection, music21.note.Note, src.utils.error_handling.handle_error

Examples

>>> pattern_selection_rhythm_only()
([<music21.note.Note C quarterLength=0.5>], ['0.5'])