Feature metadata

Shared metadata used by the docs feature catalogue and melody_features.get_feature_metadata().

Shared metadata for melodic features: name, source, type, family, description.

This module is the single source of truth for feature metadata used both by the Quarto documentation table (docs/quarto_table_build.py) and by the package-level get_feature_metadata() API, which lets users join per-feature metadata (source, family, domain, type, description) onto a long format feature table by feature_name.

Collects labelled feature callables from melody_features.features, extracts metadata such as pre-existing implementations, references, descriptions, notes, and categories.

class FeatureRow(python_name, name, source_url, implementations, references, description, type_label, notes, category, domain, sort_name, feature_types=(), has_corpus_stats_param=False)

Bases: object

One row of metadata for a single atomic feature (function or descriptor).

Parameters:

• python_name (str)

• name (str)

• source_url (str)

• implementations (str)

• references (str)

• description (str)

• type_label (str)

• notes (str)

• category (str)

• domain (str)

• sort_name (str)

• feature_types (tuple)

• has_corpus_stats_param (bool)

python_name: str

name: str

source_url: str

implementations: str

references: str

description: str

type_label: str

notes: str

category: str

domain: str

sort_name: str

feature_types: tuple = ()

has_corpus_stats_param: bool = False

snake_to_title(name)

Parameters:

name (str)

Return type:

str

capitalize_ioi(text)

Capitalize ‘IOI’ in text while preserving other formatting.

Parameters:

text (str)

Return type:

str

normalize_feature_text(text)

Normalize acronyms and tokens in free text. - IOI -> IOI - df -> DF (word-boundary) - tfdf -> TFDF (word-boundary) - npvi -> NPVI (word-boundary)

Parameters:

text (str)

Return type:

str

fix_possessive_feature_names(text)

Fix known feature name possessives that are lost by title-casing. E.g., ‘Honores H’ -> “Honore’s H”, ‘Sichels S’ -> “Sichel’s S”, etc.

Parameters:

text (str)

Return type:

str

extract_sections_from_docstring(doc)

Parse simple NumPy-style sections (Parameters, Returns, Notes, Citation, etc.).

Parameters:

doc (str)

Return type:

dict[str, str]

determine_type_from_return_annotation(obj)

Return type:

str

collect_feature_rows(objs)

Collect metadata rows for a set of (name, callable/property) pairs.

Parameters:

objs (Iterable[tuple[str, object]])

Return type:

list[FeatureRow]

to_dataframe(rows)

Parameters:

rows (list[FeatureRow])

Return type:

DataFrame

build_table()

Build the exported feature table from atomic feature callables only.

Convention: helper/aggregator wrappers (for example get_*) are intentionally excluded so the table contains only user-facing scalar/sequence feature atoms.

Return type:

DataFrame

count_features()

Return the number of features included in the summary table.

Return type:

int

get_feature_metadata()

Return a metadata table for every feature produced by get_all_features.

One row per feature family.feature_name combination (matching the dotted column names in the wide-format DataFrame returned by melody_features.get_all_features()), with columns describing the feature’s source, family/category, domain, return type, and description. This table can be joined onto a long-format feature table by feature_name (see melody_features.to_long_format()).

to_long_format falls back to inferring family/source from the column prefix for any wide-format column (e.g. dynamic IDyOM columns) that doesn’t have an exact match here.

Returns:

Columns: feature_name, family, source, domain, type, description, notes, references.

Return type:

pd.DataFrame