Skip to content

Convert Data Formats

cklm2sc_new(clm_mat, lmax)

Transforms the spherical harmonics coefficients data in clm or klm format into a SC matrix.

Parameters:

Name Type Description Default
clm_mat ndarray

The input matrix containing spherical harmonics coefficients.

 required
lmax int

The maximum degree of the spherical harmonic expansion.

 required

Returns:

Name Type Description
tuple

A tuple containing: - scmat (numpy.ndarray): The SC matrix. - dev_scmat (numpy.ndarray): The deviation SC matrix.
Source code in pyshbundle/reshape_SH_coefficients.py 
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
def cklm2sc_new(clm_mat, lmax: int):
    """
    Transforms the spherical harmonics coefficients data in clm or klm format into a SC matrix.

    Args:
        clm_mat (numpy.ndarray): The input matrix containing spherical harmonics coefficients.
        lmax (int): The maximum degree of the spherical harmonic expansion.

    Returns:
        tuple: A tuple containing:
            - scmat (numpy.ndarray): The SC matrix.
            - dev_scmat (numpy.ndarray): The deviation SC matrix.
    """

    # initialise an empty sc matrix
    sc_mat = np.zeros([lmax+1, 2*lmax + 1])
    dev_sc_mat = np.zeros([lmax+1, 2*lmax + 1])

    # navigating the maze of indices

    # Use logical indices

    # sc mat requires padding - Taken care of by the earlier initialisation
    # 
    # filling the value at appropriate locaation is the key
    # 
    # Approach-1
        # run through rows(degree) and fill the cols(order) respectively

    # Approach -2
        # create a row_func s.t. [....., C22, C21, C20, S21, S22, .......]
        # then stack the rows

    # First flatten the SC matrix - column wise aka Fortran style
    # get the flattented idx to be raplaced using sub2ind 
    # replace the indices at those locations using 
    # unflatten the matrix

    shape_sc = sc_mat.shape

    # following the approach similar to Octave implementation
    # using matrix operations to improve the time efficiency as compared to looping
    idx_s = sub2ind(sc_mat.shape, clm_mat[:, 0].astype('i'), (lmax - clm_mat[:, 1]).astype('i')).astype('i')
    idx_c = sub2ind(sc_mat.shape, clm_mat[:, 0].astype('i'), (lmax + clm_mat[:, 1]).astype('i')).astype('i')


    flat_sc = sc_mat.flatten("F")
    # Attention first place the slm coeff. or else it will relace zonal clm coeff.
    flat_sc[idx_s] = clm_mat[:, 3]
    flat_sc[idx_c] = clm_mat[:, 2]

    flat_sc2 = dev_sc_mat.flatten("F")
    flat_sc2[idx_s] = clm_mat[:, 5]
    flat_sc2[idx_c] = clm_mat[:, 4]

    dev_scmat = flat_sc2.reshape(shape_sc)

    scmat = flat_sc.reshape(shape_sc)

    # with one flag include for 

    return scmat, dev_scmat

clm2cs(data_mat, lmax, sigma_flag=False)

Converts the format from CLM to CS.

Under the hood uses the clm2sc and sc2cs functions.

Parameters:

Name Type Description Default
data_mat ndarray

List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].

 required
lmax int

Max Degree of the spherical harmonic expansion.

 required
sigma_flag bool

Flag to return the standard deviation data in CS format or not. Defaults to False.

 False

Returns:

Type Description
ndarray

Spherical Harmonic Coefficients in CS format.
Source code in pyshbundle/reshape_SH_coefficients.py 
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
def clm2cs(data_mat: np.ndarray, lmax: int, sigma_flag=False):
    """
    Converts the format from CLM to CS.

    Under the hood uses the `clm2sc` and `sc2cs` functions.

    Args:
        data_mat (numpy.ndarray): List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].
        lmax (int): Max Degree of the spherical harmonic expansion.
        sigma_flag (bool, optional): Flag to return the standard deviation data in CS format or not. Defaults to False.

    Returns:
        (numpy.ndarray): Spherical Harmonic Coefficients in CS format.
    """
    if sigma_flag:
        sc_mat, dev_sc = clm2sc(data_mat=data_mat, lmax=lmax, sigma_flag=True)
        return sc2cs(sc_mat), sc2cs.sc2cs(dev_sc)
    else:
        sc_mat = clm2sc(data_mat=data_mat, lmax=lmax, sigma_flag=False)
        return sc2cs(sc_mat)

clm2sc(data_mat, lmax, sigma_flag=False)

Converts the spherical harmonic coefficients from CLM format to SC format.

Parameters:

Name Type Description Default
data_mat ndarray

List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].

 required
lmax int

Max Degree of the spherical harmonic expansion.

 required
sigma_flag bool

Flag to return the standard deviation data in CS format or not. Defaults to False.

 False

Returns:

Type Description
ndarray

Spherical Harmonic Coefficients in SC format.
References

Refer to the SHBundle or PySHBundle docs for the different data storage and retrieval formats.

Source code in pyshbundle/reshape_SH_coefficients.py 
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
def clm2sc(data_mat: np.ndarray, lmax: int, sigma_flag=False):
    """
    Converts the spherical harmonic coefficients from CLM format to SC format.

    Args:
        data_mat (numpy.ndarray): List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].
        lmax (int): Max Degree of the spherical harmonic expansion.
        sigma_flag (bool, optional): Flag to return the standard deviation data in CS format or not. Defaults to False.

    Returns:
        (numpy.ndarray): Spherical Harmonic Coefficients in SC format.

    References:
        Refer to the SHBundle or PySHBundle docs for the different data storage and retrieval formats.
    """

    sc_mat = np.zeros((lmax+1, 2*lmax + 2))
    dev_sc_mat = np.zeros((lmax+1, 2*lmax + 2))

    # as per the convention
    clm = data_mat[:, 2]
    slm = data_mat[:, 3]
    clm_std_dev = data_mat[:, 4]
    slm_std_dev = data_mat[:, 5]

    i = 0
    for index1 in range(0,lmax+1, 1):
        for index2 in range(0,index1+1, 1):

            sc_mat[index1, lmax-index2] = slm[i]
            sc_mat[index1, lmax+index2+1] = clm[i]

            dev_sc_mat[index1, lmax-index2] = slm_std_dev[i]
            dev_sc_mat[index1, lmax+index2+1] = clm_std_dev[i]

            i = i + 1

    sc_mat = np.delete(sc_mat, lmax, 1)
    dev_sc_mat = np.delete(dev_sc_mat, lmax, 1)

    if sigma_flag:
        return sc_mat, dev_sc_mat
    else:
        return sc_mat

cs2sc(field)

Converts SH coefficients from CS to SC format.

Converts the square (L+1)x(L+1) matrix field, containing spherical harmonics coefficients in CS storage format, into a rectangular (L+1)x(2L+1) matrix in SC format.

Parameters:

Name Type Description Default
field ndarray

The square (L+1)x(L+1) matrix, containing spherical harmonics coefficients in CS storage format.

 required

Returns:

Type Description
ndarray

Rectangular (L+1)x(2L+1) matrix in SC format.

Raises:

Type Description
TypeError

If the input is neither in CS nor in SC format.

Examples:

cs2sc(field)

Source code in pyshbundle/reshape_SH_coefficients.py 
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
def cs2sc(field):
    """
    Converts SH coefficients from CS to SC format.

    Converts the square (L+1)x(L+1) matrix `field`, containing
    spherical harmonics coefficients in CS storage format, into a 
    rectangular (L+1)x(2L+1) matrix in SC format.

    Args:
        field (numpy.ndarray): The square (L+1)x(L+1) matrix, containing
            spherical harmonics coefficients in CS storage format.

    Returns:
        (numpy.ndarray): Rectangular (L+1)x(2L+1) matrix in SC format.

    Raises:
        TypeError: If the input is neither in CS nor in SC format.

    Examples:
        cs2sc(field)
    """

    rows = len(field)
    cols = len(field[0])

    if (rows != cols) and (cols != 2*rows - 1):
        raise TypeError("Input neither in cs nor in sc format")
    elif cols == 2*rows - 1:
        sc = field
    else:
        c    = np.tril(field)
        ut   = np.triu(field)
        i = np.identity(rows)
        i = 1-i
        s    = np.fliplr(np.transpose(np.multiply(ut, i, )))
        sc   = np.concatenate((s[:,1:rows], c), axis=1)

    return(sc)

klm2sc(data_mat, lmax, sigma_flag=False)

Converts the spherical harmonic coefficients from klm format to SC format.

Parameters:

Name Type Description Default
data_mat ndarray

List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].

 required
lmax int

Max Degree of the spherical harmonic expansion.

 required
sigma_flag bool

Flag to return the standard deviation data in CS format or not. Defaults to False.

 False

Returns:

Type Description
ndarray

Spherical Harmonic Coefficients or/and associated standard deviations in SC format.
Source code in pyshbundle/reshape_SH_coefficients.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
def klm2sc(data_mat: np.ndarray, lmax: int, sigma_flag=False):
    """
    Converts the spherical harmonic coefficients from klm format to SC format.

    Args:
        data_mat (numpy.ndarray): List containing [degree, order, clm, slm, delta clm, delta slm, start date, end date].
        lmax (int): Max Degree of the spherical harmonic expansion.
        sigma_flag (bool, optional): Flag to return the standard deviation data in CS format or not. Defaults to False.

    Returns:
        (numpy.ndarray): Spherical Harmonic Coefficients or/and associated standard deviations in SC format.
    """
    sc_mat = np.zeros((lmax+1, 2*lmax + 2))
    dev_sc_mat = np.zeros((lmax+1, 2*lmax + 2))
    clm = data_mat[:, 2]
    slm = data_mat[:, 3]
    clm_std_dev = data_mat[:, 4]
    slm_std_dev = data_mat[:, 5]

    # first place the slm and then clm
    index2 =0
    for index1 in range(0,lmax+1,1):
        sc_mat[index1:, lmax-index1] = slm[(index2):(index2 + lmax-index1+1)]
        sc_mat[index1:, index1+lmax] = clm[(index2):(index2 + lmax-index1+1)]

        dev_sc_mat[index1:, lmax-index1] = slm_std_dev[(index2):(index2 + lmax-index1+1)]
        dev_sc_mat[index1:, index1+lmax] = clm_std_dev[(index2):(index2 + lmax-index1+1)]

        index2 = index2 + lmax-index1+1

    sc_mat=np.delete(sc_mat,lmax,axis=1)
    dev_sc_mat=np.delete(dev_sc_mat,lmax,axis=1)

    if sigma_flag:
        return sc_mat, dev_sc_mat
    else: 
        return sc_mat

sc2cs(field)

Converts SH coefficients from SC to CS format.

Converts the rectangular (L+1) x (2L+1) matrix field, containing spherical harmonics coefficients in SC storage format, into a square (L+1) x (L+1) matrix in CS format.

Parameters:

Name Type Description Default
field ndarray

The rectangular (L+1) x (2L+1) matrix, containing the spherical harmonics coefficients in SC storage format.

 required

Returns:

Type Description
ndarray

Square (L+1) x (L+1) matrix in CS format.
References

See the SHBundle docs or PySHBundle docs for more info about SH coefficient storage and retrieval formats being implemented.

Examples:

sc2cs(field)

Source code in pyshbundle/reshape_SH_coefficients.py 
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
def sc2cs(field):
    """
    Converts SH coefficients from SC to CS format.

    Converts the rectangular (L+1) x (2L+1) matrix `field`, containing
    spherical harmonics coefficients in SC storage format, into a 
    square (L+1) x (L+1) matrix in CS format.

    Args:
        field (numpy.ndarray): The rectangular (L+1) x (2L+1) matrix, containing the
            spherical harmonics coefficients in SC storage format.

    Returns:
        (numpy.ndarray): Square (L+1) x (L+1) matrix in CS format.

    References:
        See the SHBundle docs or PySHBundle docs for more info about SH coefficient storage and retrieval formats being implemented.

    Examples:
        sc2cs(field)
    """

    rows = len(field)
    cols = len(field[0])

    if (rows!=cols) and (cols!=2*rows - 1):
        sc2cs.exit("Input neither in cs nor in sc format")
    elif cols == rows:
        cs = field
    else:
        c    = field[:, rows-1:cols]
        st   = np.transpose(np.fliplr(field[:, 0:rows-1]))
        z    = np.zeros([1,rows])
        s    = np.concatenate((st, z), axis=0)
        cs   = np.add(c, s)

    return(cs)

Reference

  • Nico Sneeuw, Matthias Weigelt, Markus Antoni, Matthias Roth, Balaji Devaraju, et. al. (2021). SHBUNDLE 2021. http://www.gis.uni-stuttgart.de/research/projects/Bundles.