ajyoon / blur

a chance art toolkit

blur

0.5 (dev)

blur is a suite of tools for Python to help make using chance operations in algorithmic art easier.

>>> from blur.markov.graph import Graph
>>> word_distance_weights = {-5: 1, -1: 2, 1: 8, 3: 3}
>>> graph = Graph.from_string('blur is a suite of tools '
... 'to help make using chance operations in algorithmic '
... 'art easier', word_distance_weights)
>>> print(' '.join(graph.pick().value for i in range(8)))
using chance algorithmic in algorithmic art easier blur

blur allows you to easily implement complex chance generated elements in your works without getting bogged down in the boilerplate and the nitty-gritty math. Besides Python (version 2.7 or 3.3+), it has no dependencies, making it easy to incorporate into your project.

Installation

To install blur use pip from the command line:

pip install blur

You can read the latest (unstable) documentation for blur online here.

---

Contributing

Feature requests, bug reports, and pull requests are all welcomed! Head on over to https://github.com/ajyoon/blur and get in touch.

See CONTRIBUTING.md for help getting started.

blur's Issues

Graph.from_string() and Graph.from_file() should allow custom word-group character replacement

Currently, Graph.from_string() and Graph.from_file() allow words to be grouped together in one Node via a simple markup format of angle brackets. Working on using this in an HTML context introduces unnecessary pain points. Users should be able to specify as a method argument their own markup flag for this to allow easy flexibility.

Change Node.name to Node.value

This is long overdue - name is misleading and confusing, since it really is an attribute for the value of the node (or rather, the state of the graph at that point)

rand.weighted_shuffle() behavior not as expected

from blur.rand import weighted_shuffle

original_list = [
    ('a', 0, 0),
    ('b', 80, 5),
    ('c', 0, 0),
    ('d', 0, 0),
    ('e', 0, 0)]

positions = {
    'a': [],
    'b': [],
    'c': [],
    'd': [],
    'e': []}

for i in range(10):
    test_list = original_list[:]
    shuffled = weighted_shuffle(original_list)
    # Find where things landed
    for index, value in enumerate(shuffled):
        positions[value].append(index)

print(positions)

Gives output:

{'a': [4, 0, 2, 0, 4, 4, 0, 0, 4, 2],
 'b': [1, 1, 1, 1, 1, 1, 1, 1, 1, 1],
 'c': [0, 4, 0, 4, 0, 0, 3, 4, 0, 0],
 'd': [2, 3, 4, 2, 2, 3, 2, 3, 2, 3],
 'e': [3, 2, 3, 3, 3, 2, 4, 2, 3, 4]}

It would be expected that items a, c, d, and e would be uniformally distributed evenly across indexes 0, 1, 2, 3, and 5 while items b would be always placed at index 4.

Investigating cause... the code in this method is awfully smelly anyway. Hoping to fix in 0.2

Implement __str__() for markov classes

Current legible printing of graphs, nodes, and links involves a lot of boilerplate for extracting names and contents with loops and such; it would be very useful to have built-in __str__() methods for these classes!

Improve iching

The iching API leaves a lot to be desired.

• get_hexagram should be renamed get_hexagrams (plural) since most often it is returning tuples of integers
• There should be an easier interface/function for getting hexagrams and retrieving their hexagram characters, names, etc without doing a verbose dictionary lookup to hexagrams[...]
• There should be a way to access data on the hexagram lines (data currently stored in _hexagram_dict) and a way to quickly view the line deltas in hexagram pairs
• There should be a way to run actual simulations of divination methods, not just probabilistic approximations

ReadTheDocs latest doesn't point to dev

Something must be configured wrong. Investigate with more sleep...

Add private utility functions to validate different types of weight lists

Then use these within relevant methods, then refactor tests to localize these types of failure checks more cleanly.

Add overview of package contents page

Should contain a summary of the different modules, classes, methods, use cases, etc.

This will be helpful for new users to quickly figure out which components of the package are relevant to their needs.

Make `Graph.merge_nodes` merge links pointing to the node being deleted

Came up while writing documentation, this behavior is more intuitive than the existing:

>>> from blur.markov.graph import Graph
>>> from blur.markov.nodes import Node
>>> node_1 = Node('One')
>>> node_2 = Node('Two')
>>> node_3 = Node('Three')
>>> node_1.add_link(node_3, 7)
>>> node_2.add_link(node_1, 1)
>>> node_2.add_link(node_2, 3)
>>> node_3.add_link(node_2, 5)
>>> graph = Graph([node_1, node_2, node_3])
>>> print([node.name for node in graph.node_list])
['One', 'Two', 'Three']
>>> graph.merge_nodes(node_2, node_3)
>>> print([node.name for node in graph.node_list])
['One', 'Two']
>>> for link in graph.node_list[1].link_list:
...     print(link.target.name, link.weight)
One 1
Two 8
>>> for link in graph.node_list[0].link_list:
...     print(link.target.name, link.weight)
# It would be expected that node 'One' now points to node 'Two'
# but in the present state node 'One' now has no links

Fix confusing documentation around weights and weight tuples

The current docs explaining weights and weight tuples have a lot of ambiguity around the word 'weight'. For instance, this gem from rand.weighted_rand():

Args:
        weights: (List[(float, float)]): the list of weights where each weight
            is a ``tuple`` of form ``(float, float)`` corresponding to
            ``(outcome, weight)``. All weights outcome values must be numbers.
            Weights with weight ``0`` or less will have no chance to be
            rolled. Must be sorted in increasing order of outcomes.

Note that the word 'weight' is used to mean two completely distinct things - one referring to the weight tuple itself, and one referring to the weight of that tuple. This could be easily resolved by replacing the latter with the word 'strength'. For example:

Args:
        weights: (List[(float, float)]): the list of weights where each weight
            is a ``tuple`` of form ``(float, float)`` corresponding to
            ``(outcome, strength)``. All weights outcome values must be numbers.
            Weights with strength ``0`` or less will have no chance to be
            rolled. Must be sorted in increasing order of outcomes.

The docs would be much easier to understand if this change were made throughout.