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 PROFILE KEYS) and message logging controls.

flowstat.py

TKEanalyst.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)

TKEanalyst.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

TKEanalyst.profile_analyst.get_data_info(file_ending, folder_name='data/test-example')[source]

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

Parameters

  • file_ending (str) – ending of data files (e.g. ‘.vna’)

  • folder_name (str) – name of the test (experiment) to analyze

Returns

_pd.DataFrame with row names corresponding to file names ending on .vna (or otherwise defined in input.xlsx), and columns X, Y, Z in meters

TKEanalyst.profile_analyst.load_input_defs(file_name='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)

TKEanalyst.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

TKEanalyst.profile_analyst.vna_file_name2coordinates(file_ending, 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

  • file_ending (str) – ending of data files (e.g. ‘.vna’)

  • 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.

TKEanalyst.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

TKEanalyst.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.