nvalues 1.0.0b1

Manages n-dimensional volumes of data

NValues

NValues is a Python package for working with n-dimensional volumes of data.

Installation

NValues requires Python 3.9 or later and can be installed via PyPI:

pip install nvalues

Usage

For example, to create a spreadsheet-like grid of float values with alphabetic x keys and integer y keys:

from nvalues import Volume

grid = Volume[tuple[str, int], float]()
grid["A", 0] = 1.2
grid["B", 1] = 1.4
grid["C", 2] = 1.6

print(grid["A", 0])
# 1.2

See the Volume class for more detail, or if you don't need more than five dimensions then see the Line, Grid, Cube, Tesseract or Penteract wrapper classes for an easier life.

The Volume class

The Volume class represents a strongly-typed n-dimensional volume of values.

Construction

Volume requires two generic types:

1. Tuple of key types
2. Value type

For example:

from nvalues import Volume

# A dictionary with integer keys and string values:
volume = Volume[tuple[int], str]()

# A grid with integer coordinates and string values:
volume = Volume[tuple[int, int], str]()

# A spreadsheet of floats with horizontal alphabetic keys and
# vertical integer keys:
volume = Volume[tuple[str, int], float]()

# A cube of booleans with integer x, string y and float z keys:
volume = Volume[tuple[int, str, float], bool]()

An optional default value can be specified here too:

from nvalues import Volume

volume = Volume[tuple[int, int], str](default_value="")

If you request a key that doesn't exist then this default value will be returned. If you request a key that doesn't exist without a default value set then the volume will raise nvalues.exceptions.NKeyError.

A default value can be set after construction via the default property and cleared by calling clear_default().

Usage

Values are read and set via their keys. For example:

from nvalues import Volume

volume = Volume[tuple[int, int], str]()
volume[0, 0] = "zero"
print(volume[0, 0])
# "zero"

The Line class

The Line class is a wrapper around the Volume class to simplify the creation of one-dimensional volumes.

Construction

Line requires two generic types:

1. Key type
2. Value type

For example, to create a Line with integer keys and string values:

from nvalues import Line

line = Line[int, str]()

See the base Volume class for more construction detail.

Usage

Values can be read and set via their keys as described in the base Volume class, but Line also provides get() and set() helper functions:

from nvalues import Line

line = Line[int, str]()
line.set(0, "zero")
print(line.get(0))
# "zero"

The Grid class

The Grid class is a wrapper around the Volume class to simplify the creation of two-dimensional volumes.

Construction

Grid requires three generic types:

1. x key type
2. y key type
3. Value type

For example, to create a Grid with x string keys, y integer keys and boolean values:

from nvalues import Grid

grid = Grid[str, int, bool]()

See the base Volume class for more construction detail.

Usage

Values can be read and set via their keys as described in the base Volume class, but Grid also provides get() and set() helper functions:

from nvalues import Grid

grid = Grid[str, int, bool]()
grid.set("A", 0, True)
print(grid.get("A", 0))
# True

The Cube class

The Cube class is a wrapper around the Volume class to simplify the creation of three-dimensional volumes.

Construction

Cube requires four generic types:

1. x key type
2. y key type
3. z key type
4. Value type

For example, to create a Cube with x string keys, y integer keys, z float keys and boolean values:

from nvalues import Cube

cube = Cube[str, int, float, bool]()

See the base Volume class for more construction detail.

Usage

Values can be read and set via their keys as described in the base Volume class, but Cube also provides get() and set() helper functions:

from nvalues import Cube

cube = Cube[str, int, float, bool]()
cube.set("A", 0, 1.2, True)
print(cube.get("A", 0, 1.2))
# True

The Tesseract class

The Tesseract class is a wrapper around the Volume class to simplify the creation of four-dimensional volumes.

Construction

Tesseract requires five generic types:

1. w key type
2. x key type
3. y key type
4. z key type
5. Value type

For example, to create a Tesseract with w string keys, x string keys, y int keys, z float keys and boolean values:

from nvalues import Tesseract

tesseract = Tesseract[str, str, int, float, bool]()

See the base Volume class for more construction detail.

Usage

Values can be read and set via their keys as described in the base Volume class, but Tesseract also provides get() and set() helper functions:

from nvalues import Tesseract

tesseract = Tesseract[str, str, int, float, bool]()
tesseract.set("A", "B", 0, 1.2, True)
print(tesseract.get("A", "B", 0, 1.2))
# True

The Penteract class

The Penteract class is a wrapper around the Volume class to simplify the creation of five-dimensional volumes.

Construction

Penteract requires six generic types:

1. v key type
2. w key type
3. x key type
4. y key type
5. z key type
6. Value type

For example, to create a Tesseract with v integer keys, w string keys, x string keys, y int keys, z float keys and boolean values:

from nvalues import Penteract

penteract = Penteract[int, str, str, int, float, bool]()

See the base Volume class for more construction detail.

Usage

Values can be read and set via their keys as described in the base Volume class, but Penteract also provides get() and set() helper functions:

from nvalues import Penteract

penteract = Penteract[int, str, str, int, float, bool]()
penteract.set(3, "A", "B", 0, 1.2, True)
print(penteract.get(3, "A", "B", 0, 1.2))
# True

Support

Please raise bugs, feature requests and ask questions at cariad/nvalues/issues.

The Project

NValues is © 2022 Cariad Eccleston and released under the MIT License at cariad/nvalues.

The Author

Hello! 👋 I'm Cariad Eccleston and I'm a freelance backend and infrastructure engineer in the United Kingdom. You can find me at cariad.earth, github/cariad, linkedin/cariad and on Mastodon at @[e-mail].