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 converts different inputs to numpy datetime64 arrays or instances.
  • to_timedelta64 converts different inputs to numpy timedelta64 arrays or instances.

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)

Dimension Selection

Most of DASCore’s processing methods can be applied along any dimension. Typically, the dimension is selected with keyword, and the method specific data are passed as values. For example, applying pass_filter to a patch with distance and time dimensions works like this:

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 depends on the function, e.g. both frequency and period might make sense in the example above. Being explicit with units helps, but be sure to read the docs!

Units

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

from dascore.units import get_quantity, m, ft

meters = get_quantity("meters")

# now meters should be equal to 1 meter
assert meters == 1 * m

# convert 10 meters to ft
ten_m = meters * 10
print(ten_m.to(ft))

# get_quantity can handle a lot of complexity!
quantity = get_quantity("10 * (PI / 10^3) (millifurlongs)/(tesla)")
print(quantity)
32.808398950131235 ft
0.01 PI * mfur / T

Many of DASCore’s Patch methods 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.