spatial

Spatial data class for reading, writing and processing spatial data

• Can read ascii, netCDF4, HDF5 files

• Can read from an index of the above file types

• Can merge a list of spatial objects into a single object

• Can subset to a list of GRACE/GRACE-FO months

• Can calculate the mean field of a spatial object

• Can output spatial objects to ascii, netCDF4 or HDF5 files

Calling Sequence

Reading a netCDF4 file

from gravity_toolkit.spatial import spatial
grid = spatial().from_netCDF4(path_to_netCDF4_file)

Reading a HDF5 file

from gravity_toolkit.spatial import spatial
grid = spatial().from_HDF5(path_to_HDF5_file)

Reading an index file of netCDF4 files and then outputting as a single file

from gravity_toolkit.spatial import spatial
grid = spatial().from_index(path_to_index_file,'netCDF4')
grid.to_netCDF4(path_to_netCDF4_file)

Reading an index file of HDF5 files and subsetting to specific months

from gravity_toolkit.spatial import spatial
grid = spatial().from_index(path_to_index_file,'HDF5').subset(months)

Converting a dictionary object to a spatial object and removing the mean field

from gravity_toolkit.spatial import spatial
grid = spatial().from_dict(grid_dict)
grid.mean(apply=True)

Source code

General Attributes and Methods

class gravity_toolkit.spatial(**kwargs)

Data class for reading, writing and processing spatial data

Attributes:

data: np.ndarray

spatial grid data

mask: np.ndarray

spatial grid mask

lon: np.ndarray

grid longitudes

lat: np.ndarray

grid latitudes

time: np.ndarray

time variable of the spatial data

month: np.ndarray

GRACE/GRACE-FO months variable of the spatial data

fill_value: float or NoneType, default None

invalid value for spatial grid data

attributes: dict

attributes of spatial variables

filename: str

input or output filename

case_insensitive_filename(filename)

Searches a directory for a filename without case dependence

Parameters:

filename: str, io.IOBase, pathlib.Path or None

input filename

compressuser(filename=None)

Tilde-compresses a file to be relative to the home directory

Parameters:

filename: str or None, default None

output filename

from_ascii(filename, date=True, **kwargs)

Read a spatial object from an ascii file

Parameters:

filename: str

full path of input ascii file

date: bool, default True

ascii file has date information

compression: str or NoneType, default None

file compression type

• 'gzip'

• 'zip'

• 'bytes'

spacing: list, default [None,None]

grid step size [longitude,latitude]

extent: list, default [None,None,None,None]

spatial grid bounds [minimum longitude, maximum longitude, minimum latitude, maximum latitude]

nlat: int or NoneType, default None

length of latitude dimension

nlon: int or NoneType, default None

length of longitude dimension

columns: list, default [‘lon’,’lat’,’data’,’time’]

variable names for each column

header: int, default 0

Number of rows of header lines to skip

verbose: bool, default False

print file and variable information

from_netCDF4(filename, **kwargs)

Read a spatial object from a netCDF4 file

Parameters:

filename: str

full path of input netCDF4 file

date: bool, default True

netCDF4 file has date information

compression: str or NoneType, default None

file compression type

• 'gzip'

• 'zip'

• 'bytes'

varname: str, default ‘data’

name for data variable

lonname: str, default ‘lon’

name for longitude variable

latname: str, default ‘lat’

name for latitude variable

timename: str, default ‘time’

name for time-dimension variable

field_mapping: dict, default {}

mapping between output variables and input netCDF4

verbose: bool, default False

print file and variable information

from_HDF5(filename, **kwargs)

Read a spatial object from a HDF5 file

Parameters:

filename: str

full path of input HDF5 file

date: bool, default True

HDF5 file has date information

compression: str or NoneType, default None

file compression type

• 'gzip'

• 'zip'

• 'bytes'

varname: str, default ‘data’

name for data variable

lonname: str, default ‘lon’

name for longitude variable

latname: str, default ‘lat’

name for latitude variable

timename: str, default ‘time’

name for time-dimension variable

field_mapping: dict, default {}

mapping between output variables and input HDF5

verbose: bool, default False

print file and variable information

from_index(filename, **kwargs)

Read a spatial object from an index of ascii, netCDF4 or HDF5 files

Parameters:

filename: str

full path of index file

format: str or NoneType, default None

format of individual files within index

• 'ascii'

• 'netCDF4'

• 'HDF5'

date: bool, default True

files contains date information

sort: bool, default True

sort spatial objects by date information

**kwargs: dict

keyword arguments for input readers

from_list(object_list, **kwargs)

Build a sorted spatial object from a list of other spatial objects

Parameters:

object_list: list

list of spatial objects to be merged

date: bool, default True

files contains date information

sort: bool, default True

sort spatial objects by date information

clear: bool, default True

clear the list of spatial objects from memory

from_file(filename, format=None, date=True, **kwargs)

Read a spatial object from a specified format

Parameters:

filename: str

full path of input file

format: str or NoneType, default None

file format

• 'ascii'

• 'netCDF4'

• 'HDF5'

date: bool, default True

file contains date information

verbose: bool, default False

print file and variable information

**kwargs: dict

keyword arguments for input readers

from_dict(d, **kwargs)

Convert a dict object to a spatial object

Parameters:

d: dict

dictionary object to be converted

to_ascii(filename, **kwargs)

Write a spatial object to ascii file

Parameters:

filename: str

full path of output ascii file

date: bool, default True

spatial objects contain date information

verbose: bool, default False

Output file and variable information

to_netCDF4(filename, **kwargs)

Write a spatial object to netCDF4 file

Parameters:

filename: str

full path of output netCDF4 file

varname: str, default ‘z’

data variable name in netCDF4 file

lonname: str

longitude variable name in netCDF4 file

latname: str

latitude variable name in netCDF4 file

field_mapping: dict, default {}

mapping between input variables and output netCDF4

attributes: dict, default {}

output netCDF4 variable and file-level attributes

units: str or NoneType, default: None

data variable units

longname: str or NoneType, default: None

data variable unit description

time_units: str, default ‘years’

time variable units

time_longname: str, default ‘Date_in_Decimal_Years’

time variable unit description

title: str or NoneType, default None

title attribute of dataset

source: str or NoneType, default None

source attribute of dataset

reference: str or NoneType, default None

reference attribute of dataset

date: bool, default True

spatial objects contain date information

clobber: bool, default True

Overwrite an existing netCDF4 file

verbose: bool, default False

Output file and variable information

to_HDF5(filename, **kwargs)

Write a spatial object to HDF5 file

Parameters:

filename: str

full path of output HDF5 file

varname: str, default ‘z’

data variable name in HDF5 file

lonname: str

longitude variable name in HDF5 file

latname: str

latitude variable name in HDF5 file

field_mapping: dict, default {}

mapping between input variables and output HDF5

attributes: dict, default {}

output HDF5 variable and file-level attributes

units: str or NoneType, default: None

data variable units

longname: str or NoneType, default: None

data variable unit description

time_units: str, default ‘years’

time variable units

time_longname: str, default ‘Date_in_Decimal_Years’

time variable unit description

title: str or NoneType, default None

description attribute of dataset

source: str or NoneType, default None

source attribute of dataset

reference: str or NoneType, default None

reference attribute of dataset

date: bool, default True

spatial objects contain date information

clobber: bool, default True

Overwrite an existing HDF5 file

verbose: bool, default False

Output file and variable information

to_index(filename, file_list, format=None, date=True, **kwargs)

Write a spatial object to index of ascii, netCDF4 or HDF5 files

Parameters:

filename: str

full path of index file to be written

file_list: list

list of filenames for each output file

format: str or NoneType, default None

format of files in index

• 'ascii'

• 'netCDF4'

• 'HDF5'

date: bool, default True

spatial object contains date information

verbose: bool, default False

print file and variable information

kwargs: dict

keyword arguments for output writers

to_file(filename, format=None, date=True, **kwargs)

Write a spatial object to a specified format

Parameters:

filename: str

full path of output file

format: str or NoneType, default None

file format

• 'ascii'

• 'netCDF4'

• 'HDF5'

date: bool, default True

spatial object contains date information

verbose: bool, default False

print file and variable information

kwargs: dict

keyword arguments for output writers

default_field_mapping(variables)

Builds field mappings from a variable list

Parameters:

variables: list

netCDF4/HDF5 variables names to be mapped

• lonname

• latname

• varname

• timename

Returns:

field_mapping: dict

Field mappings for netCDF4/HDF5 read and write functions

to_masked_array()

Convert a spatial object to a masked numpy array

update_mask()

Update the mask of the spatial object

copy()

Copy a spatial object to a new spatial object

zeros_like()

Create a spatial object using the dimensions of another

expand_dims()

Add a singleton dimension to a spatial object if non-existent

extend_matrix()

Extends a global matrix to wrap along longitudes

Returns:

temp: float

extended matrix

squeeze()

Remove singleton dimensions from a spatial object

index(indice, date=True)

Subset a spatial object to specific index

Parameters:

indice: int

index in matrix for subsetting

date: bool, default True

spatial objects contain date information

subset(months)

Subset a spatial object to specific GRACE/GRACE-FO months

Parameters:

months: int

GRACE/GRACE-FO to subset

offset(var)

Offset a spatial object by a constant

Parameters:

var: float

scalar value to which the spatial object will be offset

scale(var)

Multiply a spatial object by a constant

Parameters:

var: float

scalar value to which the spatial object will be multiplied

mean(apply=False, indices=Ellipsis)

Compute mean spatial field and remove from data if specified

Parameters:

apply: bool, default False

remove the mean field from the input spatial object

indices: int, default Ellipsis

indices of input spatial object to compute mean

flip(axis=0)

Reverse the order of data and dimensions along an axis

Parameters:

axis: int, default 0

axis to reorder

transpose(axes=None)

Transpose or permute the axes of a spatial object

Parameters:

axis: int or NoneType, default None

order of the output axes

sum(power=1)

Compute summation of a spatial object

Parameters:

power: int, default 1

apply a power before calculating summation

power(power)

Raise a spatial object to a power

Parameters:

power: int

power to which the spatial object will be raised

max()

Compute maximum value of a spatial object

min()

Compute minimum value of a spatial object

replace_invalid(fill_value, mask=None)

Replace the masked values with a new fill_value

Parameters:

fill_value: float

Replacement invalid value

mask: bool or NoneType, default None

Update the current mask

replace_masked()

Replace the masked values with fill_value

property dtype

Main data type of spatial object

property spacing

Step size of spatial object [longitude,latitude]

property extent

Bounds of spatial object [minimum longitude, maximum longitude, minimum latitude, maximum latitude]

property shape

Dimensions of spatial object

property ndim

Number of dimensions in spatial object

class gravity_toolkit.scaling_factors(**kwargs)

Inheritance of spatial class for outputting scaling factors

Attributes:

data: float

spatial scaling factor data

error: float

spatial scaling factor errors

magnitude: float

spatial magnitude of the original data

mask: bool

spatial grid mask

x: float

x-coordinate array

y: float

y-coordinate array

lon: float

grid longitudes

lat: float

grid latitudes

fill_value: float or NoneType, default None

invalid value for spatial grid data

attributes: dict

attributes of spatial variables

extent: list, default [None,None,None,None]

spatial grid bounds [minimum x, maximum x, minimum y, maximum y]

spacing: list, default [None,None]

grid step size [x, y]

shape: tuple

dimensions of spatial object

ndim: int

number of dimensions of spatial object

filename: str

input or output filename

from_ascii(filename, **kwargs)

Read a scaling_factors object from an ascii file

Parameters:

filename: str

full path of input ascii file

compression: str or NoneType, default None

file compression type

• 'gzip'

• 'zip'

• 'bytes'

spacing: list, default [None,None]

grid step size [longitude,latitude]

extent: list, default [None,None,None,None]

spatial grid bounds [minimum longitude, maximum longitude, minimum latitude, maximum latitude]

nlat: int or NoneType, default None

length of latitude dimension

nlon: int or NoneType, default None

length of longitude dimension

columns: list, default [‘lon’,’lat’,’kfactor’,’error’,’magnitude’]

variable names for each column

header: int, default 0

Number of rows of header lines to skip

verbose: bool, default False

print file and variable information

to_ascii(filename, **kwargs)

Write a scaling_factors object to ascii file

Parameters:

filename: str

full path of output ascii file

verbose: bool, default False

Output file and variable information

kfactor(var)

Calculate the scaling factor and scaling factor errors from two spatial or scaling_factors objects following Landerer and Swenson [38] and [28]

Parameters:

var: obj

spatial object to used for scaling

Returns:

temp: obj

scaling factor, scaling error and magnitude

update_mask()

Update the mask of the scaling_factors object