# Metric Functions¶

A metric function is a function that takes a scale as input and returns a calculated value. As mentioned in Basic Concepts, it returns a Python dict with the metric name as the key, and the metric value as the value.

The currently defined metrics all estimate the consonance or dissonance of a scale.

## sum_p_q()¶

pytuning.metrics.sum_p_q(scale)

Calculate a metric for a scale

Parameters: scale – The scale. A dict with the metric value.

This is an estimate of scale consonance. It is derived from summing the numerators and denominators of the scale degrees.

Smaller values are more consonant.

Note that this metric looks at the degrees of the scale, so it is somewhat tonic-focused. The similar metric sum_p_q_for_all_intervals() is similar, but it sums the numerator and denominator values for all distinct intervals within the scale.

While the metric is numerically defined for ratios expressed as irrational or transcendental numbers, it is really only meaningful for scales with just degrees (ratios expressed as rational numbers).

sum_p_q(create_pythagorean_scale())


yields:

{'sum_p_q': 3138}


## sum_distinct_intervals()¶

pytuning.metrics.sum_distinct_intervals(scale)

Calculate a metric for a scale

Parameters: scale – The scale. A dict with the metric value.

This metric is an estimate of scale consonance. Numerically it is the number of distinct intervals within the scale (including all ratios and their inversions).

Smaller values are more consonant.

sum_distinct_intervals(create_pythagorean_scale())


yields:

{'sum_distinct_intervals': 22}


## metric_3()¶

pytuning.metrics.metric_3(scale)

Calculate a metric for a scale

Parameters: scale – The scale. A dict with the metric value.

Metric 3 is an estimate of scale consonance. Given a ratio p/q, it is a heuristic given by the following:

Smaller values are more consonant.

The summation takes place over all of the intervals in the scale. It does not form a set of distinct intervals.

## sum_p_q_for_all_intervals()¶

pytuning.metrics.sum_p_q_for_all_intervals(scale)

Calculate a metric for a scale

Parameters: scale – The scale (i.e., a list of sympy.Rational values) The metric.

This metric is an estimate of scale consonance. It is formed by examining all unique intervals in the scale, and creating a numeric value based upon the summation of the numerators and denominators for all those intervals.

While the metric is numerically defined for ratios expressed as irrational or transcendental numbers, it is really only meaningful for scales with just degrees (ratios expressed as rational numbers).

Smaller values are more consonant.

## sum_q_for_all_intervals()¶

pytuning.metrics.sum_q_for_all_intervals(scale)

Calculate a metric for a scale.

Parameters: scale – The scale (i.e., a list of Rational s) The metric.

Metric 5 is an estimate of scale consonance. It is summation of the denominators of the normalized distinct ratios of the scale.

Smaller values are more consonant.

## All Metrics¶

There is also a function that calculates all defined metrics for a scale.

pytuning.metrics.all_metrics(scale)

Calculate all metrics for the scale

Parameters: scale – The scale (i.e., a list of Rational s) A dict containing all metrics.

As an example:

pythag = create_pythagorean_scale()
metrics = all_metrics(pythag)


will (currently) produce:

{
'metric_3': 49.9049074891784,
'sum_distinct_intervals': 22,
'sum_p_q': 3138,
'sum_p_q_for_all_intervals': 1092732,
'sum_q_for_all_intervals': 452817
}


If new metrics are coded they should be added to the __all__ data member for inclusion here.