Axis

‘audio.utils.axis’ module within the ketos library

This module provides utilities to convert bin numbers to continuous variable values and vice versa.

Bins are numbered 0,1,2,3,…,N-1, counting from lower to higher values, where N is the number of bins.

By default, each bin represents a half-open interval, including the lower (left) boundary while excluding the upper (right) boudary, i.e., [a,b), except for the last bin, which represents a closed interval with both boundaries included, i.e. [a,b].

Contents:

Axis class: LinearAxis class: Log2Axis class

class ketos.audio.utils.axis.Axis(bins, x_min, label)[source]

Bases: object

Base class for all Axis classes.

Child classes must implement the methods bin and low_edge.

Args:
bins: int

Number of bins

x_min: float

Left edge of first bin

label: str

Descriptive label. Optional

Attributes:
bins: int

Number of bins

x_min: float

Left edge of first bin

label: str

Descriptive label.

bin(x, truncate=False, closed_right=False)[source]

Get bin number corresponding to a given value.

By default bins are closed on the left and open on the right, i.e., [a,b). Use the argument closed_right to reverse this.

If the value lies outside the axis range, a negative bin number or a bin number above N-1 will be returned. This behaviour can be changed using the argument ‘truncate’.

Args:
x: array-like

Value

truncate: bool

Return 0 if x is below the lower axis boundary and N-1 if x is above the upper boundary. Default is False.

closed_right: bool

If False, bin is closed on the left and open on the right. If True, bin is open on the left and closed on the right. Default is False.

Returns:
b: array-like

Bin number

bin_width(b=0)[source]

Get the width of a given bin.

Args:
b: int

Bin number

Returns:
: float

Bin width

cut(x_min=None, x_max=None, bins=None)[source]

Cut the axis by specifing either a minimum and a maximum value, or by specifying a minimum value and the axis length (as an integer number of bins).

At both ends of the axis, the bins containing the cut values are included.

Args:
x_min: float

Position of lower cut. Defaults to the axis’ lower limit.

x_max: float

Position of upper cut.

bins: int

Cut length, given as a integer number of bins. When bins is specified, the argument x_max is ignored.

Returns:
b_min, b_max: int, int

Lower and upper bin number of the cut

Example:
>>> from ketos.audio.utils.axis import LinearAxis
>>> #Linear axis between 0. and 10. with 20 bins.
>>> ax = LinearAxis(bins=20, extent=(0.,10.))
>>> #Select interval from 5.3 to 8.7
>>> b_min, b_max = ax.cut(x_min=5.3, x_max=8.7)
>>> print(ax.x_min, ax.x_max, ax.bins, ax.dx)
5.0 9.0 8 0.5
>>> print(b_min, b_max)
10 17
>>> #Select 6-bin long interval with lower cut at 3.2
>>> ax = LinearAxis(bins=20, extent=(0.,10.))
>>> b_min, b_max = ax.cut(x_min=3.2, bins=6)
>>> print(ax.x_min, ax.x_max, ax.bins, ax.dx)
3.0 6.0 6 0.5
low_edge(b)[source]

Get the lower-edge value of a given bin.

Must be implemented in child class.

Args:
b: array-like

Bin number.

Returns:
x: array-like

Lower-edge bin value

max()[source]

Get the upper boundary of the axis.

Returns:
: float

Upper edge of the last bin

min()[source]

Get the lower boundary of the axis.

Returns:
: float

Lower edge of first bin

up_edge(b)[source]

Get the upper-edge value of a given bin.

Args:
b: array-like

Bin number.

Returns:
x: array-like

Upper-edge bin value

class ketos.audio.utils.axis.LinearAxis(bins, extent, label=None)[source]

Bases: ketos.audio.utils.axis.Axis

Linear axis.

Args:
bins: int

Number of bins

extent: tuple(float,float)

Axis range, e.g. (0., 100.)

label: str

Descriptive label. Optional

Attributes:
bins: int

Number of bins

x_min: float

Left edge of first bin

dx: float

Bin width

label: str

Descriptive label.

bin(x, truncate=False, closed_right=False)[source]

Get bin number corresponding to a given value.

By default bins are closed on the left and open on the right, i.e., [a,b). Use the argument closed_right to reverse this.

If the value lies outside the axis range, a negative bin number or a bin number above N-1 will be returned. This behaviour can be changed using the argument ‘truncate’.

Args:
x: array-like

Value

truncate: bool

Return 0 if x is below the lower axis boundary and N-1 if x is above the upper boundary. Default is False.

closed_right: bool

If False, bin is closed on the left and open on the right. If True, bin is open on the left and closed on the right. Default is False.

Returns:
b: array-like

Bin number

Example:
>>> from ketos.audio.utils.axis import LinearAxis
>>> #Linear axis between 0. and 100. with 200 bins.
>>> ax = LinearAxis(bins=200, extent=(0.,100.))
>>> #Get bin number corresponding to x=0.6
>>> b = ax.bin(0.6)
>>> print(b)
1
>>> #Get several bin numbes in one call 
>>> b = ax.bin([0.6,11.1])
>>> print(b)
[ 1 22]
>>> #Get bin number for values at bin edges
>>> b = ax.bin([0.0,0.5,1.0,100.])
>>> print(b)
[  0   1   2 199]
>>> #Note that when the value sits between two bins, 
>>> #the higher bin number is returned.
>>> #This behaviour can be reversed using the closed_right 
>>> #argument,
>>> b = ax.bin([0.0,0.5,1.0,100.], closed_right=True)
>>> print(b)
[  0   0   1 199]
>>> #Note that the lower edge of the first bin and the 
>>> #upper edge of the last bin are special cases: for 
>>> #these values, the first (0) and last (199) bin 
>>> #numbers are always returned.
>>> #Get bin numbers outside the axis range
>>> b = ax.bin([-2.1, 100.1])
>>> print(b)
[ -5 200]
>>> b = ax.bin([-2.1, 100.1], truncate=True)
>>> print(b)
[  0 199]
low_edge(b)[source]

Get the lower-edge value of a given bin.

Args:
b: array-like

Bin number.

Returns:
x: array-like

Lower-edge bin value

Example:
>>> from ketos.audio.utils.axis import LinearAxis
>>> #Linear axis between 12. and 22. with 5 bins.
>>> ax = LinearAxis(bins=5, extent=(12.,22.))
>>> #Get lower-edge values of bins 1 and 4
>>> x = ax.low_edge([1,4])
>>> print(x)
[14. 20.]
zero_offset()[source]

Shift axis lower boundary to zero.

class ketos.audio.utils.axis.Log2Axis(bins, bins_per_oct, min_value, label=None)[source]

Bases: ketos.audio.utils.axis.Axis

Logarithmic axis with base 2.

The lower-edge value of bin no. i is calculated from the formula,

x_{i} = 2^{i / m} \cdot x_{0}

where m is the number of bins per octave and x_0 is the lower-edge value of the first bin.

Args:
bins: int

Total number of bins

bins_per_oct: int

Number of bins per octave

min_value: float

Left edge of first bin

label: str

Descriptive label. Optional

Attributes:
bins: int

Total number of bins

bins_per_oct: int

Number of bins per octave

x_min: float

Left edge of first bin

label: str

Descriptive label

bin(x, truncate=False, closed_right=False)[source]

Get bin number corresponding to a given value.

By default bins are closed on the left and open on the right, i.e., [a,b). Use the argument closed_right to reverse this.

If the value lies outside the axis range, a negative bin number or a bin number above N-1 will be returned. This behaviour can be changed using the argument ‘truncate’.

Args:
x: array-like

Value

truncate: bool

Return 0 if x is below the lower axis boundary and N-1 if x is above the upper boundary. Default is False.

closed_right: bool

If False, bin is closed on the left and open on the right. If True, bin is open on the left and closed on the right. Default is False.

Returns:
b: array-like

Bin number

Example:
>>> from ketos.audio.utils.axis import Log2Axis
>>> ax = Log2Axis(bins=4*8, bins_per_oct=8, min_value=200.)
>>> ax.bin([400.,800.])
array([ 8, 16])
low_edge(b)[source]

Get the lower-edge value of a given bin.

Args:
b: array-like

Bin number.

Returns:
x: array-like

Lower-edge bin value

Example:
>>> from ketos.audio.utils.axis import Log2Axis
>>> ax = Log2Axis(bins=4*8, bins_per_oct=8, min_value=200.)
>>> ax.low_edge([0,16])
array([200., 800.])
ticks_and_labels()[source]

Create ticks and labels for drawing the axis.

Returns:
ticks: numpy.array

Tick positions

labels: list(str)

Labels

ketos.audio.utils.axis.bin_number(x, pos_func, bins, truncate=False, closed_right=False)[source]

Compute bin number corresponding to a given value.

If the value lies outside the axis range, a negative bin number or a bin number above N-1 will be returned. This behaviour can be changed using the argument ‘truncate’.

Args:
x: array-like

Value

pos_func: function

Calculates the position on the axis of any given input value.

bins: int

Number of bins

truncate: bool

Return 0 if x is below the lower axis boundary and N-1 if x is above the upper boundary. Default is False.

closed_right: bool

If False, bin is closed on the left and open on the right. If True, bin is open on the left and closed on the right. Default is False.

Returns:
b: array-like

Bin number