complete_interact(pp0, pps, proc_data_fn::Function; kwargs...) → nothing
complete_interact(pp0, pps, proc_data_fns::Tuple; kwargs...) → nothing

This is the top level function for building the interaction with the user. See the flow diagram in the documentation for details. It calls proc_ARGS first, prompt_and_parse multiple times, and lets user pick file(s) by a GUI. The inputs are merged with the parameter in the excel file, and all that passed to user-provided function(s) to perform the data processing.

Arguments

• pp0::Union{Nothing, ArgumentParser}: ArgumentParser for command line arguments.
• pps::NamedTuple: ArgumentParsers for individual dialogs. The corresponding keys are: [:gen_options, :spec_options, :exelfile_prompt, :datafiles_prompt, :next_file]. To skip a dialog, skip the key.
• proc_data_fn(; xlfile, datafiles, paramsets)::Function: Function to do the actual data processing. It takes these three kwargs.
• proc_data_fns::Tuple: Alternatively a tuple of three functions can be provides: For preprocessing, processing a subset, and postprocessing. See also proc_data

Keyword arguments

• basedir=nothing: The base directory for the file selection dialogs. If basedir not provided, uses the cached value.
• paramtables = (;setup="params_setup", exper="params_experiment"): The names of the tables containing the corresponding parameters. Set a table to nothing to skip it.
• getexel=false: If true, execute excel file selection dialog.
• getdata=(; dialogtype = :none): If :none, no data file selection dialog, otherwise the parameter will be passed to the get_data function to execute file/directory selection dialog.

Function complete_interact is exported.

exper_paramsets(userargs, df_exp, df_setup) → Vector{NamedTuple}

Merges userargs with the parameter in df_setup and in each row of df_exp

Arguments

• userargs: Arguments (e.g. as NamedTuple)
• df_exp::Union{Nothing, DataFrame}: Experiment (subsets) parameter, as read from an excel file.
• df_setup::Union{Nothing, DataFrame}: Experiment setup parameter, as read from an excel file.

Function exper_paramsets is exported.

proc_n_save(procwhole_fn, procsubset_fn, postproc_fn;
    xlfile,
    datafiles=nothing, 
    paramsets = [(;)],
    ) → (; overview, subsets_results, résumé, errors, dfs)

Calls proc_data with the user provided functions to process data followed by save_results. For explanation of arguments and returned values see docs on these functions.

Function proc_n_save is exported.

read_xl_paramtables(f_src; paramtables=(;setup="params_setup", exper="params_experiment")) 
    → (; df_setup::Union{Nothing, DataFrame}, df_exp::Union{Nothing, DataFrame})

Reads the two tables (if not nothing) from an XLSX file into corresponding DataFrames and strips comments, if any. Comment is any row starting with #

Argument

• f_src::String: File path

Keyword argument

• paramtables=(;setup::Union{Nothing, String}="params_setup", exper::Union{Nothing, String}="params_experiment")

Returned NamedTuple

• (;df_setup::Union{Nothing, DataFrame}, df_exp::Union{Nothing, DataFrame}

Function read_xl_paramtables is exported.

combine2df(subsets_results) → Union{DataFrame, Nothing}

Combines NamedTuples (or equivalent) into a dataFrame.

Function combine2df is public, not exported.

get_data(;dialogtype, filterlist="", datadir=nothing) 
    → (; abort::Bool, datafiles)

Calls the function NativeFileDialog: pick_file(datadir; filterlist) or pick_multi_file(datadir; filterlist). If datadir not provided, uses the cached value. Caches the selected directory. Returns file or folder or multiple files.

Keyword arguments

• dialogtype: dialogtype ∈ [:single, :multiple, :folder]
• datadir: The base directory for file selection dialog.
• filterlist: Will be passed to pick_file / pick_multi_file function.

Throws

• On unknown value of dialogtype

Function get_data is public, not exported.

get_xl(; basedir=nothing, paramtables = (;setup="params_setup", exper="params_experiment")) 
    → (;abort, xlargs=rslt, fname)

Calls the function NativeFileDialog: pick_file(datadir; filterlist) to select an XLSX. Passes the file to read_xl_paramtables to parse the parameter table(s) If basedir not provided, uses the cached value. Caches the selected directory.

Keyword arguments

• dialogtype: dialogtype ∈ [:single, :multiple, :folder]
• basedir: The base directory for file selection dialog.

Returned NamedTuple

• abort::Bool: Dialog cancelled by user
• xlargs::NamedTuple: Tables read into DataFrames - s. read_xl_paramtables
• fname::String: Selected XLSX file

Function get_xl is public, not exported.

makeproj(tgt_folder, tgt_projname, tgt_scriptname, src::NamedTuple; 
    ignorecase=false, authors::Vector{String}=String[], force=false) → nothing
makeproj(tgt_folder, tgt_projname, tgt_scriptname, src::Symbol; kwargs...)

Create a project by copying a template project and performing renamings as necessary. Destination folder must be different from the enclosing folder of the source.

Arguments

• tgt_folder::AbstractString: Destination folder
• tgt_projname::AbstractString: The name of the project to be created
• tgt_scriptname::AbstractString: The name of the executable script
• src::Symbol: Accepts either :default (the default template), or :example1 for Toy Example #1, or :example2 for Toy Example #2 provided with GivEmXL
• src::@NamedTuple{src_folder::String, src_scriptname::String}: E.g. it would be src=(; src_folder="userproj_template/Template_ProjName", src_scriptname="template_user_scriptname") for the default template

Keyword arguments

• ignorecase=false: Ignore case in the file paths
• authors::Vector{T}=String[] where T <: AbstractString: The project authors (goes to Project.toml)
• force=false: If true, will overwrite the destination.

Function makeproj is public, not exported.

merge_params(df_exp::Union{Nothing, DataFrame}, df_setup::Union{Nothing, DataFrame}, row::Integer) → (;nt, nt_exp, nt_setup, nt_unitless)

Merges default parameters and units from df_setup with the parameter in the given row of df_exp, and returns them as NamedTuple of NamedTuples. Actually only the nt field of the returned value is used.

Function merge_params is public.

Examples

julia> m = GivEmXL.merge_params(df_exp, df_setup, 1);
julia> m.nt
(area = 0.5 cm², Vunit = mV, timeunit = s, Cunit = nF, R = 5 GΩ, t_start = 1 s, t_stop = 4 s, ϵ = 3.7, no = 1, plot_annotation = "first discharge", comment = "first discharge – 1")

mergent(args::Array) → ::NamedTuple
mergent(args...) → ::NamedTuple

Merges multiple NamedTuples, or arguments convertible to NamedTuples (e.g. Dict, pairs).

Function mergent is internal.

nt2unitful(nt, ntunits) → NamedTuple

Applies units from ntunits to the values from nt

Function nt2unitful is internal.

Examples

julia> nt2unitful((; a=2.0, b=3), (;a=u"cm/s"))
(a = 2.0 cm s⁻¹, b = 3)

out_paths(f_src) → (;fname, f_src, src_dir, rslt_dir, outf, errf)

From given source path, generates names and paths used for sources and results.

Function out_paths is public, not exported.

parse_cl_string(s::AbstractString) →  ::String[]

Wrapper around Base.shell_split

Function parse_cl_string is public, not exported.

proc_ARGS(pp0::Nothing) = (;abort=false, argpairs = emptyargs())
proc_ARGS(pp0::ArgumentParser) → (;abort, argpairs)

Reads and parses the arguments provided to the script from the command line. See the flow diagram in the documentation for details.

Arguments

• pp0::Union{Nothing, ArgumentParser}: ArgumentParser for command line arguments.

Returned NamedTuple

• abort::Bool
• argpairs: Vector of pairs argname::Symbol => argvalue::Any

Function proc_ARGS is public, not exported.

proc_data(xlfile, datafiles, paramsets, procwhole_fn, procsubset_fn, postproc_fn; throwonerr=false) 
    → (; overview, subsets_results, résumé, errors)

Calls the user provided data processing functions.

Arguments

• xlfile: XLSX file (if any)
• datafiles: Data file(s) or folder (if any)
• paramsets::Vector{NamedTuple}: Parameter merged from those supplied by user as cli arguments and those contained in the excel file.
• procwhole_fn::Union{Nothing, Function}: User supplied function for preprocessing
• procsubset_fn::Union{Nothing, Function}: User supplied function for processing a data subset
• postproc_fn::Union{Nothing, Function}: User supplied function for postprocessing

Keyword arguments

• throwonerr=false: If true, Julia execution will stop on an error and print error information, otherwise execution continues and error information can be saved into a separate file.

Returned NamedTuple

• overview::NamedTuple: May contain DataFrame(s) and plot objects as returned by procwhole_fn function
• subsets_results::Vector{NamedTuple}: May contain a DataFrame row and plot objects for each subset as returned by procsubset_fn
• résumé::NamedTuple: May contain DataFrame(s) and plot objects as returned by postproc_fn function
• errors::Vector{NamedTuple}: Collects information on errors if any occurred.

Function proc_data is public, not exported.

prompt_and_parse(pp::Nothing) = (;abort=false, argpairs = emptyargs())
prompt_and_parse(pp::ArgumentParser) → (;abort, argpairs)

Prints a prompt, read and parses the input from the user. See the flow diagram in the documentation for details.

Arguments

• pp::Union{Nothing, ArgumentParser}: ArgumentParser for command line arguments.

Returned NamedTuple

• abort::Bool
• argpairs: Vector of pairs argname::Symbol => argvalue::Any

Function prompt_and_parse is public, not exported.

read_units(df_setup::DataFrame) → NamedTuple
read_units(d::Nothing) = (;)

Function read_units is internal.

Examples

julia> GivEmXL.read_units(df_setup)
(area = cm², Vunit = mV, timeunit = s, Cunit = nF, R = GΩ, t_start = s, t_stop = s, ϵ = missing)

julia> typeof(ans.timeunit)
Unitful.FreeUnits{(s,), 𝐓, nothing}

remove_comments(df::DataFrame) → ::DataFrame

Comment is any row starting with # - these rows will be omitted.

Function remove_comments is internal.

s2unit(str::AbstractString) → ::Quantity

Strips all kinds of quotation marks and parses a string into Quantity. See also Unitful.uparse

Throws

• On conversion error

Function s2unit is internal.

save_all_plots(overview, subsets_results, résumé, rslt_dir, paramsets) → nothing

Saves plot objects as generated by the three data processing functions into files of given format.

Arguments

• overview, subsets_results, résumé::NamedTuple: Results of actual data processing in the form (; plots=(;df1, df2...), ...). The key 'plots' is optional.
• rslt_dir: directory where to put files.
• paramsets::Vector{NamedTuple}: If paramsets[1] has field plotformat, it will be the format for saving plots.

Function save_all_plots is public, not exported.

save_dfs(overview, subsets_results, résumé, outf) → NamedTuple

Saves DataFrames as generated by the three data processing functions into (multiple) tables of an XLSX file

Arguments

• overview, subsets_results, résumé::NamedTuple: Results of actual data processing in the form (; dataframes=(;df1, df2...), ...). The key 'dataframes' is optional.
• outf: target XLSX file.

Returns

• dfs: a NamedTuple of DataFrames

Function save_dfs is public, not exported.

save_results(results, xlfile, paramsets) → (;dfs)

Calls the functions save_dfs, save_all_plots, write_errors to save the results and errors.

Arguments

• results: NamedTuple having structure (; overview, subsets_results, résumé, errors)
• overview, subsets_results, résumé::NamedTuple: Results of actual data processing in the form (; plots=(;df1, df2...), ...). The key 'plots' is optional.
• xlfile: Path to the XLSX file with the parameter.
• paramsets::Vector{NamedTuple}

Returned value

• (;dfs): A NamedTuple of DataFrames as returned by save_dfs

Function save_results is public, not exported.

saveplots(rs, rslt_dir; plotformat = "png", kwargs...) → nothing

Saves plot objects as generated by a data processing function into files of given format.

Arguments

• rs: NamedTuple with the processing results.
• rslt_dir: directory where to put files.

Keyword arguments

• plotformat = "png": If plotformat == "none", do not save.
• Other kwargs will be ignored.

Function saveplots is public, not exported.

write_errors(errf, errors) → errored::Bool

Saves backtraces of errors into a file.

Arguments

• errf: File where errors will be saved.
• errors: Array of backtraces

Returns

• errored: false if errors was an empty array.

Function write_errors is public, not exported.

write_xl_tables(fl, nt_dfs; overwrite=true) → Nothing

Writes multiple DataFrames into an XLSX file.

Arguments

• fl: target XLSX file.
• nt_dfs::NamedTuple: DataFrames to save. nt_dfs keys will map to table names.

Function write_xl_tables is public, not exported.