CartographySelector

class auxjad.CartographySelector(contents: list, *, decay_rate: float = 0.75)

A selector used to store, manipulate, and select objects using a weighted function constructed with a fixed decay rate. The decay rate represents the ratio of probabilities of any index given the probability of the preceding one. For instance, if the decay rate is set to 0.75 (which is its default value), the probability of the element in index 1 of the input list being selected is \(75\%\) the probability of the element in index 0, and the probability of the element in index 2 is \(56.25\%\) (i.e. \(0.75^2\)) the probability of the element in index 0. The probability \(P(n)\) of the \(n\)-th element can thus be expressed as a relation to the probability of another element \(k\) indexes apart using:

\[P(n) = (3/4)^k \times P(n-k)\]

This is the selector used in my Cartography series of compositions.

Basic usage:

The selector should be initialised with a list of objects. The elements of this list can be of any type.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]

Calling the selector will output one of its elements, selected according to its weight function.

>>> selector()
2

The default decay rate is 0.75; that is, the weight of any given elements is the weight of the previous one multiplied by 0.75. The weights are associated with the index position, not the elements themselves.

>>> selector.weights
[1.0, 0.75, 0.5625, 0.421875, 0.31640625]

By default, only the weight function (defined by the decay rate) is taken into consideration when selecting an element. This means that repeated elements can appear, as shown below.

>>> result = ''
>>> for _ in range(30):
...     result += str(selector())
>>> result
203001402200011111101400310140

len() function:

Applying the len() function to the selector will return the length of the input list.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> len(selector)
5

next() function:

Alternatively, use the next() function or __next__() method to get the next result.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.__next__()
1
>>> next(selector)
0

__call__() and argument no_repeat:

Calling the selector with the optional keyword argument no_repeat set to True will forbid immediate repetitions among consecutive calls.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> result = ''
>>> for _ in range(30):
...     result += str(selector(no_repeat=True))
>>> result
210421021020304024230120241202

decay_rate:

The keyword argument decay_rate can be used to set a different decay rate when creating a selector.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4],
...                                       decay_rate=0.5,
...                                       )
>>> selector.weights
[1.0, 0.5, 0.25, 0.125, 0.0625]

The decay rate can also be set after the creation of a selector using, the property decay_rate.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.decay_rate = 0.2
>>> selector.weights
[1.0, 0.2, 0.04000000000000001, 0.008000000000000002,
0.0016000000000000003]
>>> result = ''
>>> for _ in range(30):
...     result += str(selector())
>>> result
'000001002100000201001030000100'

drop_first_and_append():

This is a type of content transformation, it drops the first element of contents, shifts all others leftwards, and appends the new element to the last index.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.drop_first_and_append(5)
>>> selector.contents
[1, 2, 3, 4, 5]
>>> selector.drop_first_and_append(42)
>>> selector.contents
[2, 3, 4, 5, 42]

drop_n_and_append():

This is a type of content transformation similar to drop_first_and_append(), it drops the element at index n of contents, shifts all the next elements one position lefwards, and appends the new element at the last index.

>>> selector = auxjad.CartographySelector([10, 7, 14, 31, 98])
>>> selector.contents
[10, 7, 14, 31, 98]
>>> selector.drop_n_and_append(100, 2)
>>> selector.contents
[10, 7, 31, 98, 100]

drop_last_and_prepend():

A type of content transformation, it drops the last element of contents, shifts all others rightwards, and then prepends the new element to the first index.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.drop_last_and_prepend(-1)
>>> selector.contents
[-1, 0, 1, 2, 3]
>>> selector.drop_last_and_prepend(71)
>>> selector.contents
[71, -1, 0, 1, 2]

rotate():

Rotation is another type of content transformation. It rotates all elements rightwards, moving the last element to the first index. If the optional keyword argument anticlockwise is set to True, the rotation will be in the opposite direction.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.rotate()
>>> selector.contents
[1, 2, 3, 4, 0]
>>> selector.rotate(anticlockwise=True)
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.rotate(anticlockwise=True)
>>> selector.contents
[1, 2, 3, 4, 0]

mirror_swap():

The mirror swap transformation swaps takes an input index and swaps the element at tit with its complementary element. Complementary elements are defined as the pair of elements which share the same distance from the centre of the contents (in terms of number of indeces), and are located at either side of this centre.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.mirror_swap(0)
>>> selector.contents
[4, 1, 2, 3, 0]
>>> selector.mirror_swap(0)
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.mirror_swap(3)
>>> selector.contents
[0, 3, 2, 1, 4]
>>> selector.mirror_swap(2)
>>> selector.contents
[0, 3, 2, 1, 4]

mirror_random_swap():

A type of content transformation which will apply mirror_swap() to a random pair of complementary elements. In case of a selector with an odd number of elements, this method will never pick the element at the central index since that is the pivot point of the operation and it would not result in any changes.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.mirror_random_swap()
>>> selector.contents
[4, 1, 2, 3, 0]
>>> selector.mirror_random_swap()
>>> selector.contents
[4, 3, 2, 1, 0]
>>> selector.mirror_random_swap()
>>> selector.contents
[4, 1, 2, 3, 0]

shuffle():

The method shuffle() will shuffle the position of the elements of the selector’s contents.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4])
>>> selector.contents
[0, 1, 2, 3, 4]
>>> selector.shuffle()
>>> selector.contents
[1, 4, 3, 0, 2]

contents:

The contents of a selector can also be altered after it has been initialised using the contents property. The length of the contents can change as well.

>>> selector = auxjad.CartographySelector([0, 1, 2, 3, 4],
...                                       decay_rate=0.5,
...                                       )
>>> len(selector)
5
>>> selector.weights
[1.0, 0.5, 0.25, 0.125, 0.0625]
>>> selector.contents = [10, 7, 14, 31, 98, 47, 32]
>>> selector.contents
[10, 7, 14, 31, 98, 47, 32]
>>> len(selector)
7
>>> selector.weights
[1.0, 0.5, 0.25, 0.125, 0.0625, 0.03125, 0.015625]

previous_result and previous_index:

Use the read-only properties previous_result and previous_index to output the previous result and its index.

>>> selector = auxjad.CartographySelector([10, 7, 14, 31, 98])
>>> selector()
14
>>> previous_index = selector.previous_index
>>> previous_index
2
>>> selector.previous_result
14

Slicing and indexing:

Instances of this class can be indexed and sliced. This allows reading, assigning, or deleting values from contents.

>>> selector = auxjad.CartographySelector([10, 7, 14, 31, 98])
>>> selector[1]
7
>>> selector[1:4]
[7, 14, 31]
>>> selector[:]
[10, 7, 14, 31, 98]
>>> selector()
31
>>> previous_index = selector.previous_index
>>> previous_index
3
>>> selector[previous_index]
31
>>> selector.contents
[10, 7, 14, 31, 98]
>>> selector[2] = 100
>>> selector.contents
[10, 7, 100, 31, 98]
>>> del selector[2:4]
>>> selector.contents
[10, 7, 98]

Methods

__call__(*[, no_repeat])	Calls the selection process and outputs one element of contents.
__delitem__(key)	Deletes one or more elements of contents through indexing or slicing.
__getitem__(key)	Returns one or more elements of contents through indexing or slicing.
__init__(contents, *[, decay_rate])	Initialises self.
__len__()	Returns the length of contents.
__next__()	Calls the selection process and outputs one element of contents.
__repr__()	Returns interpreter representation of contents.
__setitem__(key, value)	Assigns values to one or more elements of contents through indexing or slicing.
drop_first_and_append(new_element)	A type of content transformation, it drops the first element of contents, shifts all others leftwards, and appends the new element to the last index.
drop_last_and_prepend(new_element)	A type of content transformation, it drops the last element of contents, shifts all others rightwards, and then prepends the new element to the first index.
drop_n_and_append(new_element, n)	A type of content transformation similar to drop_first_and_append(), it drops the element at index n of contents, shifts all the next elements one position lefwards, and appends the new element at the last index.
mirror_random_swap()	A type of content transformation which will apply mirror_swap() to a random pair of complementary elements.
mirror_swap(index)	A type of content transformation which swaps takes an input index and swaps the element at tit with its complementary element.
rotate(*[, anticlockwise])	A type of content transformation, it rotates all elements rightwards, moving the last element to the first index.
shuffle()	Shuffles the position of the elements of contents.

Attributes

contents	The list from which the selector picks elements.
decay_rate	The decay rate represents the ratio of probabilities of any index given the probability of the preceding one.
previous_index	Read-only property, returns the index of the previously output element.
previous_result	Read-only property, returns the previously output element.
weights	Read-only property, returns the weight vector.

__call__(*, no_repeat: bool = False) → Any

Calls the selection process and outputs one element of contents.

__delitem__(key: int) → None

Deletes one or more elements of contents through indexing or slicing.

__getitem__(key: int) → Any

Returns one or more elements of contents through indexing or slicing.

__init__(contents: list, *, decay_rate: float = 0.75) → None

Initialises self.

__len__() → int

Returns the length of contents.

__next__() → Any

Calls the selection process and outputs one element of contents.

__repr__() → str

Returns interpreter representation of contents.

__setitem__(key: int, value: Any) → None

Assigns values to one or more elements of contents through indexing or slicing.

property contents: list

The list from which the selector picks elements.

property decay_rate: float

The decay rate represents the ratio of probabilities of any index given the probability of the preceding one. For instance, if the decay rate is set to 0.75 (which is its default value), the probability of the element in index 1 of the input list being selected is 0.75 the probability of the element in index 0, and the probability of the element in index 2 is 0.5625 (i.e. 0.75 squared) the probability of the element in index 0.

drop_first_and_append(new_element: Any) → None

A type of content transformation, it drops the first element of contents, shifts all others leftwards, and appends the new element to the last index.

drop_last_and_prepend(new_element: Any) → None

A type of content transformation, it drops the last element of contents, shifts all others rightwards, and then prepends the new element to the first index.

drop_n_and_append(new_element: Any, n: int) → None

A type of content transformation similar to drop_first_and_append(), it drops the element at index n of contents, shifts all the next elements one position lefwards, and appends the new element at the last index.

mirror_random_swap() → None

A type of content transformation which will apply mirror_swap() to a random pair of complementary elements. In case of a selector with an odd number of elements, this method will never pick the element at the central index since that is the pivot point of the operation and it would not result in any changes.

mirror_swap(index: int) → None

A type of content transformation which swaps takes an input index and swaps the element at tit with its complementary element. Complementary elements are defined as the pair of elements which share the same distance from the centre of the contents (in terms of number of indeces), and are located at either side of this centre.

property previous_index: Optional[int]

Read-only property, returns the index of the previously output element.

property previous_result: Any

Read-only property, returns the previously output element.

rotate(*, anticlockwise=False) → None

A type of content transformation, it rotates all elements rightwards, moving the last element to the first index. If the optional keyword argument anticlockwise is set to True, the rotation will be in the opposite direction.

shuffle() → None

Shuffles the position of the elements of contents.

property weights: list

Read-only property, returns the weight vector.