gnssrefl.phase_functions module

gnssrefl.phase_functions.apriori_file_exist(station, fr)

reads in the a priori RH results

Parameters:

station (string) – station name
fr (integer) – frequency

Return type:

boolean as to whether the apriori file exists

gnssrefl.phase_functions.convert_phase(station, year, year_end=None, plt2screen=True, fr=20, tmin=0.05, tmax=0.5, polyorder=-99, circles=False, subdir='', hires_figs=False)

Convert GPS phase to VWC. Using Clara Chew’s algorithm from Matlab write_vegcorrect_smc.m

https://scipy-cookbook.readthedocs.io/items/SignalSmooth.html

Parameters:

station (str) – 4 char station name
year (int) – beginning year
year_end (int) – last year
plt2screen (boolean) – plots come to the screen
fr (integer) – frequency default is L2C (20)
tmin (float) – soil texture minimum
tmax (float) – soil texture maximum
polyorder (integer) – override on the polynomial order used in leveling
circles (boolean) – final plot using circles (instead of line)
subdir (str) – subdirectory for $REFL_CODE/Files
hires_figs (bool) – whether you want eps instead of png files created

gnssrefl.phase_functions.daily_phase_plot(station, fr, datetime_dates, tv, xdir, subdir, hires_figs)

makes a plot of daily averaged phase for vwc code

Parameters:

station (str) – 4 char station name
fr (int) – frequency of signal
datetime_dates – datetime values for phase points
tv (list of results) – cannot remember the format
xdir (str) – location of the results (environment variable REFL_CODE)
subdir (str) – subdirectory in Files
hires_figs (bool) – whether you want eps instead of png files

gnssrefl.phase_functions.help_debug(rt, xdir, station)

Takes the input of phase files, read by other functions, and writes out a file to help with debugging (comparion of matlab and python codes)

rtnumpy array of floats: contents of the phase files stored in a numpy array
xdirstr: where the otuput should be written
stationstr: name of the station

gnssrefl.phase_functions.kinda_qc(satellite, rhtrack, meanaztrack, nvalstrack, amin, amax, y, t, new_phase, avg_date, avg_phase, warning_value, ftmp, remove_bad_tracks, k4, avg_exist)

Parameters:

satellite (int) – satellite number
rhtrack (float) – a priori reflector height
meanaztrack (float) – I think it is the azimuth of the track, degrees
nvalstrack (int) – not sure?
amin (int) – min az of this quadrant
amax (int) – max az of this quadrant
y (numpy array of ints) – year
t (numpy array of ints) – day of year
new_phase (numpy array of floats) – phase values for a given satellite track ??
avg_date (numpy array of floats) – y + doy/365.25 I think
avg_phase (numpy array of floats) – average phase, in degrees
warning_value (float) – phase noise value
ftmp (file ID) – for writing
remove_bad_tracks (bool) – whether you write out new tracks with bad ones removed
k4 (int) – number of tracks?
avg_exist (bool) – whether you have previous solution to compare to

gnssrefl.phase_functions.load_avg_phase(station, fr)

loads a previously computed daily average phase solution. this is NOT the same as the multi-track phase results. This file is now stored in station subdirectory in $REFL_CODE/Files/

Parameters:

station (str) – 4 character station ID, lowercase
fr (int) – frequency

Returns:

avg_exist (bool) – whether the necessary file exists
avg_date (list of floats) – fractional year, i.e. year + doy/365.25
avg_phase (list of floats) – average phase for a given day

gnssrefl.phase_functions.load_phase_filter_out_snow(station, year1, year2, fr, snowmask)

Load all phase data and attempt to remove outliers from snow if snowmask provided.

Parameters:

station (str) – four character station name
year1 (int) – starting year
year2 (int) – ending year
fr (int) – frequency, i.e. 1 or 20
snowmask (str) – name/location of the snow mask file None if this value is not going to be used

Returns:

dataexist (bool) – whether phase data were found
year (numpy array of int) – calendar years
doy (numpy array of int) – day of year
hr (numpy array of floats) – UTC hour of measurement
ph (numpy array of floats) – LS phase estimates
azdata (numpy array of floats) – average azimuth, degrees
ssat (numpy array of int) – satellite number
rh (numpy array of floats) – reflector height, meters
amp_lsp (numpy array of floats) – lomb scargle periodogram amplitude
amp_ls (numpy array of floats) – least squares amplitude
ap_rh (numpy array of floats) – apriori rh
results_trans (numpy array) – all phase results concatenated into numpy array plus column for quadrant and unwrapped phase

gnssrefl.phase_functions.load_sat_phase(station, year, year_end, freq)

Picks up the phase estimates from local (REFL_CODE) results section and returns most of the information from those files

Parameters:

station (str) – four character station name
year (integer) – beginning year
year_end (integer) – ending year
freq (integer) – GPS frequency (1,20 allowed)

Returns:

dataexist (bool) – whether data found?
results (numpy array of floats) – basically one variable with everything in the original columns from the daily phase files

gnssrefl.phase_functions.low_pct(amp, basepercent)

emulated amp_normK code from PBO H2O inputs are the amplitudes and a percentage used to define the bottom level. returns normalized amplitudes

this is meant to be used by individual tracks (I think) in this case they are the top values, not the bottom … ugh

gnssrefl.phase_functions.make_snow_filter(station, medfilter, ReqTracks, year1, year2)

Runs daily_avg code to make a snow mask file. This is so you have some idea of when the soil moisture products are contaminated by snow. Make a file with these years and doys saved. The user can edit if they feel the suggestsions are poor (i.e. days in the summer might show up as “snow”)

If snow mask file exists, it does not overwrite it.

Parameters:

station (str) – 4 ch station name
medfilter (float) – how much you allow the individual tracks to deviate from the daily median (meters)
ReqTracks (int) – number of tracks to compute trustworthy daily average
year1 (int) – starting year
year2 (int) – ending year

Returns:

snowmask_exists (bool) – whether file was created
snow_file (str) – name of the snow mask file
Creates output file into a file $REFL_CODE/Files/{ssss}/snowmask_{ssss}.txt
where ssss is the station name

gnssrefl.phase_functions.normAmp(amp, basepercent): emulated amp_normK code from PBO H2O inputs are the amplitudes and a percentage used to define the bottom level. returns normalized amplitudes this is meant to be used by individual tracks (I think) in this case they are the top values, not the bottom … ugh

gnssrefl.phase_functions.old_quad(azim)

calculates oldstyle quadrants from PBO H2O

Parameters:

azim (float) – azimuth, dgrees
q (int) – old quadrant system used in pboh2o

gnssrefl.phase_functions.phase_tracks(station, year, doy, snr_type, fr_list, e1, e2, pele, plot, screenstats, compute_lsp, gzip)

This does the main work of estimating phase and other parameters from the SNR files it uses tracks that were predefined by the apriori.py code

Parameters:

name (station) – 4 char id, lowercase
year (int) – calendar year
doy (int) – day of year
snr_type (int) – SNR file extension (i.e. 99, 66 etc)
fr_list (list of integers) – frequency, [1], [20] or [1,20]
e1 (float) – min elevation angle (degrees)
e2 (float) – max elevation angle (degrees)
pele (list of floats) – elevation angle limits for the polynomial removal. units: degrees
screenstats (bool) – whether statistics are printed to the screen
compute_lsp (bool) – this is always true for now
gzip (bool) – whether you want SNR files gzipped after running the code
track. (Only GPS frequencies are allowed because this relies on the repeating ground) –

gnssrefl.phase_functions.read_apriori_rh(station, fr)

read the track dependent a priori reflector heights needed for phase & thus soil moisture.

Parameters:

station (str) – four character ID, lowercase
fr (int) – frequency (e.g. 1,20)

Returns:

results – column 1 is just a number (1,2,3,4, etc)

column 2 is RH in meters

column 3 is satellite number

column 4 is azimuth of the track (degrees)

column 5 is number of values used in average

column 6 is minimum azimuth degrees for the quadrant

column 7 is maximum azimuth degrees for the quadrant

Return type:

numpy array

gnssrefl.phase_functions.rename_vals(year_sat_phase, doy, hr, phase, azdata, ssat, amp_lsp, amp_ls, rh, ap_rh, ii)

this is just trying to clean up vwc.py send indices ii - and return renamed variables.

Parameters:

year_sat_sat –
doy –
hr –
phase –
azdata –
ssat –
amp_lsp –
amp_ls –
rh –
ap_rh –
ii –

Returns:

y (numpy array of int) – year
t (numpy array of int) – day of year
h (numpy array of floats) – hour of the day (UTC)
x (numpy array of floats) – phase, degrees
azd (numpy array of floats) – azimuth for the track
s (numpy array of int)
amps_lsp (numpy array of floats) – LSP amplitude
amps_ls (numpy array of floats) – least squares amplitude
rhs (numpy array of floats) – estimated RH (m)
ap_rhs (numpy array of floats) – a priori RH (m)

gnssrefl.phase_functions.save_vwc_plot(fig, pngfile)

Parameters:

fig (matplotlib figure) – the figure definition you define when you open a figure
pngfile (str) – name of the png file to be saved

gnssrefl.phase_functions.set_parameters(station, minvalperday, tmin, tmax, min_req_pts_track, fr, year, year_end, subdir, plt, auto_removal, warning_value)

Parameters:

station (str) – 4 character station name

Returns:

minvalperday (int) – number of phase values required each day
tmin (float) – min soil texture
tmax (float) – max soil texture
min_req_pts_track (int) – minimum number of phase values per year per track
freq (int) – frequency to use (1,20 allowed)
year_end (int) – last year to analyze
subdir (str) – name for subdirectory used in subdirectory of REFL_CODE/Files
plt (bool) – whether you want plots to come to the screen
auto_removal (bool) – whther tracks should be removed when they fail QC
warning_value (float) – phase RMS needed to trigger warning
plot_legend (bool) – whether to plot PRN numbers on the phase & amplitude results

gnssrefl.phase_functions.test_func(x, a, b, rh_apriori): This is least squares for estimating a sine wave given a fixed frequency, freqLS

gnssrefl.phase_functions.test_func_new(x, a, b, rh_apriori, freq)

This is least squares for estimating a sine wave given a fixed frequency, freqLS now freq is input so it is not hardwired for L2

Parameters:

x (numpy array of floats) – sine(elevation angle) I think
a (float) – amplitude - estimated
b (float) – phase - estimated
rh_apriori (float) – reflector height (m)
freq (int) – frequency

gnssrefl.phase_functions.vwc_plot(station, t_datetime, vwcdata, plot_path, circles)

makes a plot of volumetric water content

Parameters:

station (string) – 4 ch station name
t_datetime (datetime) – observation times for measurements
vwcdata (numpy array of floats (I think)) – volumetric water content
plot_path (Saves a plot to) – full name of the plot file
circles (boolean) – circles in the plot. default is a line (really .-)
plot_path –

gnssrefl.phase_functions.write_all_phase(v, fname)

writes out preliminary phase values and other metrics for advanced vegetation option. This is in the hope that it can be used in clara chew’s dissertation algorithm.

File is written to $REFL_CODE/Files/station/station_all_phase.txt I think

Parameters:

v (numpy of floats as defined in vwc_cl) – TBD year, doy, phase, azimuth, satellite number estimated RH, LSP amplitude, LS amplitude, UTC hours raw LSP amp, raw LS amp
fname (str) – name of the output file
filestatus (int) – 1, open the file 2, write to file (well, really any value)
rhtrack (float) – apriori reflector height for the given track, meters

Returns:

allrh

Return type:

fileID

gnssrefl.phase_functions.write_avg_phase(station, phase, fr, year, year_end, minvalperday, vxyz, subdir)

creates output file for average phase results

Parameters:

station (string) –
phase (numpy list (float)) – phase values
fr (int) – frequency
year (int) – first year evaluated
year_end (int) – last year evaluated
minvalperday (int) – required number of satellite tracks to trust the daily average
compilation (vxyz is from some other) –
subdir (str) – subdirectory for results

Returns:

tv – year doy - day of year meanph - mean phase value in degrees nvals - number of values that went into the average

Return type:

numpy array with elements

gnssrefl.phase_functions.write_out_raw_phase(v, fname)

write daily phase values used in vwc to a new consolidated file I added columns for quadrant and unwrapped phase

Parameters:

v (numpy array) – phase results read for multiple years. could be with snow filter applied
fname (str) – filename for output

Returns:

newv – original variable v with columns added for quadrant (1-4) and unwrapped phase

Return type:

numpy array

gnssrefl.phase_functions.write_phase_for_advanced(filename, vxyz)

Writes out a file of interim phase results for advanced models developed by Clara Chew

File generally written to $REFL_CODE/Files/<station>/all_phase.txt

Parameters:

filename (str) – name for output file
vxyz (numpy array of floats) – as defined in vwc_cl.py