Concepts

This page highlights some concepts helpful for working with DASCore.

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 Patches. 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 an iso8601 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 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 info on units and quantities.