Tutorial: utils

Utils and Intervals Tutorial

This tutorial explores the utilities and intervals features from the thalesians.adiutor.utils and thalesians.adiutor.intervals modules. These modules provide various utility functions and classes for batching, interval manipulation, and custom data structures like DiagonalArray and SubdiagonalArray.

---

1. Overview of utils

Key Features

• Batching: Create batches from sequences.
• Interval Generation: Generate sequences of intervals with customizable boundaries.
• Custom Arrays: Manipulate diagonal and subdiagonal data structures efficiently.

---

2. Batching

Functions

xbatch

• Description: Generates an iterator over batches of a specified size from an iterable.
• Example:

import thalesians.adiutor.utils as utils

# Generate batches of size 2 from a range
for batch in utils.xbatch(2, range(10)):
    print(list(batch))

batch

• Description: Returns a list of batches of a specified size.
• Example:

# Generate batches of size 3
result = utils.batch(3, [1, 2, 3, 4, 5, 6, 7])
print(result)

---

3. Interval Manipulation

Function: utils.intervals

• Description: Creates a sequence of intervals between start and end.
• Parameters:
  • start: Start point (e.g., numeric, date, or datetime).
  • end: End point.
  • delta: Step size.
  • intervals_right_closed: Whether the intervals are right-closed.

Example: Numeric Intervals

import thalesians.adiutor.utils as utils

intervals = utils.intervals(start=0, end=15, delta=5, intervals_right_closed=False)
for interval in intervals:
    print(interval)

Example: Date Intervals

import datetime as dt

intervals = utils.intervals(
    start=dt.date(2022, 1, 1),
    end=dt.date(2022, 1, 10),
    delta=dt.timedelta(days=3),
    intervals_right_closed=True
)
for interval in intervals:
    print(interval)

---

4. Bracketing

Function: utils.bracket

• Description: Divides data into brackets based on interval sizes.

Example:

data = [10, 20, 30, 40, 50, 60]
intervals, indices = utils.bracket(data, 15, 20)

for interval in intervals:
    print(interval)
print(indices)

---

5. Custom Arrays

DiagonalArray

Description

A data structure optimized for diagonal elements.

Example:

from thalesians.adiutor.utils import DiagonalArray

diagonal = DiagonalArray(3)
diagonal[0, 0] = 1
diagonal[1, 1] = 2
diagonal[2, 2] = 3

print(list(diagonal.items()))

SubdiagonalArray

Description

A data structure optimized for subdiagonal elements.

Example:

from thalesians.adiutor.utils import SubdiagonalArray

subdiagonal = SubdiagonalArray(3)
subdiagonal[1, 0] = 4
subdiagonal[2, 0] = 5
subdiagonal[2, 1] = 6

print(list(subdiagonal.items()))

---

6. Unit Test Examples

Testing Batching

import unittest
import thalesians.adiutor.utils as utils

class TestBatching(unittest.TestCase):
    def test_batch(self):
        result = utils.batch(3, [1, 2, 3, 4, 5, 6, 7])
        self.assertEqual(result, [[1, 2, 3], [4, 5, 6], [7]])

if __name__ == '__main__':
    unittest.main()

Testing Intervals

import datetime as dt
import unittest
from thalesians.adiutor.utils import intervals

class TestIntervals(unittest.TestCase):
    def test_date_intervals(self):
        result = intervals(
            start=dt.date(2022, 1, 1),
            end=dt.date(2022, 1, 10),
            delta=dt.timedelta(days=3),
            intervals_right_closed=True
        )
        self.assertEqual(len(result), 3)

if __name__ == '__main__':
    unittest.main()

---

7. Conclusion

The utils and intervals modules provide robust tools for data batching, interval manipulation, and specialized array handling. These utilities can help streamline common tasks in data analysis and scientific computing.