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,…,N1, counting from lower to higher values, where N is the number of bins.
By default, each bin represents a halfopen 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 N1 will be returned. This behaviour can be changed using the argument ‘truncate’.
 Args:
 x: arraylike
Value
 truncate: bool
Return 0 if x is below the lower axis boundary and N1 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: arraylike
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 6bin 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

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 N1 will be returned. This behaviour can be changed using the argument ‘truncate’.
 Args:
 x: arraylike
Value
 truncate: bool
Return 0 if x is below the lower axis boundary and N1 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: arraylike
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 loweredge value of a given bin.
 Args:
 b: arraylike
Bin number.
 Returns:
 x: arraylike
Loweredge 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 loweredge values of bins 1 and 4 >>> x = ax.low_edge([1,4]) >>> print(x) [14. 20.]

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 loweredge value of bin no. is calculated from the formula,
where is the number of bins per octave and is the loweredge 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 N1 will be returned. This behaviour can be changed using the argument ‘truncate’.
 Args:
 x: arraylike
Value
 truncate: bool
Return 0 if x is below the lower axis boundary and N1 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: arraylike
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])

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 N1 will be returned. This behaviour can be changed using the argument ‘truncate’.
 Args:
 x: arraylike
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 N1 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: arraylike
Bin number