ginput 1.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. ginput/__init__.py +4 -0
  2. ginput/common_utils/__init__.py +0 -0
  3. ginput/common_utils/ggg_logging.py +62 -0
  4. ginput/common_utils/ioutils.py +304 -0
  5. ginput/common_utils/mod_constants.py +24 -0
  6. ginput/common_utils/mod_utils.py +2663 -0
  7. ginput/common_utils/readers.py +477 -0
  8. ginput/common_utils/run_utils.py +57 -0
  9. ginput/common_utils/sat_utils.py +67 -0
  10. ginput/common_utils/versioning.py +251 -0
  11. ginput/common_utils/writers.py +377 -0
  12. ginput/data/.gitignore +1 -0
  13. ginput/data/GEOS_FPIT_lat_vs_theta_2018_500-700hPa.nc +0 -0
  14. ginput/data/ML_monthly_obs_ch4.txt +498 -0
  15. ginput/data/ML_monthly_obs_co.txt +412 -0
  16. ginput/data/ML_monthly_obs_co2.txt +597 -0
  17. ginput/data/ML_monthly_obs_n2o.txt +330 -0
  18. ginput/data/SMO_monthly_obs_ch4.txt +499 -0
  19. ginput/data/SMO_monthly_obs_co.txt +416 -0
  20. ginput/data/SMO_monthly_obs_co2.txt +613 -0
  21. ginput/data/SMO_monthly_obs_n2o.txt +330 -0
  22. ginput/data/ace_fn2o_lut.nc +0 -0
  23. ginput/data/age_spectra/age.midlat.txt +47 -0
  24. ginput/data/age_spectra/age.tropics.txt +46 -0
  25. ginput/data/age_spectra/age.vortex.txt +31 -0
  26. ginput/data/age_spectra/agespec.midlat.txt +47 -0
  27. ginput/data/age_spectra/agespec.tropics.txt +46 -0
  28. ginput/data/age_spectra/agespec.vortex.txt +31 -0
  29. ginput/data/age_spectra/time.txt +3001 -0
  30. ginput/data/ch4_hf_slopes.nc +0 -0
  31. ginput/data/ch4_strat_lut.nc +0 -0
  32. ginput/data/clams_age_clim_scaled.nc +0 -0
  33. ginput/data/co2_strat_lut.nc +0 -0
  34. ginput/data/fo2_data/.gitignore +2 -0
  35. ginput/data/fo2_data/fo2_inputs_20241118T180747/co2_annmean_gl.txt +84 -0
  36. ginput/data/fo2_data/fo2_inputs_20241118T180747/monthly_o2_alt.csv +455 -0
  37. ginput/data/fo2_data/fo2_inputs_20241118T180747/monthly_o2_cgo.csv +431 -0
  38. ginput/data/fo2_data/fo2_inputs_20241118T180747/monthly_o2_ljo.csv +455 -0
  39. ginput/data/fo2_data/fo2_inputs_20241219T112756/co2_annmean_gl.txt +84 -0
  40. ginput/data/fo2_data/fo2_inputs_20241219T112756/monthly_o2_alt.csv +455 -0
  41. ginput/data/fo2_data/fo2_inputs_20241219T112756/monthly_o2_cgo.csv +431 -0
  42. ginput/data/fo2_data/fo2_inputs_20241219T112756/monthly_o2_ljo.csv +455 -0
  43. ginput/data/hf_strat_lut.nc +0 -0
  44. ginput/data/isotopologs.dat +199 -0
  45. ginput/data/meso_co_lut.nc +0 -0
  46. ginput/data/n2o_ch4_acefts.nc +0 -0
  47. ginput/data/n2o_strat_lut.nc +0 -0
  48. ginput/data/o2_mean_dmf.dat +52 -0
  49. ginput/data/summer_35N.vmr +182 -0
  50. ginput/data/washenfelder03_table_s3.txt +83 -0
  51. ginput/download/__init__.py +0 -0
  52. ginput/download/download_utils.py +46 -0
  53. ginput/download/get_GEOS5.py +367 -0
  54. ginput/download/get_MERRA2.py +177 -0
  55. ginput/download/get_NOAA_flask_data.py +103 -0
  56. ginput/download/get_fo2_data.py +140 -0
  57. ginput/mod_maker/__init__.py +0 -0
  58. ginput/mod_maker/mod_maker.py +2470 -0
  59. ginput/mod_maker/slantify.py +450 -0
  60. ginput/mod_maker/tccon_sites.py +570 -0
  61. ginput/priors/__init__.py +0 -0
  62. ginput/priors/acos_interface.py +1376 -0
  63. ginput/priors/automation.py +313 -0
  64. ginput/priors/backend_analysis/__init__.py +0 -0
  65. ginput/priors/backend_analysis/ace_fts_analysis.py +1418 -0
  66. ginput/priors/backend_analysis/ace_fts_val.py +452 -0
  67. ginput/priors/backend_analysis/acos_comparison.py +550 -0
  68. ginput/priors/backend_analysis/aircraft_aircore_val.py +1219 -0
  69. ginput/priors/backend_analysis/aircraft_preprocessing.py +295 -0
  70. ginput/priors/backend_analysis/atmos_mkiv_val.py +116 -0
  71. ginput/priors/backend_analysis/backend_driver.py +90 -0
  72. ginput/priors/backend_analysis/backend_utils.py +358 -0
  73. ginput/priors/backend_analysis/clams.py +71 -0
  74. ginput/priors/backend_analysis/create_test_priors.py +853 -0
  75. ginput/priors/backend_analysis/geos_theta_lat.py +594 -0
  76. ginput/priors/backend_analysis/mls_val.py +217 -0
  77. ginput/priors/backend_analysis/retrieval_obs_val.py +1306 -0
  78. ginput/priors/fo2_prep.py +311 -0
  79. ginput/priors/map_maker.py +193 -0
  80. ginput/priors/mlo_smo_prep.py +1146 -0
  81. ginput/priors/tccon_priors.py +3482 -0
  82. ginput-1.3.0.dist-info/LICENSE.txt +203 -0
  83. ginput-1.3.0.dist-info/METADATA +125 -0
  84. ginput-1.3.0.dist-info/RECORD +86 -0
  85. ginput-1.3.0.dist-info/WHEEL +5 -0
  86. ginput-1.3.0.dist-info/top_level.txt +1 -0
ginput/__init__.py ADDED
@@ -0,0 +1,4 @@
1
+ # be sure to update in setup.py as well
2
+ # and man/conf.py
3
+ # please follow semantic versioning: https://semver.org/
4
+ __version__ = '1.3.0'
File without changes
@@ -0,0 +1,62 @@
1
+ from __future__ import print_function, division
2
+
3
+ import logging
4
+
5
+
6
+ ###########
7
+ # LOGGING #
8
+ ###########
9
+
10
+ # Set up the logger for this package
11
+ # Add a new level (https://stackoverflow.com/a/13638084)
12
+ _important_log_level = 29 # just below warning at 30
13
+ logging.addLevelName(_important_log_level, 'IMPORTANT')
14
+
15
+
16
+ def _log_important(self, message, *args, **kwargs):
17
+ if self.isEnabledFor(_important_log_level):
18
+ # it is correct - *args in is passes just as args
19
+ self._log(_important_log_level, message, args, **kwargs)
20
+
21
+
22
+ logging.Logger.important = _log_important
23
+
24
+ _formatter = logging.Formatter('%(levelname)s (from %(funcName)s in %(filename)s): %(message)s')
25
+ _log_handler = logging.StreamHandler()
26
+ _log_handler.setFormatter(_formatter)
27
+ logger = logging.getLogger('val-logger')
28
+ logger.addHandler(_log_handler)
29
+
30
+ logger.setLevel('DEBUG')
31
+
32
+
33
+ def _log_to_file(filename=''):
34
+ fh = logging.FileHandler(filename=filename, mode='w')
35
+ fh.setFormatter(_formatter)
36
+ logger.addHandler(fh)
37
+
38
+
39
+ def setup_logger(log_file=None, level=0):
40
+ """
41
+ Modify the package logger to add log file and change the verbosity level.
42
+
43
+ :param log_file: a filename to write the log to.
44
+ :type log_file: str
45
+
46
+ :param level: the verbosity level. < 0 suppresses all messages less important than warnings, 0 prints important
47
+ messages, 1 print informational messages, >= 2 prints everything.
48
+ :type level: int
49
+
50
+ :return: None
51
+ """
52
+ if log_file is not None:
53
+ _log_to_file(log_file)
54
+
55
+ if level < 0:
56
+ logger.setLevel('WARNING')
57
+ elif level == 0:
58
+ logger.setLevel('IMPORTANT')
59
+ elif level == 1:
60
+ logger.setLevel('INFO')
61
+ elif level >= 2:
62
+ logger.setLevel("DEBUG")
@@ -0,0 +1,304 @@
1
+ from __future__ import print_function, division
2
+
3
+ import cftime
4
+ import datetime as dt
5
+ from hashlib import sha1
6
+ import netCDF4 as ncdf
7
+ import numpy as np
8
+ from subprocess import CalledProcessError
9
+ import sys
10
+
11
+ from . import mod_utils
12
+
13
+
14
+ class SmartHandle:
15
+ """An improved handle to standard files
16
+
17
+ This solves the problem of opening either a file on disk or the special stdin/stdout file objects. If the filename
18
+ is "-" or `None`, then stdin or stdout is opened (depending on the mode - stdin for read modes, stdout for any other
19
+ mode). Otherwise the file specified is opened as normal.
20
+
21
+ Parameters
22
+ ----------
23
+ filename: str or None
24
+ The path to the file to open. If "-" or `None`, then stdin/stdout is "opened"
25
+ mode: str
26
+ The permission mode to open the file under, may be any mode recognized by the :func:`open` builtin.
27
+
28
+ Examples
29
+ --------
30
+
31
+ You can use this pretty much anywhere in place of :func:`open`. The following would write "This is a log message"
32
+ to the :file:`logfile.txt` file:
33
+
34
+ >>> f = SmartHandle('logfile.txt', 'w')
35
+ >>> f.write('This is a log message\\n')
36
+ >>> f.close()
37
+
38
+ But we can also use this to write that to stdout:
39
+
40
+ >>> f = SmartHandle('-', 'w') # stdout is chosen because the mode is write
41
+ >>> f.write('This is a log message\\n')
42
+ >>> f.close() # closing will have no effect and can be included or omitted safely
43
+
44
+ This works in `with` blocks as well
45
+ >>> with SmartHandle('-', 'w') as f:
46
+ >>> f.write('This is a log message\\n')
47
+
48
+ This is helpful if, say, you want to print messages to the screen normally but have the ability to redirect them
49
+ to a file. A single `with` block can write to either a file or stdout depending on the value of the filename, which
50
+ helps prevent having to duplicate your code.
51
+ """
52
+ def __init__(self, filename, mode):
53
+ if filename is None or filename == '-':
54
+ if mode.startswith('r'):
55
+ self._handle = sys.stdin
56
+ else:
57
+ self._handle = sys.stdout
58
+ self._do_close = False
59
+ else:
60
+ self._handle = open(filename, mode)
61
+ self._do_close = True
62
+
63
+ def __getattr__(self, item):
64
+ # this allows pass through of all read/write methods to the _handle
65
+ return getattr(self._handle, item)
66
+
67
+ def __enter__(self):
68
+ return self
69
+
70
+ def __exit__(self, exc_type, exc_val, exc_tb):
71
+ self.close()
72
+
73
+ def close(self):
74
+ """Close the open file.
75
+
76
+ This has no effect if it was stdin or stdout opened.
77
+ """
78
+ if self._do_close:
79
+ self._handle.close()
80
+
81
+
82
+ def make_ncdim_helper(nc_handle, dim_name, dim_var, **attrs):
83
+ """
84
+ Create a netCDF dimension and its associated variable simultaneously
85
+
86
+ Typically in a netCDF file, each dimension should have a variable with the same name that defines the coordinates
87
+ for that dimension. This function streamlines the process of creating a dimension with its associated variable.
88
+
89
+ :param nc_handle: the handle to a netCDF file open for writing, returned by :class:`netCDF4.Dataset`
90
+ :type nc_handle: :class:`netCDF4.Dataset`
91
+
92
+ :param dim_name: the name to give both the dimension and its associated variable
93
+ :type dim_name: str
94
+
95
+ :param dim_var: the variable to use when defining the dimension's coordinates. The dimensions length will be set
96
+ by the size of this vector. This must be a 1D numpy array or comparable type.
97
+ :type dim_var: :class:`numpy.ndarray`
98
+
99
+ :param attrs: keyword-value pairs defining attribute to attach to the dimension variable.
100
+
101
+ :return: the dimension object
102
+ :rtype: :class:`netCDF4.Dimension`
103
+ """
104
+ if np.ndim(dim_var) != 1:
105
+ raise ValueError('Dimension variables are expected to be 1D')
106
+ dim = nc_handle.createDimension(dim_name, np.size(dim_var))
107
+ var = nc_handle.createVariable(dim_name, dim_var.dtype, dimensions=(dim_name,))
108
+ var[:] = dim_var
109
+ var.setncatts(attrs)
110
+ return dim
111
+
112
+
113
+ def make_nctimedim_helper(nc_handle, dim_name, dim_var, base_date=dt.datetime(1970, 1, 1), time_units='seconds',
114
+ calendar='gregorian', **attrs):
115
+ """
116
+ Create a CF-style time dimension.
117
+
118
+ The Climate and Forecast (CF) Metadata Conventions define standardized conventions for how to represent geophysical
119
+ data. Time is one of the trickiest since there are multiple ways of identifying dates that can be ambiguous. The
120
+ standard representation is to give time in units of seconds/minutes/hours/days since a base time in a particular
121
+ calendar. This function handles creating the a time dimension and associated variable from any array-like object of
122
+ datetime-like object.
123
+
124
+ For more information, see:
125
+
126
+ http://cfconventions.org/Data/cf-conventions/cf-conventions-1.7/cf-conventions.html#time-coordinate
127
+
128
+ :param nc_handle: the handle to a netCDF file open for writing, returned by :class:`netCDF4.Dataset`
129
+ :type nc_handle: :class:`netCDF4.Dataset`
130
+
131
+ :param dim_name: the name to give both the dimension and its associated variable
132
+ :type dim_name: str
133
+
134
+ :param dim_var: the variable to use when defining the dimension's coordinates. The dimensions length will be set
135
+ by the size of this vector. This must be a 1D numpy array or comparable type.
136
+ :type dim_var: :class:`numpy.ndarray`
137
+
138
+ :param base_date: the date and time to make the time coordinate relative to. The default is midnight, 1 Jan 1970.
139
+ :type base_date: datetime-like object
140
+
141
+ :param time_units: a string indicating what unit to use as the count of time between the base date and index date.
142
+ Options are 'seconds', 'minutes', 'hours', or 'days'. This is more restrictive than the CF convention, but avoids
143
+ the potential pitfalls of using months or years.
144
+ :type time_units: str
145
+
146
+ :param calendar: one of the calendar types defined in the CF conventions document (section 4.4.1)
147
+ :type calendar: str
148
+
149
+ :param attrs: keyword-value pairs defining attribute to attach to the dimension variable.
150
+
151
+ :return: the dimension object, and a dictionary describing the units, calendar, and base date of the time dimension
152
+ :rtype: :class:`netCDF4.Dimension`, dict
153
+ """
154
+ allowed_time_units = ('seconds', 'minutes', 'hours', 'days')
155
+ if time_units not in allowed_time_units:
156
+ raise ValueError('time_units must be one of: {}'.format(', '.join(allowed_time_units)))
157
+
158
+ units_str = '{} since {}'.format(time_units, base_date.strftime('%Y-%m-%d %H:%M:%S'))
159
+ # date2num requires that the dates be given as basic datetimes. We'll handle converting Pandas timestamps, either
160
+ # as a series or datetime index, but other types will need handled by the user.
161
+ try:
162
+ date_arr = ncdf.date2num(dim_var, units_str, calendar=calendar)
163
+ except TypeError:
164
+ dim_var = [d.to_pydatetime() for d in dim_var]
165
+ date_arr = ncdf.date2num(dim_var, units_str, calendar=calendar)
166
+ base_date = cftime.date2num(base_date, units_str, calendar=calendar)
167
+ attrs.update({'units': units_str, 'calendar': calendar, 'base_date': base_date})
168
+ dim = make_ncdim_helper(nc_handle, dim_name, date_arr, **attrs)
169
+ return dim
170
+
171
+
172
+ def make_ncvar_helper(nc_handle, var_name, var_data, dims, **attrs):
173
+ """
174
+ Create a netCDF variable and store the data for it simultaneously.
175
+
176
+ This function combines call to :func:`netCDF4.createVariable` and assigning the variable's data and attributes.
177
+
178
+ :param nc_handle: the handle to a netCDF file open for writing, returned by :class:`netCDF4.Dataset`
179
+ :type nc_handle: :class:`netCDF4.Dataset`
180
+
181
+ :param var_name: the name to give the variable
182
+ :type var_name: str
183
+
184
+ :param var_data: the array to store in the netCDF variable.
185
+ :type var_data: :class:`numpy.ndarray`
186
+
187
+ :param dims: the dimensions to associate with this variable. Must be a collection of either dimension names or
188
+ dimension instances. Both types may be mixed. This works well with :func:`make_ncdim_helper`, since it returns the
189
+ dimension instances.
190
+ :type dims: list(:class:`netCDF4.Dimensions` or str)
191
+
192
+ :param attrs: keyword-value pairs defining attribute to attach to the dimension variable.
193
+
194
+ :return: the variable object
195
+ :rtype: :class:`netCDF4.Variable`
196
+ """
197
+ dim_names = tuple([d if isinstance(d, str) else d.name for d in dims])
198
+ var = nc_handle.createVariable(var_name, var_data.dtype, dimensions=dim_names)
199
+ var[:] = var_data
200
+ var.setncatts(attrs)
201
+ return var
202
+
203
+
204
+ def make_creation_info(filename, creation_note=None):
205
+ """
206
+ Create a string describing the creation of a stored file.
207
+
208
+ This is intended to create a string attribute that describes how a file containing look up tables or other
209
+ derived information for the GGG retrieval. The string will include the date the file was generated and, provided
210
+ the Mercurial repository is intact, the commit hash that generated the file.
211
+
212
+ :param filename: the path to the file that is being created. Its status will be ignored when determining if the
213
+ Mercurial commit is clean or not.
214
+ :type filename: str
215
+
216
+ :param creation_note: A short string describing how the file was created. If given, it will be inserted into the
217
+ string as "Created by {note} on {date}". Typically this will indicate what function created the file.
218
+ :type creation_note: str
219
+
220
+ :return: the description string
221
+ :rtype: str
222
+ """
223
+ now = dt.datetime.now()
224
+ try:
225
+ git_or_hg = 'git' if mod_utils._is_git_repo() else 'mercurial'
226
+ commit_hash, branch, _ = mod_utils.vcs_commit_info()
227
+ clean_or_dirty = 'clean' if mod_utils.vcs_is_commit_clean(ignore_files=[filename]) else 'dirty'
228
+ except (CalledProcessError, FileNotFoundError): # if hg is not installed, get a FileNotFoundError instead of CalledProcessError
229
+ if creation_note is not None:
230
+ description = 'Created by {note} on {date} (could not acquire {vcs} commit information)'
231
+ else:
232
+ description = 'Created on {date} (could not acquire {vcs} commit information)'
233
+ description = description.format(note=creation_note, date=now, vcs=git_or_hg)
234
+ else:
235
+ if creation_note is not None:
236
+ description = 'Created by {note} on {date} ({vcs} commit {commit} on branch {branch}, {cleanstate})'
237
+ else:
238
+ description = 'Created with {vcs} commit {commit} on branch {branch} ({cleanstate}) on {date}'
239
+
240
+ description = description.format(note=creation_note, date=now, commit=commit_hash, branch=branch,
241
+ cleanstate=clean_or_dirty, vcs=git_or_hg)
242
+ return description
243
+
244
+
245
+ def add_creation_info(nc_handle, creation_note=None, creation_att_name='history'):
246
+ """
247
+ Add a creation note to a netCDF file.
248
+
249
+ :param nc_handle: a handle to the netCDF4 dataset to add the attribute to.
250
+ :type nc_handle: :class:`netCDF4.Dataset`
251
+
252
+ :param creation_note: see the same named parameter in :func:`make_creation_info`.
253
+ :type creation_note: str
254
+
255
+ :param creation_att_name: what attribute to store the creation information as.
256
+ :type creation_att_name: str
257
+
258
+ :return: None
259
+ """
260
+ description = make_creation_info(nc_handle.filepath(), creation_note=creation_note)
261
+ nc_handle.setncattr(creation_att_name, description)
262
+
263
+
264
+ def make_dependent_file_hash(dependent_file):
265
+ """
266
+ Create an SHA1 hash of a file.
267
+
268
+ :param dependent_file: the path to the file to hash.
269
+ :type dependent_file: str
270
+
271
+ :return: the SHA1 hash
272
+ :rtype: str
273
+ """
274
+ hashobj = sha1()
275
+ with open(dependent_file, 'rb') as fobj:
276
+ block = fobj.read(4096)
277
+ while block:
278
+ hashobj.update(block)
279
+ block = fobj.read(4096)
280
+
281
+ return hashobj.hexdigest()
282
+
283
+
284
+ def add_dependent_file_hash(nc_handle, hash_att_name, dependent_file):
285
+ """
286
+ Add an SHA1 hash of another file as an attribute to a netCDF file.
287
+
288
+ This is intended to create an attribute that list the SHA1 hash of a file that the netCDF file being created
289
+ depends on.
290
+
291
+ :param nc_handle: a handle to the netCDF4 dataset to add the attribute to.
292
+ :type nc_handle: :class:`netCDF4.Dataset`
293
+
294
+ :param hash_att_name: the name to give the attribute that will store the hash. It is recommended to include the
295
+ substring "sha1" so that it is clear what hash function was used.
296
+ :type hash_att_name: str
297
+
298
+ :param dependent_file: the file to generate the hash of.
299
+ :type dependent_file: str
300
+
301
+ :return: None
302
+ """
303
+ hash_hex = make_dependent_file_hash(dependent_file)
304
+ nc_handle.setncattr(hash_att_name, hash_hex)
@@ -0,0 +1,24 @@
1
+ import os
2
+
3
+ avogadro = 6.022141e23 # molec./mol
4
+ mass_dry_air = 28.964e-3 # kg/mol
5
+ mass_h2o = 18.01534e-3 # kg/mol
6
+ gas_const = 8.314e4 # gas constant in cm^3 * hPa / (mol * K)
7
+
8
+ ratio_molec_mass = 28.964/18.02 # Ratio of Molecular Masses (Dry_Air/H2O)
9
+
10
+ trop_flag = 1
11
+ middleworld_flag = 2
12
+ overworld_flag = 3
13
+
14
+ _mydir = os.path.dirname(__file__)
15
+ data_dir = os.path.abspath(os.path.join(_mydir, '..', 'data'))
16
+
17
+ days_per_year = 365.25
18
+
19
+ priors_version = '1.0.0'
20
+
21
+ # US Standard Atmosphere
22
+ p_ussa = (10.0, 5.0, 2.0, 1.0, 0.5, 0.2, 0.1, 0.01, 0.001, 0.0001)
23
+ t_ussa = (227.7, 239.2, 257.9, 270.6, 264.3, 245.2, 231.6, 198.0, 189.8, 235.0)
24
+ z_ussa = (31.1, 36.8, 42.4, 47.8, 53.3, 60.1, 64.9, 79.3, 92.0, 106.3)