Merge branch 'dev'

Author: MegamindHenry

docs/src/index.md

@@ -10,6 +10,18 @@ JudiLing is now on the Julia package system. You can install JudiLing by the fol
 using Pkg
 Pkg.add("JudiLing")
 ```
+For brave adventurers, install test version of JudiLing by:
+```
+julia> Pkg.add(PackageSpec(url="https://github.com/MegamindHenry/JudiLing.jl.git"))
+```
+if you are on the Julia 1.4 and in Julia 1.5 REPL, we can run:
+```
+julia> Pkg.add(url="https://github.com/MegamindHenry/JudiLing.jl.git")
+```
+Or from the Julia REPL, type `]` to enter the Pkg REPL mode and run
+```
+pkg> add https://github.com/MegamindHenry/JudiLing.jl.git
+```
 
 ## Running Julia with multiple threads
 JudiLing supports the use of multiple threads. Simply start up Julia in your terminal as follows:
@@ -526,6 +538,16 @@ You can download and try out this script [here](https://osf.io/sa89x/download).
 
 We implemented a high-level wrapper function that aims to provide quick and preliminary studies on multiple datasets with different parameter settings. For a sophisticated study, we suggest to build a script step by step.
 
+In general, `test_combo` function will perform the following operations:
+
+- prepare datasets
+- make cue matrix object
+- make semantic matrix
+- learn transfrom mapping F and G
+- perform path-finding algorithms for both `learn_paths` and `build_paths` in training and validation datasets
+- evaluate results
+- save outputs
+
 ### Split mode
 `test_combo` function provides four split mode. `:train_only` give the opportunity to only evaluate the model with training data or partial training data. `data_path` is the path to the CSV file and `data_output_dir` is the directory for store training and validation datasets for future analysis.
 
@@ -567,7 +589,7 @@ JudiLing.test_combo(
     )
 ```
 
-`:random_split` will randomly split data into training and validation datasets. In this case, it is high likely that unseen n-grams and features are in the validation datasets. Therefore, `if_combined` should be turned on. `data_path` is the path to the directory containing CSV files and `data_output_dir` is the directory for store training and validation datasets for future analysis.
+`:random_split` will randomly split data into training and validation datasets. In this case, it is high likely that unseen n-grams and features are in the validation datasets. Therefore, you should set `if_combined` to true. `data_path` is the path to the directory containing CSV files and `data_output_dir` is the directory for store training and validation datasets for future analysis.
 
 ```julia
 JudiLing.test_combo(
@@ -594,7 +616,7 @@ JudiLing.test_combo(
     )
 ```
 
-`:careful_split` will carefully split data into training and validation datasets where there will be no unseen n-grams and features in the validation datasets. Therefore, `if_combined` shall be truned off. `data_path` is the path to the directory containing CSV files and `data_output_dir` is the directory for store training and validation datasets for future analysis. `n_features_columns` gives names of feature columns and target column.
+`:careful_split` will carefully split data into training and validation datasets where there will be no unseen n-grams and features in the validation datasets. Therefore, you should set `if_combined` to false. `data_path` is the path to the directory containing CSV files and `data_output_dir` is the directory for store training and validation datasets for future analysis. `n_features_columns` gives names of feature columns and target column.
 
 ```julia
 JudiLing.test_combo(

src/find_path.jl

@@ -65,6 +65,7 @@ word, which n-grams are best supported for a given position in the sequence of n
 - `sep_token::Union{Nothing, String, Char}=nothing`: separator token
 - `keep_sep::Bool=false`:if true, keep separators in cues
 - `target_col::Union{String, :Symbol}=:Words`: the column name for target strings
+- `start_end_token::Union{String, Char}="#"`: start and end token in boundary cues
 - `issparse::Symbol=:auto`: control of whether output of Mt matrix is a dense matrix or a sparse matrix
 - `sparse_ratio::Float64=0.2`: the ratio to decide whether a matrix is sparse
 - `if_pca::Bool=false`: turn on to enable pca mode
@@ -214,6 +215,7 @@ function learn_paths(
     sep_token = nothing,
     keep_sep = false,
     target_col = "Words",
+    start_end_token = "#",
     issparse = :auto,
     sparse_ratio = 0.2,
     if_pca = false,
@@ -261,6 +263,7 @@ function learn_paths(
             tokenized = tokenized,
             sep_token = sep_token,
             keep_sep = keep_sep,
+            start_end_token = start_end_token
         )
 
         verbose && println("Calculating Mt...")

src/test_combo.jl

@@ -122,6 +122,10 @@ function test_combo(test_mode; kwargs...)
     random_seed = get_kwarg(kwargs, :random_seed, required=false)
     if_combined = get_kwarg(kwargs, :if_combined, required=false)
 
+    verbose && println("="^20)
+    verbose && println("Preparing datasets...")
+    verbose && println("="^20)
+    
     # split and load data
     if test_mode == :train_only
         data_path = get_kwarg(kwargs, :data_path, required=true)
@@ -218,6 +222,9 @@ function test_combo(test_mode; kwargs...)
 
     # make cue matrix/matrices
     # make semantic matrix/matrices
+    verbose && println("="^20)
+    verbose && println("Making cue matrix object...")
+    verbose && println("="^20)
 
     cue_obj_train, cue_obj_val = make_cue_train_val(
         data_train,
@@ -230,6 +237,14 @@ function test_combo(test_mode; kwargs...)
         start_end_token,
         if_combined,
         verbose)
+    for i in 1:10
+        display(cue_obj_train.i2f[i])
+        display(cue_obj_val.i2f[i])
+    end
+
+    verbose && println("="^20)
+    verbose && println("Making S matrix...")
+    verbose && println("="^20)
 
     n_features = size(cue_obj_train.C, 2)
     S_train, S_val = make_S_train_val(data_train, data_val,
@@ -247,6 +262,10 @@ function test_combo(test_mode; kwargs...)
         S_val = S_train[1:val_sample_size, :]
     end
 
+    verbose && println("="^20)
+    verbose && println("Learning transformation mapping F and G...")
+    verbose && println("="^20)
+
     learn_mode = get_kwarg(kwargs, :learn_mode, required=false)
 
     # cholesky params
@@ -311,6 +330,10 @@ function test_combo(test_mode; kwargs...)
             ":wh"))
     end
 
+    verbose && println("="^20)
+    verbose && println("Predicting S and C...")
+    verbose && println("="^20)
+
     Shat_train = cue_obj_train.C * F_train
     Shat_val = cue_obj_val.C * F_train
     Chat_train = S_train * G_train
@@ -350,6 +373,10 @@ function test_combo(test_mode; kwargs...)
         end
     end
 
+    verbose && println("="^20)
+    verbose && println("Performing path-finding algorithms...")
+    verbose && println("="^20)
+
     max_can = get_kwarg(kwargs, :max_can, required=false)
     threshold_train = get_kwarg(kwargs, :threshold_train, required=false)
     is_tolerant_train = get_kwarg(kwargs, :is_tolerant_train, required=false)
@@ -386,6 +413,7 @@ function test_combo(test_mode; kwargs...)
         sep_token = n_grams_sep_token,
         keep_sep = n_grams_keep_sep,
         target_col = n_grams_target_col,
+        start_end_token = start_end_token,
         issparse = issparse,
         sparse_ratio = sparse_ratio,
         verbose = verbose)
@@ -414,6 +442,7 @@ function test_combo(test_mode; kwargs...)
         sep_token = n_grams_sep_token,
         keep_sep = n_grams_keep_sep,
         target_col = n_grams_target_col,
+        start_end_token = start_end_token,
         issparse = issparse,
         sparse_ratio = sparse_ratio,
         verbose = verbose)
@@ -464,6 +493,10 @@ function test_combo(test_mode; kwargs...)
         verbose = verbose,
     )
 
+    verbose && println("="^20)
+    verbose && println("Evaluating results...")
+    verbose && println("="^20)
+
     acc_Chat_train = eval_SC(Chat_train, cue_obj_train.C)
     acc_Shat_train = eval_SC(Shat_train, S_train)
     acc_Shat_train_homo = eval_SC(Shat_train, S_train, data_train, n_grams_target_col)
@@ -496,6 +529,10 @@ function test_combo(test_mode; kwargs...)
         verbose=verbose
     )
 
+    verbose && println("="^20)
+    verbose && println("Saving outputs...")
+    verbose && println("="^20)
+
     output_dir = get_kwarg(kwargs, :output_dir, required=false)
 
     mkpath(output_dir)