Developer Docs

The following sections provide details of functions, their arguments, and outputs to help tweaking the code for individual purposes.

config.py

Global parameters settings (essentially SCRIPT_DIR) and message logging controls.

flowstat.py

flowstat.flowstat(time, u, v, w1, w2, profile_type='lp')[source]

Calculate ADV data statistics

Parameters

  • time (np.array) – time in seconds

  • u (np.array) – streamweise velocity along x-axis (positive in bulk flow direction)

  • v (np.array) – perpendicular velocity along y-axis

  • w1 (np.array) – vertical velocity if side is DOWN

  • w2 (np.array) – vertical velocity if side is not DOWN

  • profile_type (str) – orientation of the probe (default: lp, which mean probe looks like FlowTracker in a river)

Returns

keys correspond to series names and values to full time series stats (dict(dict)): keys correspond to series names with STAT for autoreplacement with STAT type of nested dictionaries with AVRG, STD and STDERR

Return type

time_series (dict)

profile_analyst.py

Load ADV measurements and calculate TKE with plot options Originally coded in Matlab at Nepf Lab (MIT) Re-written in Python by Sebastian Schwindt (2022)

profile_analyst.build_stats_summary(vna_stats_dict, experiment_info, profile_type, bulk_velocity, log_length)[source]

Re-organize the stats dataset and assign probe coordinates

Parameters

  • vna_stats_dict (dict) – the result of all vna files processed with the flowstat.flowstat function

  • experiment_info (dict) – the result of the get_data_info function for retrieving probe positions

  • profile_type (str) – profile orientation as a function of sensor position; the default is lp corresponding to DOWN (ignores w2 measurements)

  • bulk_velocity (float) – bulk streamwise flow velocity in m/s (from input.xlsx)

  • log_length (float) – characteristic log length (either diameter or length) in m (from input.xlsx)

Returns

Organized overview pandas.DataFrame with measurement stats, ready for dumping to workbook

profile_analyst.get_data_info(folder_name='test-example')[source]

get names of input file names and prepare output matrix according to number of files

Parameters

  • folder_name (str) – name of the test (experiment) to analyze (default is test-example)

  • input_file_name (str) – name of input file (default is input.xlsx)

Returns

pd.DataFrame with row names corresponding to file names ending on .vna, and columns X, Y, Z in meters

profile_analyst.load_input_defs(file_name='/home/docs/checkouts/readthedocs.org/user_builds/tke-calculator/checkouts/latest/docs/input.xlsx')[source]

loads provided input file name as pandas dataframe

Parameters

file_name (str) – name of input file (default is input.xlsx)

Returns

user input of input.xlsx (or costum file, if provided)

Return type

(dict)

profile_analyst.read_vna(vna_file_name)[source]

Read vna file name as pandas dataframe.

Parameters

vna_file_name (str) – name of a vna file, such as __8_16.5_6_T3.vna

Returns

pd.DataFrame

profile_analyst.vna_file_name2coordinates(vna_file_name)[source]

Take vna file name and extract x, y, and z coordinates in meters. Non-convertible numbers are translated into np.nan with warning.

Parameters

vna_file_name (str) – name of a vna file, such as __8_16.5_6_T3.vna

Returns

list [x, y, z] coordinates

profile_plotter.py

Plot functions for TKE visualization

Note

The script represents merely a start for plotting normalized TKE against normalized X. If required, enrich this script with more plot functions and integrate them in profile_analyst.process_vna_files at the bottom of the function.

profile_plotter.plot_xy(x, y, file_name)[source]

Plots y data against x (1d-numpy array) and markers of local maxima and minima

Parameters

  • x (numpy.array) – x data

  • y (numpy.array) – y data

Returns

show and save plot in test folder as norm-TKE-x.png

rmspike.py

rmspike.rmspike(vna_df, u_stats, v_stats, w_stats, w2_stats=None, method='velocity', freq=200.0, lambda_a=1.0, k=3.0, profile_type='lp')[source]

Spike removal and replacement - see Nikora & Goring (1999) and Goring & Nikora (2002).

Parameters

  • vna_df (pandas.DataFrame) – matrix-like data array of the vna measurement file

  • u_stats (pandas.DataFrame) – streamwise velocity stats from flowstat function

  • v_stats (pandas.DataFrame) – perpendicular velocity stats from flowstat function

  • w_stats (pandas.DataFrame) – vertical velocity stats from flowstat function

  • w2_stats (pandas.DataFrame) – sec. vertical velocity stats from flowstat function (only required if profile_type is not lp)

  • method (str) – determines whether to use acceleration or velocity (default) for despiking

  • freq (int) – sampling frequency in 1/s (Hz); default is 200 Hz

  • lambda_a (float) – multiplier of gravitational acceleration (acceleration threshold)

  • k (float) – multiplier of velocity stdev (velocity threshold)

  • side (str) – orientation of the probe (default: DOWN, which mean probe looks like FlowTracker in a river)

Note

Goring & Nikora (2002) suggest lambda_a = 1.0 ~ 1.5 and k = 1.5, but we shall use lambda_a = 1.0 and k = 3 ~ 9. SonTek, Nortek, and Lei recommend the SNR and correlation thresholds to be 15 and 70 respectively. Though data points have high SNR, the correlation can be low.