View on GitHub

The Spacetime Project

Basic installation and usage instructions for Spacetime

Spacetime logo


Spacetime Documentation

The main objective of the spacetime python is to make tasks like loading, rescaling, merging, and conducting mathmatical operations on spatiotemporal (or other D-dimensional data sets) easier for the user by providing a set of concise yet powerful functions. Spacetime opperations utilize a cube-like structure for all data sets that makes storing and manipulating large D-dimensional datasets more efficient. For scientists working with spatiotemporal data (such as climate or weather data sets) spacetime is an ideal platform that allows the user to focus on the science rather than the coding. Spacetime is in the beta stage (version number = 0.0.1) and additional functionality will be added on a regular basis. The current functionality of spacetime is below:

Spacetime Objects:

fileObj.methods():

Description: File objects are the output of the read_data() fucntion. They are essentially a list object of all the raster files that were read in. All methods of a file object result in a list of outputs (one for each raster in the object). File objects can contain rasters of various scales, time lengths, and sizes. The functions raster_scale() and raster_align() may be used on file objects to return a file object that contains aligned and trimmed rasters. General output of methods: A list of output objects of the length of the list of raster objects loaded by read_data().

# extract list of raster data cubes from file object
dataArray = ds.get_data_array()

cubeObj.methods():

Description: Cube objects are the main operational unit in the spacetime package. Cube objects are cleaned, aligned D-dimensioal cube-liek datasets that minamally contain a data cube, a time dimension, and latitude and longitude (y, x) dimensions. They are the output of the make_cube() function. Cube objects may be passed to functions like cube_smasher(), cube_plotter() etc. to be opperated on mathmatically or functionally and visulized. General output of methods: The associated value for the cube object as specified by the method.

# extract latitude dimension from cube object
lat = ds.get_lat()

spacetime Functions:

Description: spacetime functions conduct scaling, plotting, writing and other tasks on spacetime objects.

read_data(data=None)

# read in data set from raster files
ds = read_data(data=rasterList)

make_cube(data = None, fileName = None, organizeFiles="filestotime", organizeBands="bandstotime", varNames=None, timeObj=None, inMemory = False)

make_cube(data = fileObject, fileName = "test.nc4", organizeFiles = "filestovar", varNames = ["SpA","SpB"], timeObj = years)

raster_align(data=None, resolution=None, SRS=None, noneVal=None, algorithm="near")

dsAligned = raster_align(data=fileObj, resolution=.08, SRS=4326, noneVal=-9999)

raster_trim(data=None)

dsTrimmed = raster_trim(data=cubeObj)

cube_time(start, length, scale)

yearObj = cube_time(start="2000", length=202, scale = "year")

scale_time(cube, scale, method)

scale_time(cube=ds, scale="month", method="max")

select_time(cube, range="entire", scale = None, element=None)

select_time(cube=cubeObj, range=['2000-02-29', '2000-04-30'], scale = "month", element=4)

expand_time(cube, target_time, starting_scale = "month", target_scale = "day")

newCube = expand_time(cube = cubeObj, target_time = cube.get_time(), starting_scale = "month", target_scale = "day")

cube_smasher(function = None, eq = None, parentCube = None, **kwarg))

# mathmatical operations on two tif files
outputCube = cube_smasher(eq = "a + b ** c", a=cube1, b=cube2, c = 5, parentCube = cube1)


# conduct mathmatical operation on two cube objects
outputCube = cube_smasher(eq = "a + b", a=obj1, b=obj2, parentCube = obj1)

cube_to_dataframe(cube)

# convert a cube into a dataframe
df = cube_to_dataframe(cube=cubeObject)

plot_cube(cube, type="space", variable = None, summary="mean", showPlot = True)

df = plot_cube(cube=x, variable="B", type="space", summary = "max", showPlot = True)

load_cube(file)

# a cube object file
newCube = "myDirectory/myCubeFile.nc4"

# load the cube object back in
ds = load_cube(file = newCube)

Example Workflow:

import spacetime as sp

# input file names
file1 = "file1.tif"
file2 = "file2.tif"

data = [file1, file2]

# read data from list of files and make a spaceTime file object
ds = read_data(data)
##########################################################################

# align the rasters to the same epsg codes and grid size
newObj = raster_align(data=ds)

# trim the rasters to the same greatest common bounding box
trimmed = raster_trim(newObj)

# create spacetime time object
yearObj = cube_time(start="2000", length=101, scale = "day")

# make the alinged file object into a cube with a time element (writes the new file to disk)
ds = make_cube(data = trimmed, fileName = "test.nc4", organizeFiles = "filestovar", timeObj = yearObj)

# scale time does basic temporal summary (here we are doing monthly means)
x = scale_time(cube=ds, scale="month", method="mean")

# selects ranges of time and/or slices at different scales 
# here we extract aprils between '2000-02-29' and '2000-04-30'
y = select_time(cube=x, range=['2000-02-29', '2000-04-30'], scale = "month", element=4)

# cube smasher does mathmatical/function operations on a cube or cubes (times 5)
answer = cube_smasher(eq = "a * c", a = y, c = 5, parentCube = y)

# plot the cube and output the data set in dataframe format that made the plot
t=plot_cube(cube=x, variable="B", type="space", summary = "max", showPlot = True)

# convert a cube into a dataframe
df = cube_to_dataframe(cube=x)

# write out our final cube as a .cd4 file
ds = make_cube(data = x, fileName = "testCube.nc4")

# pull in the file name of our newly created cube
newCube = "/Users/pburnham/Documents/GitHub/barra_python/testCube.nc4"

# load the cube object back in
ds = load_cube(file = newCube)