Skip to content

Commit 95463f4

Browse files
Tyler-g-hudsonTyler-g-hudson
authored
PyLance-compatible docstrings and clarifications in point/grid.py (#114)
* Clarify docstrings in grid.py, point.py and reformat them to be compatible with pylance * small add'l change * Fix small docstring issues in calc_solid_earth_tides_grid and calc_solid_earth_tides_point * Clarify lat/lon units in calc_solid_earth_tides_point_per_day * Further documentation clarifications. * Typo fix, specify that step_size is optional in calc_solid_earth_tides_grid * Tiny docstring consistency change
1 parent cedf3da commit 95463f4

2 files changed

Lines changed: 99 additions & 45 deletions

File tree

‎src/pysolid/grid.py‎

Lines changed: 30 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -26,20 +26,36 @@ def calc_solid_earth_tides_grid(dt_obj, atr, step_size=1e3, display=False, verbo
2626
input size. This uses the fact that SET varies slowly in space. Comparison w and w/o step_size
2727
shows a difference in tide_u with max of 5e-8 m, thus negligible.
2828
29-
Parameters: dt_obj - datetime.datetime object (with precision up to the second)
30-
atr - dict, metadata including the following keys:
31-
LENGTH/WIDTTH
32-
X/Y_FIRST
33-
X/Y_STEP
34-
step_size - float, grid step feeded into the fortran code in meters
35-
to speedup the calculation
36-
display - bool, plot the calculated SET
37-
verbose - bool, print verbose message
38-
Returns: tide_e - 2D np.ndarray, SET in east direction in meters
39-
tide_n - 2D np.ndarray, SET in north direction in meters
40-
tide_u - 2D np.ndarray, SET in up direction in meters
41-
Examples: atr = readfile.read_attribute('geo_velocity.h5')
42-
tide_e, tide_n, tide_u = calc_solid_earth_tides_grid('20180219', atr)
29+
Parameters:
30+
dt_obj : datetime.datetime
31+
The datetime to calculate this grid for, with precision up to the second.
32+
atr : dict
33+
metadata including the following keys:
34+
LENGTH/WIDTH
35+
X/Y_FIRST
36+
X/Y_STEP
37+
step_size : float, optional
38+
grid step size in meters; fed into the fortran code to speed up the
39+
calculation. Defaults to 1e3.
40+
display : bool, optional
41+
If True, plot the calculated SET. Defaults to False.
42+
verbose : bool, optional
43+
If True, print verbose messages. Defaults to True.
44+
45+
Returns:
46+
tide_e : 2D np.ndarray of floats
47+
SET in east direction in meters
48+
tide_n : 2D np.ndarray
49+
SET in north direction in meters
50+
tide_u : 2D np.ndarray
51+
SET in up direction in meters
52+
53+
Example:
54+
atr = readfile.read_attribute('geo_velocity.h5')
55+
56+
dt_obj = datetime.datetime(year=2018, month=2, day=19)
57+
58+
tide_e, tide_n, tide_u = calc_solid_earth_tides_grid(dt_obj, atr)
4359
"""
4460
try:
4561
from pysolid.solid import solid_grid

‎src/pysolid/point.py‎

Lines changed: 69 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -72,23 +72,47 @@
7272

7373
################################## Earth tides - point mode ##################################
7474
def calc_solid_earth_tides_point(lat, lon, dt0, dt1, step_sec=60, display=False, verbose=True):
75-
"""Calculate SET in east/north/up direction for the given time period at the given point (lat/lon).
76-
77-
Parameters: lat/lon - float32, latitude/longitude of the point of interest
78-
dt0/1 - datetime.datetime object, start/end date and time
79-
step_sec - int16, time step in seconds
80-
display - bool, plot the calculated SET
81-
verbose - bool, print verbose message
82-
Returns: dt_out - 1D np.ndarray in dt.datetime objects
83-
tide_e - 1D np.ndarray in float32, SET in east direction in meters
84-
tide_n - 1D np.ndarray in float32, SET in north direction in meters
85-
tide_u - 1D np.ndarray in float32, SET in up direction in meters
86-
Examples: dt0 = dt.datetime(2020,11,1,4,0,0)
87-
dt1 = dt.datetime(2020,12,31,2,0,0)
88-
(dt_out,
89-
tide_e,
90-
tide_n,
91-
tide_u) = calc_solid_earth_tides_point(34.0, -118.0, dt0, dt1)
75+
"""
76+
Calculate solid earth tides (SET) in east/north/up direction for the given time
77+
period at the given point.
78+
79+
Parameters:
80+
lat : float
81+
Latitude of the point of interest, in degrees.
82+
lon : float
83+
Longitude of the point of interest, in degrees.
84+
dt0 : datetime.datetime
85+
The datetime of the beginning of the SET calculation.
86+
dt1 : datetime.datetime
87+
The datetime of the end of the SET calculation.
88+
step_sec : int, optional
89+
Time step, in seconds, of the output. Defaults to 60.
90+
display : bool, optional
91+
If True, plot the calculated SET. Defaults to False.
92+
verbose : bool, optional
93+
If True, print verbose messages. Defaults to True.
94+
95+
Returns:
96+
dt_out : 1D np.ndarray of datetime.datetime
97+
The datetimes associated with each index of the following three arrays.
98+
The span of this array will be at least the period between dt0 and dt1.
99+
Note that dt_out is clamped to step_sec, so the start and end times may
100+
be slightly different than dt0 and dt1.
101+
tide_e : 1D np.ndarray of float32
102+
SET in east direction, in meters.
103+
tide_n : 1D np.ndarray of float32
104+
SET in north direction, in meters.
105+
tide_u : 1D np.ndarray of float32
106+
SET in up direction, in meters.
107+
108+
Example:
109+
dt0 = dt.datetime(2020,11,1,4,0,0)
110+
111+
dt1 = dt.datetime(2020,12,31,2,0,0)
112+
113+
(
114+
dt_out, tide_e, tide_n, tide_u
115+
) = calc_solid_earth_tides_point(34.0, -118.0, dt0, dt1)
92116
"""
93117

94118
print('PYSOLID: calculate solid Earth tides in east/north/up direction')
@@ -144,20 +168,34 @@ def calc_solid_earth_tides_point(lat, lon, dt0, dt1, step_sec=60, display=False,
144168

145169

146170
def calc_solid_earth_tides_point_per_day(lat, lon, date_str, step_sec=60):
147-
"""Calculate solid Earth tides (SET) in east/north/up direction
148-
for one day at the given point (lat/lon).
149-
150-
Parameters: lat/lon - float32, latitude/longitude of the point of interest
151-
date_str - str, date in YYYYMMDD
152-
step_sec - int16, time step in seconds
153-
Returns: dt_out - 1D np.ndarray in dt.datetime objects
154-
tide_e - 1D np.ndarray in float32, SET in east direction in meters
155-
tide_n - 1D np.ndarray in float32, SET in north direction in meters
156-
tide_u - 1D np.ndarray in float32, SET in up direction in meters
157-
Examples: (dt_out,
158-
tide_e,
159-
tide_n,
160-
tide_u) = calc_solid_earth_tides_point_per_day(34.0, -118.0, '20180219')
171+
"""
172+
Calculate solid Earth tides (SET) in east/north/up direction for one day at the
173+
given point (lat/lon).
174+
175+
Parameters:
176+
lat : float
177+
Latitude of the point of interest, in degrees.
178+
lon : float
179+
Longitude of the point of interest, in degrees.
180+
date_str : str
181+
The date to generate solid earth tides for, in YYYYMMDD format.
182+
step_sec : int, optional
183+
Time step, in seconds, of the output. Defaults to 60.
184+
185+
Returns:
186+
dt_out : 1D np.ndarray of datetime.datetime
187+
The datetimes associated with each index of the following three arrays.
188+
tide_e : 1D np.ndarray of float32
189+
SET in east direction, in meters.
190+
tide_n : 1D np.ndarray of float32
191+
SET in north direction, in meters.
192+
tide_u : 1D np.ndarray of float32
193+
SET in up direction, in meters.
194+
195+
Example:
196+
(
197+
dt_out, tide_e, tide_n, tide_u
198+
) = calc_solid_earth_tides_point_per_day(34.0, -118.0, '20180219')
161199
"""
162200
try:
163201
from pysolid.solid import solid_point

0 commit comments

Comments
 (0)