Concepts

This page highlights a few core DASCore concepts.

Data structures

For most uses of DASCore, only two data structures are directly involved. These are the Patch and the Spool.

The Patch contains a contiguous block of N dimensional data and metadata. The Spool manages a group of Patchs. These can be in memory, on disk, or a remote resource.

Figure 1: Patch (blue) and Spool (red)

You will read more about Patches and Spools later on in the tutorial.

Time

Any expression of time should use numpy time constructs, which include datetime64 and timedelta64.

For example:

import numpy as np

# create a datetime64 with a very precise time string
time_1 = np.datetime64('2022-01-01T15:12:11.172455')

# create a new time by adding some time to time_1
time_2 = time_1 + np.timedelta64(60, 's')

# get the number of hour separating them:
delta_1 = (time_2 - time_1) / np.timedelta64(1, 'h')

DASCore provides two convenience functions for working with times:

to_datetime64 which tries to convert most types of inputs expressing date times to the proper numpy type. to_timedelta64 performs a similar function for timedeltas. For example:

import dascore as dc

# convert a time string to a datetime64 object.
time_1 = dc.to_datetime64('2022-01-01T12:12:12.1212')

# convert a timestamp (seconds from 1970-01-01) to a datetime object
time_2 = dc.to_datetime64(610243200)

In general, you should try to be as explicit as possible and use numpy’s time constructs directly, but the dascore time functions provide a helpful way to sanitize a variety of time inputs.

Dimension Selection

Most of DASCore’s processing methods can be applied along any dimension. For example, pass_filter can be applied along any dimension by passing a range and dimension name:

import dascore as dc
patch = dc.get_example_patch()

filtered_time = patch.pass_filter(time=(1, 5))
filtered_distance = patch.pass_filter(distance=(0.1, 0.2))

However, the meaning of the values (ie frequency vs period) depends on the function, so be sure to read the docs!

Units

DASCore provides first class support for units through the units module. Units (or rather quantities) can be created with get_quantity.

from dascore.units import get_quantity

meters = get_quantity("meters")

ten_m = meters * 10
print(ten_m)

# Or by direct string parsing, which can handle a lot of complexity
quantity = get_quantity("10 * (PI / 10^3) (millifurlongs)/(tesla)")
print(quantity)
10 m
0.01 PI * mfur / T

Many of DASCore’s processing functions support units/quantities as shown above. See the units section in the Patch tutorial for examples.

Note

DASCore uses the unit library Pint for unit parsing/conversions. See its documentation for more on how units and quantities work.