feat: added more time parsing for longer periods (#88)

refactor: use UCI for geocenter solutions (SLR still valid)

doc/source/api_reference/calc_mascon.rst

@@ -50,7 +50,7 @@ Calling Sequence
         * ``None``
         * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         * ``'SLR'``: satellite laser ranging coefficients from CSR
-        * ``'SLF'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson
         * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS
 

doc/source/api_reference/grace_mean_harmonics.rst

@@ -23,7 +23,7 @@ Calling Sequence
         * ``None``
         * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         * ``'SLR'``: satellite laser ranging coefficients from CSR
-        * ``'SLF'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson
         * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS
 

doc/source/api_reference/grace_spatial_error.rst

@@ -34,7 +34,7 @@ Calling Sequence
         * ``None``
         * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         * ``'SLR'``: satellite laser ranging coefficients from CSR
-        * ``'SLF'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson
         * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS
 

doc/source/api_reference/grace_spatial_maps.rst

@@ -49,7 +49,7 @@ Calling Sequence
         * ``None``
         * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         * ``'SLR'``: satellite laser ranging coefficients from CSR
-        * ``'SLF'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson
         * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS
 

doc/source/api_reference/scale_grace_maps.rst

@@ -51,7 +51,7 @@ Calling Sequence
         * ``None``
         * ``'Tellus'``: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         * ``'SLR'``: satellite laser ranging coefficients from CSR
-        * ``'SLF'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        * ``'UCI'``: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         * ``'Swenson'``: GRACE-derived coefficients from Sean Swenson
         * ``'GFZ'``: GRACE/SLR derived coefficients from GFZ GravIS
 

doc/source/api_reference/time.rst

@@ -25,7 +25,7 @@ Convert from Julian Days into calendar dates
     import gravity_toolkit.time
     JD = MJD + 2400000.5
     YEAR,MONTH,DAY,HOUR,MINUTE,SECOND = gravity_toolkit.time.convert_julian(JD,
-        FORMAT='tuple')
+        format='tuple')
 
 Convert a calendar date into Modified Julian Days (MJD)
 

gravity_toolkit/grace_input_months.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 grace_input_months.py
-Written by Tyler Sutterley (09/2022)
+Written by Tyler Sutterley (10/2022)
 Contributions by Hugo Lecomte and Yara Mohajerani
 
 Reads GRACE/GRACE-FO files for a specified spherical harmonic degree and order
@@ -44,7 +44,7 @@
             https://grace.jpl.nasa.gov/data/get-data/geocenter/
         SLR: satellite laser ranging coefficients from CSR
             http://download.csr.utexas.edu/pub/slr/geocenter/
-        SLF: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        UCI: Sutterley and Velicogna coefficients, Remote Sensing (2019)
             https://doi.org/10.6084/m9.figshare.7388540
         Swenson: GRACE-derived coefficients from Sean Swenson
             https://doi.org/10.1029/2007JB005338
@@ -105,6 +105,7 @@
     read_gfc_harmonics.py: reads spherical harmonic data from gfc files
 
 UPDATE HISTORY:
+    Updated 10/2022: tilde-expansion of input working data directory
     Updated 09/2022: use logging for debugging level verbose output
         add option to replace degree 4 zonal harmonics with SLR
     Updated 04/2022: updated docstrings to numpy documentation format
@@ -236,7 +237,7 @@ def grace_input_months(base_dir, PROC, DREL, DSET, LMAX, start_mon, end_mon,
             - ``None``: No degree 1 replacement
             - ``'Tellus'``: `GRACE/GRACE-FO TN-13 coefficients from PO.DAAC <https://grace.jpl.nasa.gov/data/get-data/geocenter/>`_ [Sun2016]_
             - ``'SLR'``: `Satellite laser ranging coefficients from CSR <ftp://ftp.csr.utexas.edu/pub/slr/geocenter/>`_ [Cheng2013]_
-            - ``'SLF'``: `GRACE/GRACE-FO coefficients from Sutterley and Velicogna <https://doi.org/10.6084/m9.figshare.7388540>`_ [Sutterley2019]_
+            - ``'UCI'``: `GRACE/GRACE-FO coefficients from Sutterley and Velicogna <https://doi.org/10.6084/m9.figshare.7388540>`_ [Sutterley2019]_
             - ``'Swenson'``: GRACE-derived coefficients from Sean Swenson [Swenson2008]_
             - ``'GFZ'``: `GRACE/GRACE-FO coefficients from GFZ GravIS <http://gravis.gfz-potsdam.de/corrections>`_
     MMAX: int or NoneType, default None
@@ -352,7 +353,7 @@ def grace_input_months(base_dir, PROC, DREL, DSET, LMAX, start_mon, end_mon,
     kwargs.setdefault('POLE_TIDE',False)
 
     #-- directory of exact GRACE/GRACE-FO product
-    grace_dir = os.path.join(base_dir, PROC, DREL, DSET)
+    grace_dir = os.path.join(os.path.expanduser(base_dir), PROC, DREL, DSET)
     #-- check that GRACE/GRACE-FO product directory exists
     if not os.access(grace_dir, os.F_OK):
         raise FileNotFoundError(grace_dir)
@@ -616,7 +617,7 @@ def grace_input_months(base_dir, PROC, DREL, DSET, LMAX, start_mon, end_mon,
         DEG1_input = gravity_toolkit.geocenter(radius=6.378136e9).from_SLR(DEG1_file,
             AOD=True,release=DREL,header=15,columns=COLUMNS)
         FLAGS.append('_w{0}_DEG1'.format(DEG1))
-    elif (DEG1 == 'SLF'):
+    elif DEG1 in ('SLF','UCI'):
         #-- degree one files from Sutterley and Velicogna (2019)
         #-- default: iterated and with self-attraction and loading effects
         MODEL = dict(RL04='OMCT', RL05='OMCT', RL06='MPIOM')
@@ -757,10 +758,10 @@ def grace_input_months(base_dir, PROC, DREL, DSET, LMAX, start_mon, end_mon,
     #-- Use Degree 1 coefficients
     #-- Tellus: Tellus Degree 1 (PO.DAAC following Sun et al., 2016)
     #-- SLR: CSR Satellite Laser Ranging (SLR) Degree 1 - GRACE AOD
-    #-- SLF: OMCT/MPIOM coefficients with Sea Level Fingerprint land-water mass
+    #-- UCI: OMCT/MPIOM coefficients with Sea Level Fingerprint land-water mass
     #-- Swenson: GRACE-derived coefficients from Sean Swenson
     #-- GFZ: GRACE/GRACE-FO coefficients from GFZ GravIS
-    if DEG1 in ('Tellus','SLR','SLF','Swenson','GFZ'):
+    if DEG1 in ('GFZ','SLR','SLF','Swenson','Tellus','UCI'):
         #-- check if modeling degree 1 or if all months are available
         if kwargs['MODEL_DEG1']:
             #-- least-squares modeling the degree 1 coefficients

gravity_toolkit/read_GRACE_harmonics.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 read_GRACE_harmonics.py
-Written by Tyler Sutterley (05/2022)
+Written by Tyler Sutterley (10/2022)
 Contributions by Hugo Lecomte
 
 Reads GRACE files and extracts spherical harmonic data and drift rates (RL04)
@@ -42,6 +42,7 @@
     time.py: utilities for calculating time operations
 
 UPDATE HISTORY:
+    Updated 10/2022: make keyword arguments part of kwargs dictionary
     Updated 05/2022: updated comments
     Updated 04/2022: updated docstrings to numpy documentation format
         include utf-8 encoding in reads to be windows compliant
@@ -70,7 +71,7 @@
 import gravity_toolkit.time
 
 #-- PURPOSE: read Level-2 GRACE and GRACE-FO spherical harmonic files
-def read_GRACE_harmonics(input_file, LMAX, MMAX=None, POLE_TIDE=False):
+def read_GRACE_harmonics(input_file, LMAX, **kwargs):
     """
     Extracts spherical harmonic coefficients from GRACE/GRACE-FO files
 
@@ -116,6 +117,9 @@ def read_GRACE_harmonics(input_file, LMAX, MMAX=None, POLE_TIDE=False):
         *Journal of Geophysical Research: Solid Earth*, 120(6), 4597--4615, (2015).
         `doi: 10.1002/2015JB011986 <https://doi.org/10.1002/2015JB011986>`_
     """
+    #-- set default keyword arguments
+    kwargs.setdefault('MMAX', None)
+    kwargs.setdefault('POLE_TIDE', False)
 
     #-- parse filename
     PFX,SY,SD,EY,ED,N,PRC,F1,DRL,F2,SFX = parse_file(input_file)
@@ -173,7 +177,7 @@ def read_GRACE_harmonics(input_file, LMAX, MMAX=None, POLE_TIDE=False):
         epoch=(1858,11,17,0,0,0))
 
     #-- set maximum spherical harmonic order
-    MMAX = np.copy(LMAX) if (MMAX is None) else MMAX
+    MMAX = np.copy(LMAX) if (kwargs['MMAX'] is None) else np.copy(kwargs['MMAX'])
     #-- output dimensions
     grace_L2_input['l'] = np.arange(LMAX+1)
     grace_L2_input['m'] = np.arange(MMAX+1)
@@ -241,7 +245,7 @@ def read_GRACE_harmonics(input_file, LMAX, MMAX=None, POLE_TIDE=False):
         grace_L2_input['slm'][:,:] += dt*drift_s[:,:]
 
     #-- Correct Pole Tide following Wahr et al. (2015) 10.1002/2015JB011986
-    if POLE_TIDE and (DSET == 'GSM'):
+    if kwargs['POLE_TIDE'] and (DSET == 'GSM'):
         #-- time since 2000.0
         dt = (grace_L2_input['time']-2000.0)
         #-- CSR and JPL Pole Tide Correction

gravity_toolkit/read_SLR_C20.py

@@ -328,7 +328,7 @@ def read_SLR_C20(SLR_file, AOD=True, HEADER=True):
                 MJD = np.float64(line_contents[0])
                 #-- converting from MJD into month, day and year
                 YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-                    MJD+2400000.5, FORMAT='tuple')
+                    MJD+2400000.5, format='tuple')
                 #-- converting from month, day, year into decimal year
                 dinput['time'][t] = gravity_toolkit.time.convert_calendar_decimal(
                     YY, MM, day=DD, hour=hh)
@@ -388,7 +388,7 @@ def read_SLR_C20(SLR_file, AOD=True, HEADER=True):
                 MJD = np.float64(line_contents[0])
                 #-- converting from MJD into month, day and year
                 YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-                    MJD+2400000.5, FORMAT='tuple')
+                    MJD+2400000.5, format='tuple')
                 #-- converting from month, day, year into decimal year
                 date_conv[t] = gravity_toolkit.time.convert_calendar_decimal(
                     YY, MM, day=DD, hour=hh)

gravity_toolkit/read_SLR_C30.py

@@ -158,7 +158,7 @@ def read_SLR_C30(SLR_file, C30_MEAN=9.5717395773300e-07, HEADER=True):
                 MJD = np.float64(line_contents[0])
                 #-- converting from MJD into month, day and year
                 YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-                    MJD+2400000.5, FORMAT='tuple')
+                    MJD+2400000.5, format='tuple')
                 #-- converting from month, day, year into decimal year
                 dinput['time'][t] = gravity_toolkit.time.convert_calendar_decimal(
                     YY, MM, day=DD, hour=hh)
@@ -251,7 +251,7 @@ def read_SLR_C30(SLR_file, C30_MEAN=9.5717395773300e-07, HEADER=True):
         dinput['error'] = Ylms['error']['clm'][3,0,:].copy()
         #-- converting from MJD into month, day and year
         YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-            Ylms['MJD']+2400000.5, FORMAT='tuple')
+            Ylms['MJD']+2400000.5, format='tuple')
         #-- calculate GRACE/GRACE-FO month
         dinput['month'] = gravity_toolkit.time.calendar_to_grace(YY,MM)
 

gravity_toolkit/read_SLR_C40.py

@@ -110,7 +110,7 @@ def read_SLR_C40(SLR_file, C40_MEAN=0.0, DATE=None, **kwargs):
         dinput['error'] = Ylms['error']['clm'][4,0,:].copy()
         #-- converting from MJD into month, day and year
         YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-            Ylms['MJD']+2400000.5, FORMAT='tuple')
+            Ylms['MJD']+2400000.5, format='tuple')
         #-- calculate GRACE/GRACE-FO month
         dinput['month'] = gravity_toolkit.time.calendar_to_grace(YY,MM)
 

gravity_toolkit/read_SLR_C50.py

@@ -137,7 +137,7 @@ def read_SLR_C50(SLR_file, C50_MEAN=0.0, DATE=None, HEADER=True):
                 MJD = np.float64(line_contents[0])
                 #-- converting from MJD into month, day and year
                 YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-                    MJD+2400000.5, FORMAT='tuple')
+                    MJD+2400000.5, format='tuple')
                 #-- converting from month, day, year into decimal year
                 dinput['time'][t] = gravity_toolkit.time.convert_calendar_decimal(
                     YY, MM, day=DD, hour=hh)
@@ -182,7 +182,7 @@ def read_SLR_C50(SLR_file, C50_MEAN=0.0, DATE=None, HEADER=True):
         dinput['error'] = Ylms['error']['clm'][5,0,:].copy()
         #-- converting from MJD into month, day and year
         YY,MM,DD,hh,mm,ss = gravity_toolkit.time.convert_julian(
-            Ylms['MJD']+2400000.5, FORMAT='tuple')
+            Ylms['MJD']+2400000.5, format='tuple')
         #-- calculate GRACE/GRACE-FO month
         dinput['month'] = gravity_toolkit.time.calendar_to_grace(YY,MM)
 

gravity_toolkit/time.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python
 u"""
 time.py
-Written by Tyler Sutterley (08/2022)
+Written by Tyler Sutterley (10/2022)
 Utilities for calculating time operations
 
 PYTHON DEPENDENCIES:
@@ -11,6 +11,7 @@
         https://dateutil.readthedocs.io/en/stable/
 
 UPDATE HISTORY:
+    Updated 10/2022: added more time parsing for longer periods
     Updated 08/2022: added file parsing functions from GRACE date utilities
         added function to dynamically select newest version of granules
         output variables to unit conversion to seconds and the number of days
@@ -48,6 +49,14 @@
            'hours': 3600.0, 'hour': 3600.0,
            'hr': 3600.0, 'hrs': 3600.0, 'h': 3600.0,
            'day': 86400.0, 'days': 86400.0, 'd': 86400.0}
+#-- approximate conversions for longer periods
+_to_sec['mon'] = 30.0 * 86400.0
+_to_sec['month'] = 30.0 * 86400.0
+_to_sec['months'] = 30.0 * 86400.0
+_to_sec['common_year'] = 365.0 * 86400.0
+_to_sec['common_years'] = 365.0 * 86400.0
+_to_sec['year'] = 365.25 * 86400.0
+_to_sec['years'] = 365.25 * 86400.0
 
 #-- PURPOSE: parse a date string into epoch and units scale
 def parse_date_string(date_string):

gravity_toolkit/tools.py

@@ -311,11 +311,11 @@ def select_options(self, **kwargs):
         #    https://grace.jpl.nasa.gov/data/get-data/geocenter/
         # SLR: satellite laser ranging from CSR
         #    ftp://ftp.csr.utexas.edu/pub/slr/geocenter/
-        # SLF: Sutterley and Velicogna, Remote Sensing (2019)
+        # UCI: Sutterley and Velicogna, Remote Sensing (2019)
         #    https://www.mdpi.com/2072-4292/11/18/2108
-        geocenter_default = 'SLF' if (self.product.value == 'GSM') else '[none]'
+        geocenter_default = 'UCI' if (self.product.value == 'GSM') else '[none]'
         self.geocenter = ipywidgets.Dropdown(
-            options=['[none]', 'Tellus', 'SLR', 'SLF'],
+            options=['[none]', 'Tellus', 'SLR', 'UCI'],
             value=geocenter_default,
             description='Geocenter:',
             disabled=False,
@@ -918,7 +918,7 @@ def from_cpt(filename, use_extremes=True, **kwargs):
     """
 
     # read the cpt file and get contents
-    with open(filename,'r') as f:
+    with open(filename, mode='r', encoding='utf8') as f:
         file_contents = f.read().splitlines()
     # extract basename from cpt filename
     name = re.sub(r'\.cpt','',os.path.basename(filename),flags=re.I)

gravity_toolkit/utilities.py

@@ -1473,7 +1473,7 @@ def from_figshare(directory,article='7388540',timeout=None,
         print file transfer information
     fid: obj, default sys.stdout
         open file object to print if verbose
-    pattern: str, default '(CSR|GFZ|JPL)_(RL\d+)_(.*?)_SLF_iter.txt$'
+    pattern: str, default r'(CSR|GFZ|JPL)_(RL\d+)_(.*?)_SLF_iter.txt$'
         regular expression pattern for reducing list
     mode: oct, default 0o775
         permissions mode of output local file

scripts/calc_mascon.py

@@ -52,7 +52,7 @@
     --geocenter X: Update Degree 1 coefficients with SLR or derived values
         Tellus: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         SLR: satellite laser ranging coefficients from CSR
-        SLF: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        UCI: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         Swenson: GRACE-derived coefficients from Sean Swenson
         GFZ: GRACE/GRACE-FO coefficients from GFZ GravIS
     --slr-c20 X: Replace C20 coefficients with SLR values
@@ -839,15 +839,15 @@ def arguments():
     #--     https://grace.jpl.nasa.gov/data/get-data/geocenter/
     #-- SLR: satellite laser ranging from CSR
     #--     ftp://ftp.csr.utexas.edu/pub/slr/geocenter/
-    #-- SLF: Sutterley and Velicogna, Remote Sensing (2019)
+    #-- UCI: Sutterley and Velicogna, Remote Sensing (2019)
     #--     https://www.mdpi.com/2072-4292/11/18/2108
     #-- Swenson: GRACE-derived coefficients from Sean Swenson
     #--     https://doi.org/10.1029/2007JB005338
     #-- GFZ: GRACE/GRACE-FO coefficients from GFZ GravIS
     #--     http://gravis.gfz-potsdam.de/corrections
     parser.add_argument('--geocenter',
         metavar='DEG1', type=str,
-        choices=['Tellus','SLR','SLF','Swenson','GFZ'],
+        choices=['Tellus','SLR','SLF','UCI','Swenson','GFZ'],
         help='Update Degree 1 coefficients with SLR or derived values')
     parser.add_argument('--geocenter-file',
         type=lambda p: os.path.abspath(os.path.expanduser(p)),

scripts/dealiasing_monthly_mean.py

@@ -201,7 +201,7 @@ def dealiasing_monthly_mean(base_dir, PROC=None, DREL=None, DSET=None,
         #-- calendar dates to read
         JD = np.array(julian_days_to_read)
         Y,M,D,h,m,s = gravity_toolkit.time.convert_julian(JD,
-            ASTYPE='i', FORMAT='tuple')
+            astype='i', format='tuple')
         #-- find unique year and month pairs to read
         rx1='|'.join(['{0:d}-{1:02d}'.format(*p) for p in set(zip(Y,M))])
         rx2='|'.join(['{0:0d}-{1:02d}-{2:02d}'.format(*p) for p in set(zip(Y,M,D))])

scripts/gfz_isdc_grace_ftp.py

@@ -243,11 +243,6 @@ def gfz_isdc_grace_ftp(DIRECTORY, PROC=[], DREL=[], VERSION=[],
                         drel_str = copy.copy(rl)
                     #-- print string of exact data product
                     logging.info('{0}/{1}/{2}/{3}'.format(mi, pr, drel_str, ds))
-                    #-- local directory for exact data product
-                    local_dir = os.path.join(DIRECTORY, pr, rl, ds)
-                    #-- check if directory exists and recursively create if not
-                    if not os.path.exists(local_dir):
-                        os.makedirs(local_dir,MODE)
                     #-- compile the regular expression operator to find files
                     R1 = re.compile(r'({0}-(.*?)(gz|txt|dif))'.format(ds))
                     #-- get filenames from remote directory

scripts/grace_mean_harmonics.py

@@ -21,7 +21,7 @@
     --geocenter X: Update Degree 1 coefficients with SLR or derived values
         Tellus: GRACE/GRACE-FO TN-13 coefficients from PO.DAAC
         SLR: satellite laser ranging coefficients from CSR
-        SLF: Sutterley and Velicogna coefficients, Remote Sensing (2019)
+        UCI: Sutterley and Velicogna coefficients, Remote Sensing (2019)
         Swenson: GRACE-derived coefficients from Sean Swenson
         GFZ: GRACE/GRACE-FO coefficients from GFZ GravIS
     --slr-c20 X: Replace C20 coefficients with SLR values
@@ -378,15 +378,15 @@ def arguments():
     #--     https://grace.jpl.nasa.gov/data/get-data/geocenter/
     #-- SLR: satellite laser ranging from CSR
     #--     ftp://ftp.csr.utexas.edu/pub/slr/geocenter/
-    #-- SLF: Sutterley and Velicogna, Remote Sensing (2019)
+    #-- UCI: Sutterley and Velicogna, Remote Sensing (2019)
     #--     https://www.mdpi.com/2072-4292/11/18/2108
     #-- Swenson: GRACE-derived coefficients from Sean Swenson
     #--     https://doi.org/10.1029/2007JB005338
     #-- GFZ: GRACE/GRACE-FO coefficients from GFZ GravIS
     #--     http://gravis.gfz-potsdam.de/corrections
     parser.add_argument('--geocenter',
         metavar='DEG1', type=str,
-        choices=['Tellus','SLR','SLF','Swenson','GFZ'],
+        choices=['Tellus','SLR','SLF','UCI','Swenson','GFZ'],
         help='Update Degree 1 coefficients with SLR or derived values')
     parser.add_argument('--geocenter-file',
         type=lambda p: os.path.abspath(os.path.expanduser(p)),