readme updated, clarifications in script

EC-F14C-raw-data[example].csv

@@ -1,22 +1,15 @@
 F14C(EC)
-0.74 
-0.67 
-0.78 
-0.81 
-0.86 
-0.82 
-0.86 
-0.47 
-0.46 
-0.42 
-0.85 
-0.81 
-0.90 
-0.83 
-1.01 
-0.92 
-0.84 
-0.89 
-0.98 
-0.81 
-0.88 
+0.881
+0.597
+0.642
+0.689
+0.544
+0.748
+0.563
+0.184
+0.570
+0.527
+0.677
+0.767
+0.554
+

OC-F14C-raw-data[example].csv

@@ -1,22 +1,14 @@
 F14C(OC)
-0.80 
-0.69 
-0.78 
-0.83 
-0.83 
-0.80 
-0.66 
-0.46 
-0.60 
-0.54 
-0.94 
-0.90 
-0.88 
-0.76 
-0.90 
-0.90 
-0.81 
-0.76 
-0.86 
-0.82 
-0.80 
+0.749
+1.165
+0.951
+0.993
+1.095
+0.837
+0.492
+0.652
+1.014
+1.027
+0.802
+1.011
+0.756

changelog.txt

@@ -0,0 +1,61 @@
+####################################################################################
+#LOG file versions
+####################################################################################
+
+#v1.1.5: handful of changes in the corr_100_EC.R file as a result of the F14C_100EC correction issues in the WS01-003 EC data (measured with magazine C200610WSG and C200615WSG measured at LARA)
+
+#changes to corr_100_EC.R
+#8,6:
+#new      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
+#old      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
+#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
+#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
+
+#18,6:
+#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
+#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
+#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
+#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
+
+#25,6:
+#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
+#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
+#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
+#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
+
+#35,6
+#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
+#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
+#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
+#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
+
+#70,5
+#new      Ea_RT0<-7.5   # ----> max Ea/RT0 value <---  
+
+#79,5
+#new      up_par<-c(rep(Ea_RT0,n),rep(0.25,n))             #vector of upper bound a's and T's
+#old      up_par<-c(rep(5,n),rep(0.25,n))  
+
+#92,5
+#new      up_par<-c(rep(Ea_RT0,n_taken),rep(0.25,n_taken))             #vector of upper bound a's and T's
+#old      up_par<-c(rep(5,n_taken),rep(0.25,n_taken)) 
+
+#101,6
+#new      alfa.nv.all<-alfa0^(exp(Ea_RT0-(1/T))) # non volatile
+#old      alfa.nv.all<-alfa0^(exp(5-(1/T))) # non volatile
+#new      alfa.v.all<-alfa0^(exp(Ea_RT0-(b_fixed/T)))  # volatile
+#old      alfa.v.all<-alfa0^(exp(5-(b_fixed/T)))  # volatile
+
+#113,6
+#new      alfav_err_T<-b_fixed*log(alfa0)*exp(Ea_RT0-(b_fixed/T))*(1/T^2)*alfa0^(exp(Ea_RT0-(b_fixed/T)))
+#old      alfav_err_T<-b_fixed*log(alfa0)*exp(5-(b_fixed/T))*(1/T^2)*alfa0^(exp(5-(b_fixed/T)))
+#new      alfanv_err_T<-log(alfa0)*exp(Ea_RT0-(1/T))*(1/T^2)*alfa0^(exp(Ea_RT0-(1/T)))
+#old      alfanv_err_T<-log(alfa0)*exp(5-(1/T))*(1/T^2)*alfa0^(exp(5-(1/T)))
+
+#v1.1.4 Wildcard added to OC and EC F14C csv import
+#v1.1.3 Bug when subfolders go beyond src (letter S), so src changed to zsrc
+
+####################################################################################
+#end
+####################################################################################
+

compycalc.R

@@ -1,12 +1,15 @@
 ####################################################################################
-#COMPYCALC: COMprehensive Yield CALCulation 
 ####################################################################################
-#a tool to perform 14C OC/EC corrections with Sunset OC/EC analyzer laser data
+# COMPYCALC: COMprehensive Yield CALCulation 
+# A tool for EC yield extrapolation and charring correction 
+####################################################################################
 #written by Martin Rauber and Gary Salazar
 # Github: https://github.com/martin-rauber/compycalc
 #Version information: 1.1.5
 ####################################################################################
-#USER: follow the four instructions and run the script
+#USER:  follow the instructions and run the script
+#       details are written in the readme
+####################################################################################
 ####################################################################################
 
 #set wd-----------------------------------------------------------------------------
@@ -44,6 +47,7 @@
 ####################################################################################
 #USER: DO NOT change the script below this line                      
 ####################################################################################
+####################################################################################
 # prep.
 ####################################################################################
 #load libraries & install packages if necessary-------------------------------------
@@ -271,62 +275,6 @@ annotate_figure(fig_summary, top = text_grob(paste("\n",basename(getwd())," summ
                bottom = text_grob(paste(compycalc_version, "   ", Sys.info()[["user"]],Sys.time(), "  ",sep=" "), color = "black",  face = "italic", size = 10),)
 dev.off()
 
-####################################################################################
-#LOG file versions
-####################################################################################
-
-#v1.1.5: handful of changes in the corr_100_EC.R file as a result of the F14C_100EC correction issues in the WS01-003 EC data (measured with magazine C200610WSG and C200615WSG)
-
-#changes to corr_100_EC.R
-#8,6:
-#new      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
-#old      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
-#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
-#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
-
-#18,6:
-#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
-#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
-#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
-#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
-
-#25,6:
-#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
-#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
-#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
-#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
-
-#35,6
-#new      alfa.nv<-exp(log(alfa0)*exp(Ea_RT0-(1/T))) # non volatile
-#old      alfa.nv<-exp(log(alfa0)*exp(5-(1/T))) # non volatile
-#new      alfa.v<-exp(log(alfa0)*exp(Ea_RT0-(b/T)))  # volatile
-#old      alfa.v<-exp(log(alfa0)*exp(5-(b/T)))  # volatile
-
-#70,5
-#new      Ea_RT0<-7.5   # ----> max Ea/RT0 value <---  
-
-#79,5
-#new      up_par<-c(rep(Ea_RT0,n),rep(0.25,n))             #vector of upper bound a's and T's
-#old      up_par<-c(rep(5,n),rep(0.25,n))  
-
-#92,5
-#new      up_par<-c(rep(Ea_RT0,n_taken),rep(0.25,n_taken))             #vector of upper bound a's and T's
-#old      up_par<-c(rep(5,n_taken),rep(0.25,n_taken)) 
-
-#101,6
-#new      alfa.nv.all<-alfa0^(exp(Ea_RT0-(1/T))) # non volatile
-#old      alfa.nv.all<-alfa0^(exp(5-(1/T))) # non volatile
-#new      alfa.v.all<-alfa0^(exp(Ea_RT0-(b_fixed/T)))  # volatile
-#old      alfa.v.all<-alfa0^(exp(5-(b_fixed/T)))  # volatile
-
-#113,6
-#new      alfav_err_T<-b_fixed*log(alfa0)*exp(Ea_RT0-(b_fixed/T))*(1/T^2)*alfa0^(exp(Ea_RT0-(b_fixed/T)))
-#old      alfav_err_T<-b_fixed*log(alfa0)*exp(5-(b_fixed/T))*(1/T^2)*alfa0^(exp(5-(b_fixed/T)))
-#new      alfanv_err_T<-log(alfa0)*exp(Ea_RT0-(1/T))*(1/T^2)*alfa0^(exp(Ea_RT0-(1/T)))
-#old      alfanv_err_T<-log(alfa0)*exp(5-(1/T))*(1/T^2)*alfa0^(exp(5-(1/T)))
-
-#v1.1.4 Wildcard added to OC and EC F14C csv import
-#v1.1.2 to 1.1.3.R: bug when subfolders go beyond src (letter S), so src changed to zsrc
 
 ####################################################################################
 #end COMPYCALC

readme.md

@@ -2,11 +2,19 @@
 
 # COMprehensive Yield CALCulation 
 
-#### a tool for EC yield extrapolation and charring correction 
+#### A tool for EC yield extrapolation and charring correction 
 
-##  General usage 
+## Describtion
 
-To use the COMPYCALC program, follow the four steps written in the comment section of the `compycalc.R` file. This is the file you want to run, the other files in the subfolder are linked to this script. In the first section, you are asked to set the working directory, either with the command `setwd()` or by going to Session  → Set Working Directory  → To Source File Location if you are using [R Studio](https://rstudio.com). 
+COMPYCALC is a R script for EC yield extrapolation and charring correction. The script uses the the raw data output from a thermo-optical OC/EC analyzer (Model 5L, [Sunset Laboratory Inc.](https://www.sunlab.com), OR, United States) running the Swiss_3S protocol for OC/EC separation developed by [Zhang et al. (2012)](https://doi.org/10.5194/acp-12-10841-2012) for EC yield and charring calculation. Using F<sup>14</sup>C(EC) values measured by accelerator mass spectrometry (AMS) and calculated F<sup>14</sup>OC values, the script performs the EC yield extrapolation to 100% EC yield and a charring correction to 0% charring for F<sup>14</sup>C(EC) values.
+
+##  Usage 
+
+To use the run COMPYCALC program, follow the steps written in the comment section of the `compycalc.R` file. This is the file you want to run, the other files in the subfolder (zsrc) are linked to this script. 
+
+### Step 1: set up environment
+
+In the first section, you are asked to set the working directory, either with the command `setwd()` or by going to Session  &rarr; Set Working Directory  &rarr; To Source File Location if you are using [R Studio](https://rstudio.com). 
 
 ```
 #set wd-----------------------------------------------------------------------------
@@ -18,7 +26,9 @@ To use the COMPYCALC program, follow the four steps written in the comment secti
 #setwd("")
 ```
 
-In the second step, you are ask to add your Sunset raw files in folders to the working directory folder. Obviously, you can also do it the other way around by adding the `compycalc.R` script to the folder where your data is. Now please be aware that the script will take the last digit of each folder for naming, so at best name your folders with xxx-[letter] (xxx-A, xxx-B, …). 
+### Step 2: add OC/EC analyzer files
+
+In the second step, you are ask to add your Sunset raw files in folders to the working directory folder. Obviously, you can also do it the other way around by adding the `compycalc.R` script to the folder where your data is. Now please be aware that the script will take the last digit of each folder for naming, so at best name your folders with xyz-[letter] (xyz-A, xyz-B, …). 
 
 ```
 #add data---------------------------------------------------------------------------
@@ -28,7 +38,9 @@ In the second step, you are ask to add your Sunset raw files in folders to the w
 
 ```
 
-Last but not least you have to add the F14C EC and OC raw data. These need to be in sample order and in a csv file in the working directory, i.e. the folder where your `compycalc.R` file is. 
+### Step 3: add radiocarbon data
+
+Last but not least you have to add the F<sup>14</sup>C(EC) and F<sup>14</sup>OC raw data. These need to be in sample order and in a csv file in the working directory, i.e. the folder where your `compycalc.R` file is. 
 
 ```
 # 3)  enter F14C EC and OC raw data
@@ -45,7 +57,9 @@ Last but not least you have to add the F14C EC and OC raw data. These need to be
           #F14C_OC_raw_data = c()
 ```
 
-Finally, you are ready to run the code. 
+### Step 4: run code
+
+Finally, you are ready to run the COMPYCALC script. 
 
 ```
 # 4)  run script
@@ -55,17 +69,24 @@ Finally, you are ready to run the code.
 #         - wd folder will get "your-wd-name-here"-mean-summary-with-F14C.csv and "your-wd-name-here"-F14C_and_EC-yield-and-charring-summary.pdf
 ```
 
-These For best results, you use the uncorrected EC and OC values, run COMPYCALC and and use the corrected EC and OC F<sup>14</sup>C values for a second run. After this iteration, the differences should be minuscule and you can use the fine EC and OC data. 
+### Step 5: iteration
+
+For best results, it's recommended to run COMPYCALC at least twice to use a corrected F<sup>14</sup>OC. First you use the uncorrected F<sup>14</sup>C(EC) and calculated F<sup>14</sup>OC values (raw data) and run the script, then use the corrected F<sup>14</sup>C(EC) vaule for the calculation  of the first run corrected of F<sup>14</sup>OC. Now run COMPYCALC again with the first run corrected F<sup>14</sup>C(EC) & F<sup>14</sup>OC. With the F<sup>14</sup>C(EC) result of the second run you can calculate the final F<sup>14</sup>OC:
+ <br/> <br/>
+Initial F<sup>14</sup>C(EC) & F<sup>14</sup>C(OC) &rarr; **first run** of COMPYCALC &rarr; calculation of first run corrected of F<sup>14</sup>OC &rarr; **second run** of COMPYCALC &rarr; **final F<sup>14</sup>C(EC)** and calculation of **final F<sup>14</sup>C(OC)**
+<br/> 
+
+After this iteration the differences should be minuscule and you can use the final F<sup>14</sup>C(EC) and F<sup>14</sup>C(OC) values. 
 
 ## How does COMPYCALC work?
 
-COMPYCALC (COMprehensive Yield CALCulation) consists of three subscripts for data input and output, EC yield and charring, as well as an extrapolation of the F<sup>14</sup>C(EC) values to 100% EC yield. For each sample, the OC/EC analyzer raw data files containing the laser transmission signal for each OC removal run need to be in a designated subfolder. Additionally, the script requires the uncorrected F<sup>14</sup>C(EC) and F<sup>14</sup>C(OC) data in separate files (csv format) in the main folder. The data input and output script loads the OC/EC analyzer raw data files for each sample folder and initiates the calculation with the EC yield and charring script. The results written in each sample folder is then read by the main script and forwarded to the second calculation script for the correction to 100% EC yield. Finally, the F<sup>14</sup>C(EC) value extrapolated to 100% EC yield corrects for charring in the main script, as this should be regarded as an OC contamination of the measured EC. After all calculations, a summary data file (csv) with overall EC yield, the charring contribution for each OC removal step (S1, S2, S3), the total charring contribution as well as the raw F<sup>14</sup>C(EC), F<sup>14</sup>C(EC) extrapolated to 100% EC yield, and F<sup>14</sup>C(EC) extrapolated to 100% EC yield and corrected for charring is generated as an output. Additionally, a summary pdf is generated with plots for all F<sup>14</sup>C results, EC yields, and charring for each step (S1, S2, S3). 
+COMPYCALC (COMprehensive Yield CALCulation) consists of three subscripts for data input and output, EC yield and charring, as well as an extrapolation of the F<sup>14</sup>C(EC) values to 100% EC yield. For each sample, the OC/EC analyzer raw data files containing the laser transmission signal for each OC removal run need to be in a designated subfolder. Additionally, the script requires the uncorrected F<sup>14</sup>C(EC) and F<sup>14</sup>C(OC) data in separate files (csv format) in the main folder. The data input and output script loads the OC/EC analyzer raw data files for each sample folder and initiates the calculation with the EC yield and charring script. The results written in each sample folder is then read by the main script and forwarded to the second calculation script for the extrapolation to 100% EC yield. Finally, the F<sup>14</sup>C(EC) value extrapolated to 100% EC yield is corrected for charring in the main script, as this should be regarded as an OC contamination of the measured EC. After all calculations, a summary data file (csv) with overall EC yield, the charring contribution for each OC removal step (S1, S2, S3), the total charring contribution as well as the raw F<sup>14</sup>C(EC), F<sup>14</sup>C(EC) extrapolated to 100% EC yield, and F<sup>14</sup>C(EC) extrapolated to 100% EC yield and corrected for charring is generated as an output. Additionally, a summary pdf is generated with plots for all F<sup>14</sup>C results, EC yields, and charring for each step (S1, S2, S3). 
 
 ![COMPYCALC scheme](How-does-COMPYCALC-work.png "COMPYCALC scheme")
 
-## About
+## Authors
 
-This tool was written by [Martin Rauber](https://martin-rauber.com) and [Gary Salazar](mailto:gary.salazar@dcb.unibe.ch) for LARA, the Laboratory for the Analysis of Radiocarbon with AMS at the University of Bern. Please get in touch for any bug fixes and suggestions!
+This tool was written by [Martin Rauber](https://www.martin-rauber.com) and [Gary Salazar](mailto:gary.salazar@dcb.unibe.ch) for LARA, the [Laboratory for the Analysis of Radiocarbon with AMS](https://www.14c.unibe.ch) at the University of Bern. Please get in touch for any bug fixes and suggestions!
 
 ## Licence