Skip to main content

Convenience class for doing maths with explicit coordinates

Project description

coordinates

Build Status

Convenience class for dealing with coordinates which need both maths and explicit ordering.

Supports python 3.4+

Motivation

Numpy arrays are great for doing maths with coordinates stored as arrays.

Dicts are great for dealing with coordinate systems where the order keeps changing (e.g. between C and Fortran order).

But what if you want both?

(Note: if you're doing lots of maths... stick with numpy)

Installation

pip install coordinates

Usage

Coordinates are Mappings (i.e. dict-like). They don't expose an interface for mutation, but we're all consenting adults so if you really want to modify the internal _dict, I won't stop you.

Instantiation

They can be instantiated in any of the ways a dict can (from another Mapping, a sequence of pairs, some keyword arguments, or a mixture of the above).

from coordinates import Coordinate

Coordinate({'x': 1, 'y': 2})
Coordinate({'x': 1}, y=2)
Coordinate([('x', 1), ('y', 2)])
Coordinate(x=1, y=2)

If an order is defined (more on this later), you can also instantiate a Coordinate from a single argument which is a sequence, or from a number of *args.

Coordinate([1, 2], order='xy')
Coordinate(1, 2, order='xy')

Coordinate.default_order = 'xy'
Coordinate([1, 2])
Coordinate(1, 2)

Because Mappings can be instantiated from other Mappings, you can "extend" existing coordinates into new dimensions.

coord_2d = Coordinate(x=1, y=2)
coord_3d = Coordinate(coord_2d, z=3)

Finally, many Coordinates can be instantiated at once (with lazy evaluation) using from_sequence:

Coordinate.from_sequence([(1, 2), (3, 4)], order='xy')
Coordinate.from_sequence([{'x': 1, 'y': 2}, {'x': 3, 'y': 4}], z=10)
# N.B. `order`-dependent argument cannot be mixed with `**kwargs`

Maths

Coordinates do maths like you might expect them to, where the other operand is anything dict-like with the same keys, or a number.

coord = Coordinate(x=1, y=2, z=3)

coord * 2 == Coordinate(x=2, y=4, z=3)
>>> True

coord ** 2 == Coordinate(x=1, y=4, z=9)
>>> True

coord + coord == Coordinate(x=2, y=4, z=3)
>>> True

coord += 1  # coord is a reference to a new object; no mutation
coord == Coordinate(x=2, y=3, z=4)
>>> True

abs(Coordinate(x=-10, y=10)) == Coordinate(x=10, y=10)
>>> True

import math
math.ceil(Coordinate(x=0.5)) == Coordinate(x=1)
>>> True

math.floor(Coordinate(x=0.5)) == Coordinate(x=0)
>>> True

They also have some convenience methods for getting the sum, product or norm of their keys.

coord.sum() == 9
>>> True

coord.prod() == 24
>>> True

Coordinate(x=3, y=4).norm(order=2) == 5
>>>True

Ordering

You can get the keys, values or items of the Coordinate in a specific order:

coord.to_list('yxz') == [2, 1, 3]
>>> True

list(coord.keys('yxz')) == ['y', 'x', 'z']
>>> True

The default order for a single instance can be given on instantiation, or mutated (this does not affect equality).

The default order for all Coordinates can be set on the class. This affects existing instances, but does not override their order if it was set explicitly.

If neither an instance order or a class default_order is set, it falls back to reverse lexicographic.

coord3 = Coordinate(x=1, y=2, z=3, order='zxy')
coord3.order = 'yzx'

Coordinate.default_order = 'xyz'

Subclassing

If you're working in one space, the spaced_coordinate factory can create custom subclasses with a fixed set of keys and optionally a default order.

from coordinates import spaced_coordinate
CoordinateXYZC = spaced_coordinate('CoordinateXYZC', 'xyzc')

# this will raise a ValueError
CoordinateXYZC(x=1, y=2, z=3)

Or you can subclass Coordinate directly.

Value access

Coordinate values can be accessed with dict-like syntax (coord['x'], coord.get('y', 2)) or, for convenience, attribute-like (coord.z) if the keys are strings.

Note

If you don't want the order-related functionality for another application, the base class MathDict is implemented here too.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
coordinates-0.2.0-py2.py3-none-any.whl (8.1 kB) Copy SHA256 hash SHA256 Wheel py2.py3
coordinates-0.2.0.tar.gz (10.0 kB) Copy SHA256 hash SHA256 Source None

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page