harmonics

Spherical harmonic data class for processing GRACE/GRACE-FO Level-2 data

Can read ascii, netCDF4, HDF5 files

Can read from an index of the above file types

Can merge a list of harmonics objects into a single object

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

Can calculate the mean field of a harmonics object

Can filter harmonics for correlated “striping” errors

Can output harmonics objects to ascii, netCDF4 or HDF5 files

Calling Sequence

Reading a netCDF4 file

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_netCDF4(path_to_netCDF4_file)

Reading a HDF5 file

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_HDF5(path_to_HDF5_file)

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

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_index(path_to_index_file,'netCDF4')
Ylms.to_netCDF4(path_to_netCDF4_file)

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

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_index(path_to_index_file,'HDF5').subset(months)

Reading an index file of ascii files and truncating to a new degree and order

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_index(path_to_index_file,'ascii').truncate(lmax)

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

from gravity_toolkit.harmonics import harmonics
Ylms = harmonics().from_dict(Ylms_dict)
Ylms.mean(apply=True)

Source code

General Attributes and Methods

class gravity_toolkit.harmonics(**kwargs)[source]

Data class for reading, writing and processing spherical harmonic data

Attributes:

lmax: int: maximum degree of the spherical harmonic field
mmax: int: maximum order of the spherical harmonic field
clm: np.ndarray: cosine spherical harmonics
slm: np.ndarray: sine spherical harmonics
time: np.ndarray: time variable of the spherical harmonics
month: np.ndarray: GRACE/GRACE-FO months variable of the spherical harmonics
attributes: dict: attributes of harmonics variables
filename: str: input or output filename
flattened: bool: harmonics object is compressed into arrays

case_insensitive_filename(filename)[source]

Searches a directory for a filename without case dependence

Parameters:

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

compressuser(filename=None)[source]

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

Parameters:

filename: str or None, default None: output filename

from_ascii(filename, **kwargs)[source]

Read a harmonics 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'

verbose: bool, default False

print file and variable information

from_netCDF4(filename, **kwargs)[source]

Read a harmonics 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'

verbose: bool, default False

print file and variable information

from_HDF5(filename, **kwargs)[source]

Read a harmonics 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'

verbose: bool, default False

print file and variable information

from_gfc(filename, **kwargs)[source]

Read a harmonics object from a gfc gravity model file

Parameters:

filename: str

full path of input gfc file

date: bool, default True

gfc file has date information

tide: str or NoneType, default None

permanent tide system of output gravity fields

'tide_free': no permanent direct and indirect tidal potentials

'mean_tide': permanent tidal potentials (direct and indirect)

'zero_tide': permanent direct tidal potential removed

verbose: bool, default False

print file and variable information

from_SHM(filename, **kwargs)[source]

Read a harmonics object from a spherical harmonic model file

Parameters:

filename: str: full path of input spherical harmonic model file
MMAX: int or NoneType, default None: Maximum order of spherical harmonics
POLE_TIDE: bool, default False: correct GSM data for pole tide drift
verbose: bool, default False: print file and variable information

from_index(filename, **kwargs)[source]

Read a harmonics 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 harmonics objects by date information

from_list(object_list, **kwargs)[source]

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

Parameters:

object_list: list: list of harmonics objects to be merged
date: bool, default True: files contains date information
sort: bool, default True: sort harmonics objects by date information
clear: bool, default True: clear the list of harmonics objects from memory

from_file(filename, format=None, date=True, **kwargs)[source]

Read a harmonics object from a specified format

Parameters:

filename: str

full path of input file

format: str or NoneType, default None

file format

'ascii'

'netCDF4'

'HDF5'

'gfc'

'SHM'

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)[source]

Convert a dict object to a harmonics object

Parameters:

d: dict: dictionary object to be converted

to_ascii(filename, date=True, **kwargs)[source]

Write a harmonics object to ascii file

Parameters:

filename: str: full path of output ascii file
date: bool, default True: harmonics objects contain date information
verbose: bool, default False: Output file and variable information

to_netCDF4(filename, **kwargs)[source]

Write a harmonics object to netCDF4 file

Parameters:

filename: str: full path of output netCDF4 file
units: str, default: ‘Geodesy_Normalization’: spherical harmonic units
time_units: str, default ‘years’: time variable units
time_longname: str, default ‘Date_in_Decimal_Years’: time variable description
months_name: str, default ‘month’: name of months variable
months_units: str, default ‘number’: months variable units
months_longname: str, default ‘GRACE_month’: months variable description
field_mapping: dict, default {}: mapping between input variables and output netCDF4
attributes: dict, default {}: output netCDF4 variable and file-level attributes
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: harmonics 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)[source]

Write a harmonics object to HDF5 file

Parameters:

filename: str: full path of output HDF5 file
units: str, default: ‘Geodesy_Normalization’: spherical harmonic units
time_units: str, default ‘years’: time variable units
time_longname: str, default ‘Date_in_Decimal_Years’: time variable description
months_name: str, default ‘month’: name of months variable
months_units: str, default ‘number’: months variable units
months_longname: str, default ‘GRACE_month’: months variable description
field_mapping: dict, default {}: mapping between input variables and output HDF5
attributes: dict, default {}: output HDF5 variable and file-level attributes
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: harmonics 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)[source]

Write a harmonics 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

harmonics 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)[source]

Write a harmonics 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

harmonics object contains date information

verbose: bool, default False

print file and variable information

kwargs: dict

keyword arguments for output writers

to_dict()[source]

Convert a harmonics object to a dict object

Returns:

d: dict: converted dictionary object

to_masked_array()[source]: Convert a harmonics object to a masked numpy array

to_coo_array()[source]: Convert data arrays to a COO sparse matrices

update_dimensions()[source]: Update the dimension variables of the harmonics object

add(temp)[source]

Add two harmonics objects

Parameters:

temp: obj: harmonic object to be added

subtract(temp)[source]

Subtract one harmonics object from another

Parameters:

temp: obj: harmonic object to be subtracted

multiply(temp)[source]

Multiply two harmonics objects

Parameters:

temp: obj: harmonic object to be multiplied

divide(temp)[source]

Divide one harmonics object from another

Parameters:

temp: obj: harmonic object to be divided

copy()[source]: Copy a harmonics object to a new harmonics object

zeros(lmax=None, mmax=None, nt=None)[source]: Create an empty harmonics object

zeros_like()[source]: Create a harmonics object using the dimensions of another

expand_dims(update_dimensions=True)[source]

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

Parameters:

update_dimensions: bool, default True: Update the degree and order dimensions

squeeze(update_dimensions=True)[source]

Remove singleton dimensions from a harmonics object

Parameters:

update_dimensions: bool, default True: Update the degree and order dimensions

flatten(date=True)[source]

Flatten harmonics matrices into arrays

Parameters:

date: bool, default True: harmonics objects contain date information

expand(date=True)[source]

Expand flattened harmonics into matrices

Parameters:

date: bool, default True: harmonics objects contain date information

index(indice, date=True)[source]

Subset a harmonics object to specific index

Parameters:

indice: int: index in matrix for subsetting
date: bool, default True: harmonics objects contain date information

subset(months)[source]

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

Parameters:

months: int: GRACE/GRACE-FO to subset

truncate(lmax, lmin=0, mmax=None)[source]

Truncate or expand a harmonics object to a new degree and order

Parameters:

lmax: int: maximum degree of spherical harmonics
lmin: int, default 0: minimum degree of spherical harmonics
mmax: int or NoneType, default None: maximum order of spherical harmonics

mean(apply=False, indices=Ellipsis)[source]

Compute mean gravitational field and remove from data if specified

Parameters:

apply: bool, default False: remove the mean field from the input harmonics object
indices: int, default Ellipsis: indices of input harmonics object to compute mean

scale(var)[source]

Multiply a harmonics object by a constant

Parameters:

var: float or np.ndarray: scalar value to which the harmonics object will be multiplied

power(power)[source]

Raise a harmonics object to a power

Parameters:

var: float: power to which the harmonics object will be raised

drift(t, epoch=2003.3)[source]

Integrate a harmonics rate field over time to calculate drift

Parameters:

t: np.ndarray: times for calculating drift
epoch: float: reference epoch for times

convolve(var)[source]

Convolve harmonics with a degree-dependent array

Parameters:

var: np.ndarray: degree dependent array for convolution

destripe(**kwargs)[source]

Filters spherical harmonic coefficients for correlated “striping” errors following Swenson and Wahr [64]

Parameters:

kwargs: dict: keyword arguments for destripe_harmonics

amplitude: Degree amplitude of the spherical harmonics

property dtype: Main data type of harmonics object

property shape: Dimensions of harmonics object

property ndim: Number of dimensions in harmonics object

ilm: Complex form of the spherical harmonics