From 9a1e685a636f7632fc77c7375f9d42735be2decc Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Tue, 9 Jul 2019 12:34:04 +0200 Subject: More adaptations to mkin 0.9.49.6, update manual Static documentation rebuilt by pkgdown --- .Rbuildignore | 21 +- GNUmakefile | 17 +- NEWS.md | 4 +- README.html | 2 +- docs/articles/gmkin_manual.html | 55 +- docs/articles/img/configuration.png | Bin 100479 -> 152482 bytes docs/articles/img/gmkin_start.png | Bin 97244 -> 87653 bytes docs/articles/img/plotoptions.png | Bin 15186 -> 14740 bytes docs/articles/index.html | 4 +- docs/authors.html | 4 +- docs/gmkin_screenshot.png | Bin 134864 -> 182718 bytes docs/index.html | 7 +- docs/news/index.html | 4 +- docs/pkgdown.yml | 2 +- docs/reference/FOCUS_2006.html | 4 +- docs/reference/FOCUS_2006_Z.html | 4 +- docs/reference/UBA_model_gallery.html | 4 +- docs/reference/gmkin.html | 48 +- docs/reference/gmkinws.html | 4 +- docs/reference/index.html | 4 +- inst/GUI/gmkin.R | 6 +- vignettes/gmkin_manual.Rmd | 69 +- vignettes/gmkin_manual.html | 1188 +++++++++++++++++---------------- vignettes/img/configuration.png | Bin 100479 -> 152482 bytes vignettes/img/gmkin_start.png | Bin 97244 -> 87653 bytes vignettes/img/plotoptions.png | Bin 15186 -> 14740 bytes 26 files changed, 730 insertions(+), 721 deletions(-) diff --git a/.Rbuildignore b/.Rbuildignore index bc6b972..c9e467f 100644 --- a/.Rbuildignore +++ b/.Rbuildignore @@ -1,12 +1,9 @@ -GNUmakefile -README.html -gmkin_.*\.tar\.gz -gmkin_.*\.zip -gmkin_screenshot.png -Rprofile -vignettes/.build.timestamp -vignettes/cache -vignettes/gmkin_manual_cache -vignettes/gmkin_manual.R -vignettes/gmkin_manual.md -inst/GUI/gmkin_workflow_inkscape.svg +^GNUmakefile$ +^README.html$ +^gmkin_.*\.tar\.gz$ +^gmkin_.*\.zip$ +^gmkin_screenshot.png$ +^Rprofile$ +^inst/GUI/gmkin_workflow_inkscape.svg$ +^docs$ +^_pkgdown\.yml$ diff --git a/GNUmakefile b/GNUmakefile index 5078d82..b2399d7 100644 --- a/GNUmakefile +++ b/GNUmakefile @@ -2,7 +2,6 @@ PKGNAME := $(shell sed -n "s/Package: *\([^ ]*\)/\1/p" DESCRIPTION) PKGVERS := $(shell sed -n "s/Version: *\([^ ]*\)/\1/p" DESCRIPTION) PKGDIR := $(PWD) TGZ := $(PKGNAME)_$(PKGVERS).tar.gz -TGZVNR := $(PKGNAME)_$(PKGVERS)-vignettes-not-rebuilt.tar.gz WINBIN := $(PKGNAME)_$(PKGVERS).zip # Specify the directory holding R binaries. To use an alternate R build (say a @@ -17,6 +16,7 @@ RFDIR ?= $(RFSVN)/pkg/gmkin SDDIR ?= $(RFSVN)/www/gmkin_static pkgfiles = NEWS.md \ + .Rbuildignore \ data/* \ DESCRIPTION \ inst/GUI/* \ @@ -34,17 +34,11 @@ all: check clean $(TGZ): $(pkgfiles) "$(RBIN)/R" CMD build . -$(TGZVNR): $(pkgfiles) - "$(RBIN)/R" CMD build --no-build-vignettes . ;\ - mv $(TGZ) $(TGZVNR) - roxygen: "$(RBIN)/Rscript" -e 'devtools::document()' build: roxygen $(TGZ) -build-no-vignettes: $(TGZVNR) - $(WINBIN): build @echo "Building windows binary package..." "$(RBIN)/R" CMD INSTALL $(TGZ) --build @@ -55,17 +49,8 @@ winbin: $(WINBIN) install: build "$(RBIN)/R" CMD INSTALL $(TGZ) -install-no-vignettes: build-no-vignettes - "$(RBIN)/R" CMD INSTALL $(TGZVNR) - check: build - # Vignettes have been rebuilt by the build target - "$(RBIN)/R" CMD check --no-tests --no-build-vignettes $(TGZ) - -check-no-vignettes: build-no-vignettes - mv $(TGZVNR) $(TGZ) "$(RBIN)/R" CMD check --no-tests $(TGZ) - mv $(TGZ) $(TGZVNR) README.html: README.md "$(RBIN)/Rscript" -e "rmarkdown::render('README.md', output_format = 'html_document', output_options = list(self_contained = TRUE))" diff --git a/NEWS.md b/NEWS.md index a6aea8d..1dd1be6 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,8 +1,8 @@ # NEWS for package 'gmkin' -## gmkin 0.6-10 (2019-07-08) +## gmkin 0.6-10 (2019-07-09) -- Adapt to mkin 0.9.49.6 +- Adapt to mkin 0.9.49.6, making the new way to fit variance by variable and the two-component error model available to gmkin - Use devEMF for better vector graphics export for Windows diff --git a/README.html b/README.html index 6a09eeb..9d38844 100644 --- a/README.html +++ b/README.html @@ -403,7 +403,7 @@ $(document).ready(function () { 
install.packages("gmkin")

The latest changes to gmkin are recorded in the NEWS file, more details can be found in the commit history.

-gmkin screenshot +gmkin screenshot

gmkin screenshot

diff --git a/docs/articles/gmkin_manual.html b/docs/articles/gmkin_manual.html index 5d7d5b3..c1e58ec 100644 --- a/docs/articles/gmkin_manual.html +++ b/docs/articles/gmkin_manual.html @@ -30,7 +30,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -76,7 +76,7 @@

Manual for gmkin

Johannes Ranke

-

2019-03-14

+

2019-07-09

@@ -88,8 +88,8 @@

Introduction

-

The R add-on package gmkin provides a browser based graphical interface for performing kinetic evaluations of degradation data using the mkin package. While the use of gmkin should be largely self-explanatory, this manual may serve as a functionality overview and reference.

-

For system requirements and installation instructions, please refer to the gmkin homepage.

+

The R add-on package gmkin provides a browser based graphical interface for performing kinetic evaluations of degradation data using the mkin package. While the use of gmkin should be largely self-explanatory, this manual may serve as a functionality overview and reference.

+

For system requirements and installation instructions, please refer to the gmkin homepage.

@@ -216,10 +216,8 @@

The parameters “atol” and “rtol” are only effective if the solution type is “deSolve”. They control the precision of the iterative numerical solution of the differential equation model.

The checkboxes “transform_rates” and “transform_fractions” control if the parameters are fitted as defined in the model, or if they are internally transformed during the fitting process in order to improve the estimation of standard errors and confidence intervals which are based on a linear approximation at the optimum found by the fitting algorithm.

If fitting with transformed fractions leads to a suboptimal fit, doing a first run without transforming fractions may help. A final run using the optimised parameters from the previous run as starting values (see comment on “Get initials from” above) can then be performed with transformed fractions.

-

The dropdown box “weight” specifies if and how the observed values should be weighted in the fitting process. If “manual” is chosen, the values in the “err” column of the dataset are used, which are set to unity by default. Setting these to higher values gives lower weight and vice versa. If “none” is chosen, observed values are not weighted. Please refer to the documentation of the modFit function from the FME package for the meaning of options “std” and “mean”.

-

If the “IRLS” option is set to “obs”, then we make use of iteratively reweighted least squares fitting. Please refer to the mkinfit documentation for more details. IRLS fitting can be configured using the options “reweight.tol” and “reweight.max.iter”.

-

The drop down box “method.modFit” makes it possible to choose between the optimisation algorithms “Port” (the default in mkin versions > 0.9-33, a local optimisation algorithm using a model/trust region approach), “Marq” (the former default in mkin, a Levenberg-Marquardt variant from the R package minpack.lm), and “SANN” (the simulated annealing method - robust but inefficient and without a convergence criterion).

-

Finally, the maximum number of iterations for the optimisation can be adapted using the “maxit.modFit” field.

+

If the “error_model” option is set to “obs” or “tc”, then a suitable “error_model_algorithm” has to be selected. The recommended algorithm for these error model is “d_3”, which is the one selected by “mkin” for there error models. Please refer to the mkinfit documentation for more details. IRLS fitting can be configured using the options “reweight.tol” and “reweight.max.iter”.

+

The maximum number of iterations for the optimisation can be adapted using the “maxit” field.

@@ -228,7 +226,7 @@
plot options

plot options

-

On systems running the Windows operating system, the windows metafile (wmf) format can be additionally chosen. Changing the file format for plotting will also change the extension of the proposed filename for saving the plot.

+

On systems running the Windows operating system, the enhanced metafile (emf) format can be additionally chosen. Changing the file format for plotting will also change the extension of the proposed filename for saving the plot.

@@ -242,23 +240,21 @@

Fitting the model

In many cases the starting parameters and the fit options do not need to be modified and the model fitting process can simply be started by pressing the “Run fit” button. In the R console, the progressive reduction in the model cost can be monitored and will be displayed in the following way:

- +

If plotting of the fitting progress was selected, a new separate graphics window should either pop up, or a graphics window previously started for this purpose will be reused.

If your screen size allows for it, you can arrange the R plotting window and the R console in a way that you can see everything at the same time:

@@ -326,7 +322,7 @@
  • Press ‘Keep changes’
  • Select the ‘Model gallery’ to the right
  • From the model gallery, press ‘FOMC, one met’ below the corresponding model scheme
    • -
  • In the dataset explorer, select ‘Test dataset howto 2’
    • +
  • In the dataset explorer, select ‘Data howto 2’
  • In the model explorer, select ‘FOMC, one met’
  • In the configuration display, press ‘Configure fit’
  • In the configuration editor in the center, press ‘Run fit’
    • @@ -355,7 +351,8 @@
  • Enter ‘DFOP lin’ as the model name
  • Select ‘max’ in the dropbox ‘Use of formation fractions’
  • Press ‘Add observed variable’ three times
    • -
  • In the line where ‘parent’ is selected, in the dropbox after the word ‘to’, select ‘M1’
    • +
  • In the line where ‘parent’ is selected, in the dropbox to the right change ‘SFO’ to ‘DFOP’
    • +
  • In the line where ‘parent’ is selected, after the word ‘to’, select ‘M1’
  • Click outside the dropbox
  • In the line where ‘M1’ is selected, in the dropbox after the word ‘to’, select ‘M2’
  • Click outside the dropbox
    • @@ -400,7 +397,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/articles/img/configuration.png b/docs/articles/img/configuration.png index 1a18608..12dc195 100644 Binary files a/docs/articles/img/configuration.png and b/docs/articles/img/configuration.png differ diff --git a/docs/articles/img/gmkin_start.png b/docs/articles/img/gmkin_start.png index 9b494ec..92d2325 100644 Binary files a/docs/articles/img/gmkin_start.png and b/docs/articles/img/gmkin_start.png differ diff --git a/docs/articles/img/plotoptions.png b/docs/articles/img/plotoptions.png index 24cda2d..a3f1b06 100644 Binary files a/docs/articles/img/plotoptions.png and b/docs/articles/img/plotoptions.png differ diff --git a/docs/articles/index.html b/docs/articles/index.html index bb2278b..49817ae 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -60,7 +60,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -126,7 +126,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/authors.html b/docs/authors.html index 85ee6e1..f148358 100644 --- a/docs/authors.html +++ b/docs/authors.html @@ -60,7 +60,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -135,7 +135,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/gmkin_screenshot.png b/docs/gmkin_screenshot.png index 3a1afa7..38b1ad0 100644 Binary files a/docs/gmkin_screenshot.png and b/docs/gmkin_screenshot.png differ diff --git a/docs/index.html b/docs/index.html index a9c7511..f2daa55 100644 --- a/docs/index.html +++ b/docs/index.html @@ -32,7 +32,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -82,7 +82,7 @@

    System requirements

    For running gmkin you need a system running a recent version of R (version 3.1.0 or later), the gWidgesWWW2 package, the gmkin package and a web browser (Firefox/Iceweasel and Chrome work for me) with JavaScript enabled.

    -

    It should be possible to run gmkin on most laptop or desktop computers running Linux, Mac OS X, Windows XP or Windows 7. It is frequently checked under Linux and Windows 7.

    +

    It should be possible to run gmkin on most laptop or desktop computers running Linux, Mac OS X, Windows 7 or Windows 10.

    To view the complete set of widgets in the browser window without resizing anything, it needs a screen space of 1366x740 pixels.

    @@ -159,6 +159,7 @@

    Acknowledgements

    Financial support, feedback and suggestions by the German Federal Environmental Agency (Umweltbundesamt) in two projects in 2014 and 2015 was crucial for reaching version 0.6.3 in November 2015 and is gratefully acknowledged. In particular, Stefan Meinecke contributed with a lot of user feedback and suggestions for improvement in that time.

    +

    The adaptation to mkin versions > 0.9.49.6 that can do fits using a two-component error model was supported by another project by the Umweltbundesamt in 2018/2019.

    @@ -193,7 +194,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/news/index.html b/docs/news/index.html index 5055106..f9e4e28 100644 --- a/docs/news/index.html +++ b/docs/news/index.html @@ -60,7 +60,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -128,7 +128,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index b60ebd0..85c5bf3 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -1,5 +1,5 @@ pandoc: 2.2.1 -pkgdown: 1.3.0.9000 +pkgdown: 1.3.0 pkgdown_sha: ~ articles: gmkin_manual: gmkin_manual.html diff --git a/docs/reference/FOCUS_2006.html b/docs/reference/FOCUS_2006.html index 57bb310..9066d83 100644 --- a/docs/reference/FOCUS_2006.html +++ b/docs/reference/FOCUS_2006.html @@ -65,7 +65,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -168,7 +168,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/reference/FOCUS_2006_Z.html b/docs/reference/FOCUS_2006_Z.html index e3309c7..8df70a6 100644 --- a/docs/reference/FOCUS_2006_Z.html +++ b/docs/reference/FOCUS_2006_Z.html @@ -63,7 +63,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -163,7 +163,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/reference/UBA_model_gallery.html b/docs/reference/UBA_model_gallery.html index 3cf9e12..d302d27 100644 --- a/docs/reference/UBA_model_gallery.html +++ b/docs/reference/UBA_model_gallery.html @@ -68,7 +68,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -169,7 +169,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/reference/gmkin.html b/docs/reference/gmkin.html index 8740e7d..f3e9729 100644 --- a/docs/reference/gmkin.html +++ b/docs/reference/gmkin.html @@ -33,8 +33,8 @@ +github page of gWidgetsWWW2 +for an explanation how this toolkit works." /> @@ -65,7 +65,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -119,8 +119,8 @@

    This function starts a browser based GUI. Please visit the - github page of gWidgetsWWW2 - for an explanation how this toolkit works.

    +github page of gWidgetsWWW2 +for an explanation how this toolkit works.

    @@ -131,38 +131,24 @@ script_name -

    During development, a script name with a local working version - of gmkin can be passed. Defaults to the location of the gmkin.R script - shipped with the package.

    +

    During development, a script name with a local working +version of gmkin can be passed. Defaults to the location of the gmkin.R +script shipped with the package.

    show.log -

    During development, it may be useful to see the log of the Rook apps.

    +

    During development, it may be useful to see the log of the +Rook apps.

    Value

    -

    The function is called for its side effect, namely starting the GUI in a browser. - For the curious, the desperate or the adventurous, the gmkin app (a GWidgetsApp object) is returned.

    +

    The function is called for its side effect, namely starting the GUI + in a browser. For the curious, the desperate or the adventurous, the gmkin + app (a GWidgetsApp object) is returned.

    -

    Examples

    - 
      
    # NOT RUN {
-gmkin()
-# }
     # Start the gmkin GUI
-  
    # NOT RUN {
-    g <- gmkin()
-
-    # Only for debugging or other advanced usage:
-    session <- gmkin:::get_current_session(g)
-    session$p.df
-    session$ds.df
-    session$ds.cur
-    session$m.cur
-    session$ws
-
-# }
    @@ -185,7 +167,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/reference/gmkinws.html b/docs/reference/gmkinws.html index d2f667f..4a264e9 100644 --- a/docs/reference/gmkinws.html +++ b/docs/reference/gmkinws.html @@ -63,7 +63,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -157,7 +157,7 @@ by the names used in the models contained in field m

    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/docs/reference/index.html b/docs/reference/index.html index cc279d2..96635b9 100644 --- a/docs/reference/index.html +++ b/docs/reference/index.html @@ -60,7 +60,7 @@ gmkin - 0.6.9 + 0.6.10 @@ -173,7 +173,7 @@
    -

    Site built with pkgdown 1.3.0.9000.

    +

    Site built with pkgdown 1.3.0.

    diff --git a/inst/GUI/gmkin.R b/inst/GUI/gmkin.R index 1320da0..7e0a052 100644 --- a/inst/GUI/gmkin.R +++ b/inst/GUI/gmkin.R @@ -1108,9 +1108,9 @@ show_plot <- function(type) { state.ini = stateparms, fixed_parms = names(deparms), fixed_initials = names(stateparms), - err = "err", quiet = TRUE, - method.modFit = "Marq", - control.modFit = list(maxiter = 0))) + transform_fraction = FALSE, # to be able to fix ff + quiet = TRUE, + control = list(iter.max = 0))) ftmp$ds <<- ds.cur } svalue(plot.ftmp.gi) <<- plot_ftmp_png() diff --git a/vignettes/gmkin_manual.Rmd b/vignettes/gmkin_manual.Rmd index 45dae83..26ebe4d 100644 --- a/vignettes/gmkin_manual.Rmd +++ b/vignettes/gmkin_manual.Rmd @@ -21,12 +21,12 @@ opts_chunk$set(tidy = FALSE, cache = FALSE) The R add-on package gmkin provides a browser based graphical interface for performing kinetic evaluations of degradation data using the -[mkin package](http://kinfit.r-forge.r-project.org/mkin_static). +[mkin package](https://pkgdown.jrwb.de/mkin). While the use of gmkin should be largely self-explanatory, this manual may serve as a functionality overview and reference. For system requirements and installation instructions, please refer to the -[gmkin homepage](http://kinfit.r-forge.r-project.org/gmkin_static). +[gmkin homepage](https://pkgdown.jrwb.de/gmkin). ## Starting gmkin @@ -289,28 +289,16 @@ run without transforming fractions may help. A final run using the optimised parameters from the previous run as starting values (see comment on "Get initials from" above) can then be performed with transformed fractions. -The dropdown box "weight" specifies if and how the observed values should be weighted -in the fitting process. If "manual" is chosen, the values in the "err" column of the -dataset are used, which are set to unity by default. Setting these to higher values -gives lower weight and vice versa. If "none" is chosen, observed -values are not weighted. Please refer to the documentation of the `modFit` function from -the `FME` package for the meaning of options "std" and "mean". - -If the "IRLS" option is set to "obs", then we make use of iteratively -reweighted least squares fitting. Please refer to the `mkinfit` -[documentation](http://kinfit.r-forge.r-project.org/mkin_static/mkinfit.html) +If the "error_model" option is set to "obs" or "tc", then a suitable +"error_model_algorithm" has to be selected. The recommended algorithm for these +error model is "d_3", which is the one selected by "mkin" for there error models. +Please refer to the `mkinfit` +[documentation](https://pkgdown.jrwb.de/mkin/reference) for more details. IRLS fitting can be configured using the options "reweight.tol" and "reweight.max.iter". -The drop down box "method.modFit" makes it possible to choose between the optimisation -algorithms "Port" (the default in mkin versions > 0.9-33, a local optimisation -algorithm using a model/trust region approach), "Marq" (the former default in -mkin, a Levenberg-Marquardt variant from the R package `minpack.lm`), -and "SANN" (the simulated annealing method - robust but inefficient and without -a convergence criterion). - -Finally, the maximum number of iterations for the optimisation can be adapted using the -"maxit.modFit" field. +The maximum number of iterations for the optimisation can be adapted using the +"maxit" field. ### Plot options @@ -320,7 +308,7 @@ the model fit should be plotted can be selected as shown below. ![plot options](img/plotoptions.png) -On systems running the Windows operating system, the windows metafile (wmf) format +On systems running the Windows operating system, the enhanced metafile (emf) format can be additionally chosen. Changing the file format for plotting will also change the extension of the proposed filename for saving the plot. @@ -351,23 +339,21 @@ In the R console, the progressive reduction in the model cost can be monitored a be displayed in the following way: ```{r, eval = FALSE} -Model cost at call 1 : 15156.12 -Model cost at call 3 : 15156.12 -Model cost at call 7 : 14220.79 -Model cost at call 8 : 14220.79 -Model cost at call 11 : 14220.79 -Model cost at call 12 : 3349.268 -Model cost at call 15 : 3349.268 -Model cost at call 17 : 788.6367 -Model cost at call 18 : 788.6366 -Model cost at call 22 : 374.0575 -Model cost at call 23 : 374.0575 -Model cost at call 27 : 371.2135 -Model cost at call 28 : 371.2135 -Model cost at call 32 : 371.2134 -Model cost at call 36 : 371.2134 -Model cost at call 37 : 371.2134 -Optimisation by method Port successfully terminated. +> Ordinary least squares optimisation +Sum of squared residuals at call 1: 2388.077 +Sum of squared residuals at call 3: 2388.077 +Sum of squared residuals at call 4: 247.1962 +Sum of squared residuals at call 7: 200.6791 +Sum of squared residuals at call 10: 197.7231 +Sum of squared residuals at call 11: 197.0872 +Sum of squared residuals at call 14: 196.535 +Sum of squared residuals at call 15: 196.535 +Sum of squared residuals at call 16: 196.535 +Sum of squared residuals at call 17: 196.5334 +Sum of squared residuals at call 20: 196.5334 +Sum of squared residuals at call 25: 196.5334 +Negative log-likelihood at call 31: 26.64668 +Optimisation successfully terminated. ``` If plotting of the fitting progress was selected, a new separate graphics @@ -444,7 +430,7 @@ before releasing a new version. - Press 'Keep changes' - Select the 'Model gallery' to the right - From the model gallery, press 'FOMC, one met' below the corresponding model scheme -- In the dataset explorer, select 'Test dataset howto 2' +- In the dataset explorer, select 'Data howto 2' - In the model explorer, select 'FOMC, one met' - In the configuration display, press 'Configure fit' - In the configuration editor in the center, press 'Run fit' @@ -470,7 +456,8 @@ before releasing a new version. - Enter 'DFOP lin' as the model name - Select 'max' in the dropbox 'Use of formation fractions' - Press 'Add observed variable' three times -- In the line where 'parent' is selected, in the dropbox after the word 'to', select 'M1' +- In the line where 'parent' is selected, in the dropbox to the right change 'SFO' to 'DFOP' +- In the line where 'parent' is selected, after the word 'to', select 'M1' - Click outside the dropbox - In the line where 'M1' is selected, in the dropbox after the word 'to', select 'M2' - Click outside the dropbox diff --git a/vignettes/gmkin_manual.html b/vignettes/gmkin_manual.html index b1c3c6e..e9f2bca 100644 --- a/vignettes/gmkin_manual.html +++ b/vignettes/gmkin_manual.html @@ -1,677 +1,737 @@ - + + + - -Introduction + + + - - - + + + + + + + + -body { - max-width: 800px; - margin: auto; - padding: 1em; - line-height: 20px; -} -tt, code, pre { - font-family: 'DejaVu Sans Mono', 'Droid Sans Mono', 'Lucida Console', Consolas, Monaco, monospace; -} + -pre, img { - max-width: 100%; -} -pre { - overflow-x: auto; + + + + -@media print { - * { - background: transparent !important; - color: black !important; - filter:none !important; - -ms-filter: none !important; - } - body { - font-size:12pt; - max-width:100%; - } - a, a:visited { - text-decoration: underline; - } + - hr { - visibility: hidden; - page-break-before: always; - } + + - + - -

    Introduction

    -

    The R add-on package gmkin provides a browser based graphical interface for -performing kinetic evaluations of degradation data using the -mkin package. -While the use of gmkin should be largely self-explanatory, this manual may serve -as a functionality overview and reference.

    -

    For system requirements and installation instructions, please refer to the -gmkin homepage.

    -

    Starting gmkin

    + -

    As gmkin is an R package, you need to start R and load the gmkin package before you can run gmkin. -The latter can be achieved by entering the command

    + -
    library(gmkin)
-
    -

    into the R console. This will also load the packages that gmkin depends on, -most notably gWidgetsWWW2 and mkin. Loading the package only has to be done -once after you have started R.

    +
    -

    Before you start gmkin, you should make sure that R is using the working -directory that you would like to keep your gmkin project file(s) in. If you use -the standard R GUI application on windows, you can change the working directory -from the File menu ('File' -> 'Change dir…').

    -

    Once you are sure that the working directory is what you want it to be, gmkin -can be started by entering the R command

    -
    gmkin()
-
    -

    This will cause the default browser to start up or, if it is already running, to -pop up and open a new tab for displaying the gmkin user interface.

    + -

    If the browser only shows “Loading ExtJS…” and nothing else happens for about 10 to 15 seconds, -please enter the gmkin() command again in the R console. If this still does not bring up the -gmkin GUI, please close the browser and try again.

    + +
    +

    Introduction

    +

    The R add-on package gmkin provides a browser based graphical interface for performing kinetic evaluations of degradation data using the mkin package. While the use of gmkin should be largely self-explanatory, this manual may serve as a functionality overview and reference.

    +

    For system requirements and installation instructions, please refer to the gmkin homepage.

    +
    +
    +

    Starting gmkin

    +

    As gmkin is an R package, you need to start R and load the gmkin package before you can run gmkin. The latter can be achieved by entering the command

    +
    library(gmkin)
    +

    into the R console. This will also load the packages that gmkin depends on, most notably gWidgetsWWW2 and mkin. Loading the package only has to be done once after you have started R.

    +

    Before you start gmkin, you should make sure that R is using the working directory that you would like to keep your gmkin project file(s) in. If you use the standard R GUI application on windows, you can change the working directory from the File menu (‘File’ -> ‘Change dir…’).

    +

    Once you are sure that the working directory is what you want it to be, gmkin can be started by entering the R command

    +
    gmkin()
    +

    This will cause the default browser to start up or, if it is already running, to pop up and open a new tab for displaying the gmkin user interface.

    +

    In the R console, you should see a message that the httpd help server is started, if it wasn’t already started before.

    +

    In the browser, you should see something like the screenshot below.

    +
    +Screenshot of the newly started gmkin GUI +

    Screenshot of the newly started gmkin GUI

    +
    +

    The statusbar at the bottom of the gmkin window shows, among others, the working directory that gmkin uses.

    +

    If the browser only shows “Loading ExtJS…” and nothing else happens for about 10 to 15 seconds, please enter the gmkin() command again in the R console. If this still does not bring up the gmkin GUI, please close the browser and try again.

    +
    +

    Three column layout

    - -

    Since version 0.6.1, gmkin adheres to a three column layout. To the left, there are explorer -areas for the available projects, datasets, kinetic models and the completed fits.

    - -

    In the central, tabbed area, the projects, datasets, models and fits are defined. The area -to the right is mainly for showing information intended to support the user, and results. -However, it also contains a tab 'Data' for editing kinetic data.

    - +

    Since version 0.6.1, gmkin adheres to a three column layout. To the left, there are explorer areas for the available projects, datasets, kinetic models and the completed fits.

    +

    In the central, tabbed area, the projects, datasets, models and fits are defined. The area to the right is mainly for showing information intended to support the user, and results. However, it also contains a tab ‘Data’ for editing kinetic data.

    +
    +

    Project file management

    - -

    At startup, the project explorer to the left shows the two project workspaces 'FOCUS_2006' and -'FOCUS_2006_Z' delivered with the package. The project manangement area in the -center gives the possibility to save these projects under a new name, or to -start a new, empty project.

    - -

    A gmkin project workspace contains datasets, kinetic models for fitting, and -so-called fits, i.e. the results of fitting models to data. The project area also shows the current -working directory, where project workspace files are saved using the file extension .gmkinws.

    - -

    Once a project has been saved by the user, the project explorer to the left will show it in the -project list.

    - -

    Screenshot of saving a new project

    - -

    The current state of a project should repeatedly be saved during the work in order to avoid -loosing data. This can be achieved by selecting the 'Project' tab in the center and pressing -the 'Save project to project file' button. More conveniently, the keyboard shortcut Shift-F12 -(was Ctrl-X in gmkin < 0.6.6) can be used to save the current status of the -project.

    - -

    In the project file management area, datasets and models can be imported from -one of the projects in the project list, once it has been selected in the -droplist labelled 'Import from:'.

    - -

    Screenshot of importing datasets and models

    - -

    Once the project has been set up, you may want to minimize the project explorer, especially -if you are limited in vertical screen space.

    - -

    Screenshot of minimized project explorer

    - +

    At startup, the project explorer to the left shows the two project workspaces ‘FOCUS_2006’ and ‘FOCUS_2006_Z’ delivered with the package. The project manangement area in the center gives the possibility to save these projects under a new name, or to start a new, empty project.

    +

    A gmkin project workspace contains datasets, kinetic models for fitting, and so-called fits, i.e. the results of fitting models to data. The project area also shows the current working directory, where project workspace files are saved using the file extension .gmkinws.

    +

    Once a project has been saved by the user, the project explorer to the left will show it in the project list.

    +
    +Screenshot of saving a new project +

    Screenshot of saving a new project

    +
    +

    The current state of a project should repeatedly be saved during the work in order to avoid loosing data. This can be achieved by selecting the ‘Project’ tab in the center and pressing the ‘Save project to project file’ button. More conveniently, the keyboard shortcut Shift-F12 (was Ctrl-X in gmkin < 0.6.6) can be used to save the current status of the project.

    +

    In the project file management area, datasets and models can be imported from one of the projects in the project list, once it has been selected in the droplist labelled ‘Import from:’.

    +
    +Screenshot of importing datasets and models +

    Screenshot of importing datasets and models

    +
    +

    Once the project has been set up, you may want to minimize the project explorer, especially if you are limited in vertical screen space.

    +
    +Screenshot of minimized project explorer +

    Screenshot of minimized project explorer

    +
    +
    +

    Dataset editor

    - -

    When you select one of the datasets in the dataset explorer to the left, some -summary information about the dataset is shown in the center, and the data itself -is loaded into the data editor to the right.

    - -

    Screenshot of the GUI after loading a dataset

    - -

    When you have added information about the units, or edited the data to the right, you should hit -the button 'Keep changes'. This will add a new entry in the dataset explorer.

    - -

    In the dataset editor to the right, you can override original data (for example in order to -follow FOCUS recommendations for time zero samples or values below the limit of detection) -by entering numbers in the override column.

    - -

    When saving a dataset, the sampling times, the number of replicates and the list of observed -variables will be computed from the current data in the data editor.

    - -

    However, entering data in these fields is a prerequisite for entering a new dataset directly -in the dataset editor.

    - +

    When you select one of the datasets in the dataset explorer to the left, some summary information about the dataset is shown in the center, and the data itself is loaded into the data editor to the right.

    +
    +Screenshot of the GUI after loading a dataset +

    Screenshot of the GUI after loading a dataset

    +
    +

    When you have added information about the units, or edited the data to the right, you should hit the button ‘Keep changes’. This will add a new entry in the dataset explorer.

    +

    In the dataset editor to the right, you can override original data (for example in order to follow FOCUS recommendations for time zero samples or values below the limit of detection) by entering numbers in the override column.

    +

    When saving a dataset, the sampling times, the number of replicates and the list of observed variables will be computed from the current data in the data editor.

    +

    However, entering data in these fields is a prerequisite for entering a new dataset directly in the dataset editor.

    +

    Entering data directly

    - -

    For entering new data manually, there are two possibilities. You can either -change the Dataset title of the current dataset and edit the data in the Data -editor to the right. Or, if the new data should have a different structure, e.g. -different sampling times, observed variables and replicates, click on “New -dataset”, edit the dataset title, sampling times, number of replicates and the list of -observed variables, and press the button 'Generate grid for entering kinetic data', in -order to prepare the Data editor to the right.

    - -

    For sampling times and short names of the relevant compounds, a comma separated -list must be entered, with a space after each comma. An example of filling out -the respective fields is shown below.

    - -

    Screenshot of generating a data grid

    - -

    After that, the actual measurements can be entered into the Data editor to the right, in the -column 'value'.

    - -

    If everything is OK, press “Keep changes” to save the dataset in the current -workspace. Note that you need to save the project file (see above) in order to -be able to use the dataset that you created in a future gmkin session.

    - +

    For entering new data manually, there are two possibilities. You can either change the Dataset title of the current dataset and edit the data in the Data editor to the right. Or, if the new data should have a different structure, e.g. different sampling times, observed variables and replicates, click on “New dataset”, edit the dataset title, sampling times, number of replicates and the list of observed variables, and press the button ‘Generate grid for entering kinetic data’, in order to prepare the Data editor to the right.

    +

    For sampling times and short names of the relevant compounds, a comma separated list must be entered, with a space after each comma. An example of filling out the respective fields is shown below.

    +
    +Screenshot of generating a data grid +

    Screenshot of generating a data grid

    +
    +

    After that, the actual measurements can be entered into the Data editor to the right, in the column ‘value’.

    +

    If everything is OK, press “Keep changes” to save the dataset in the current workspace. Note that you need to save the project file (see above) in order to be able to use the dataset that you created in a future gmkin session.

    +
    +

    Importing data from text files

    - -

    In case you want to work with a larger dataset that is already available as a computer -file e.g. in a spreadsheet application, you can export these data as a tab separated -or comma separated text file and import it using the “Browse” and “Upload” buttons in the -dataset editor.

    - -

    As an example, we can create a text file from one of the datasets shipped with -the mkin package using the following R command:

    - -
    write.table(schaefer07_complex_case, sep = ",", dec = ".",
+
    In case you want to work with a larger dataset that is already available as a computer file e.g. in a spreadsheet application, you can export these data as a tab separated or comma separated text file and import it using the “Browse” and “Upload” buttons in the dataset editor.
    
+
    As an example, we can create a text file from one of the datasets shipped with the mkin package using the following R command:
    
+
    write.table(schaefer07_complex_case, sep = ",", dec = ".",
             row.names = FALSE, quote = FALSE,
-            file = "schaefer07.csv")
-
    
-
+            file = "schaefer07.csv")

    This produces a text file with comma separated values in the current working directory of R.

    - -

    Loading this text file into gmkin using the “Browse” and “Upload” buttons

    - -

    Screenshot of the browse and upload dialogue

    - -

    results in an an import configuration area showing the top lines of the imported file, and -giving the possibility to chose the import options matching the file format.

    - -

    Screenshot of the import configuration area

    - -

    In the import configuration area, the following options can be specified. In the field -“Comment lines”, the number of lines in the beginning of the file that should be ignored -can be specified.

    - -

    The checkbox on the next line should be checked if the first line of the file contains -the column names, i.e. the names of the observed variables when the data are in wide format.

    - -

    As “Separator”, whitespace, semicolon or comma can be chosen. If whitespace is selected, -files in which the values are separated by a fixed or varying number of whitespace characters -should be read in correctly. As the tabulator counts as a whitespace character, this is -also the option to choose for tabulator separated values.

    - -

    As the “Decimal” separator, comma “,” or period “.” can be selected.

    - -

    In the next line, it can be specified if the data are in wide or in long format. -If in wide format, the only option left to specify is the title of the column containing -the sampling times. If the data is in long format, the column headings specifying the -columns containing the observed variables (default is “name”), the sampling times -(default is “time”), the observed values (default is “value”) and, if present in the data, -the relative errors (default is “err”) can be adapted. The default settings appearing if -the long format is selected are shown below.

    - -

    Screenshot of the default variable names for data in long format

    - -

    In our example we have data in the wide format, and after adapting the -“Separator” to a comma, we can press the button “Import using options specified -below”, and the data should be imported. If successful, the dataset editor should -show the sampling times and the names of the observed variables, and the Data editor -should show the imported data in a grid for further editing or specifying -overrides.

    - -

    Screenshot of a successful upload

    - -

    After adapting the dataset title and possibly the units, press -“Keep changes” to save the dataset in the current workspace. Again, you need to -save the project file in order to be able to use the dataset that you created -in a future gmkin session.

    - +

    Loading this text file into gmkin using the “Browse” and “Upload” buttons

    +
    +Screenshot of the browse and upload dialogue +

    Screenshot of the browse and upload dialogue

    +
    +

    results in an an import configuration area showing the top lines of the imported file, and giving the possibility to chose the import options matching the file format.

    +
    +Screenshot of the import configuration area +

    Screenshot of the import configuration area

    +
    +

    In the import configuration area, the following options can be specified. In the field “Comment lines”, the number of lines in the beginning of the file that should be ignored can be specified.

    +

    The checkbox on the next line should be checked if the first line of the file contains the column names, i.e. the names of the observed variables when the data are in wide format.

    +

    As “Separator”, whitespace, semicolon or comma can be chosen. If whitespace is selected, files in which the values are separated by a fixed or varying number of whitespace characters should be read in correctly. As the tabulator counts as a whitespace character, this is also the option to choose for tabulator separated values.

    +

    As the “Decimal” separator, comma “,” or period “.” can be selected.

    +

    In the next line, it can be specified if the data are in wide or in long format. If in wide format, the only option left to specify is the title of the column containing the sampling times. If the data is in long format, the column headings specifying the columns containing the observed variables (default is “name”), the sampling times (default is “time”), the observed values (default is “value”) and, if present in the data, the relative errors (default is “err”) can be adapted. The default settings appearing if the long format is selected are shown below.

    +
    +Screenshot of the default variable names for data in long format +

    Screenshot of the default variable names for data in long format

    +
    +

    In our example we have data in the wide format, and after adapting the “Separator” to a comma, we can press the button “Import using options specified below”, and the data should be imported. If successful, the dataset editor should show the sampling times and the names of the observed variables, and the Data editor should show the imported data in a grid for further editing or specifying overrides.

    +
    +Screenshot of a successful upload +

    Screenshot of a successful upload

    +
    +

    After adapting the dataset title and possibly the units, press “Keep changes” to save the dataset in the current workspace. Again, you need to save the project file in order to be able to use the dataset that you created in a future gmkin session.

    +
    +
    +

    Model editor

    - -

    The following screenshot shows the model editor for the model 'Z.2a.ff' from -the project workspace 'FOCUS_2006_Z' provided with the gmkin package.

    - -

    Screenshot of the model editor

    - -

    In the first line the name of the model can be edited. You can also specify “min” or -“max” for minimum or maximum use of formation fractions. Maximum use of formation -fractions means that the differential equations in the degradation model are formulated -using formation fractions. When you specify “min”, then formation fractions are only used -for the parent compound when you use the FOMC, DFOP or the HS model for it.

    - -

    Pressing “Add observed variable” adds a line in the array of state variable specifications below. -The observed variables to be added are usually transformation products (usually termed metabolites), -but can also be the parent compound in a different compartment (e.g. “parent_sediment”).

    - -

    Only observed variable names that occur in previously defined datasets or -models can be selected. For any observed variable other than the first one, -only the SFO or the SFORB model can be selected. For each observed variables, a -comma separated list of target variables can be specified. In addition, a -pathway to the sink compartment can be selected. If too many observed variables -have been added, complete lines can be removed from the model definition by -pressing the button “Remove observed variable”.

    - -

    If the model definition is supposedly correct, press “Keep changes” to make it possible to select -it for fitting in the listing of models to the left.

    - +

    The following screenshot shows the model editor for the model ‘Z.2a.ff’ from the project workspace ‘FOCUS_2006_Z’ provided with the gmkin package.

    +
    +Screenshot of the model editor +

    Screenshot of the model editor

    +
    +

    In the first line the name of the model can be edited. You can also specify “min” or “max” for minimum or maximum use of formation fractions. Maximum use of formation fractions means that the differential equations in the degradation model are formulated using formation fractions. When you specify “min”, then formation fractions are only used for the parent compound when you use the FOMC, DFOP or the HS model for it.

    +

    Pressing “Add observed variable” adds a line in the array of state variable specifications below. The observed variables to be added are usually transformation products (usually termed metabolites), but can also be the parent compound in a different compartment (e.g. “parent_sediment”).

    +

    Only observed variable names that occur in previously defined datasets or models can be selected. For any observed variable other than the first one, only the SFO or the SFORB model can be selected. For each observed variables, a comma separated list of target variables can be specified. In addition, a pathway to the sink compartment can be selected. If too many observed variables have been added, complete lines can be removed from the model definition by pressing the button “Remove observed variable”.

    +

    If the model definition is supposedly correct, press “Keep changes” to make it possible to select it for fitting in the listing of models to the left.

    +
    +

    Configuring the fit

    - -

    If a dataset and a kinetic model are selected, the button “Configure fit” below -in the Explorer window “Configuration” becomes active. Pressing it opens the “Configuration” -area in the center and loads the dataset into the Data editor to the right, for viewing only.

    - -

    After pressing the button 'Plot unoptimised', the data and the kinetic model with default -starting parameters are plotted in the 'Plot' area to the right.

    - -

    Screenshot of the fit configuration area

    - +

    If a dataset and a kinetic model are selected, the button “Configure fit” below in the Explorer window “Configuration” becomes active. Pressing it opens the “Configuration” area in the center and loads the dataset into the Data editor to the right, for viewing only.

    +

    After pressing the button ‘Plot unoptimised’, the data and the kinetic model with default starting parameters are plotted in the ‘Plot’ area to the right.

    +
    +Screenshot of the fit configuration area +

    Screenshot of the fit configuration area

    +
    +

    Fit options

    - -

    The most important fit options of the mkinfit function can be set via the -controls in the fit configuration area shown above. If the “plot” checkbox is -checked (and on Windows, the R GUI is used for running gmkin), an R graphics -device started via the R console shows the fitting progress, i.e. the change of -the model solution together with the data during the optimisation.

    - -

    The “solution_type” can either be “auto”, which means that the most effective solution -method is chosen for the model, in the order of “analytical” (for parent only degradation -data), “eigen” (for differential equation models with only linear terms, i.e. without -FOMC, DFOP or HS submodels) or “deSolve”, which can handle all model definitions generated -by the mkin package. If a compiler (gcc, on Windows install the 'Rtools' software package), -then the “deSolve” solution method is alway chosen when there are more than one -variables in the model.

    - -

    The parameters “atol” and “rtol” are only effective if the solution type is “deSolve”. They -control the precision of the iterative numerical solution of the differential equation model.

    - -

    The checkboxes “transform_rates” and “transform_fractions” control if the parameters are fitted -as defined in the model, or if they are internally transformed during the fitting process in -order to improve the estimation of standard errors and confidence intervals which are based -on a linear approximation at the optimum found by the fitting algorithm.

    - -

    If fitting with transformed fractions leads to a suboptimal fit, doing a first -run without transforming fractions may help. A final run using the optimised -parameters from the previous run as starting values (see comment on “Get -initials from” above) can then be performed with transformed fractions.

    - -

    The dropdown box “weight” specifies if and how the observed values should be weighted -in the fitting process. If “manual” is chosen, the values in the “err” column of the -dataset are used, which are set to unity by default. Setting these to higher values -gives lower weight and vice versa. If “none” is chosen, observed -values are not weighted. Please refer to the documentation of the modFit function from -the FME package for the meaning of options “std” and “mean”.

    - -

    If the “IRLS” option is set to “obs”, then we make use of iteratively -reweighted least squares fitting. Please refer to the mkinfit -documentation -for more details. IRLS fitting can be configured using the options -“reweight.tol” and “reweight.max.iter”.

    - -

    The drop down box “method.modFit” makes it possible to choose between the optimisation -algorithms “Port” (the default in mkin versions > 0.9-33, a local optimisation -algorithm using a model/trust region approach), “Marq” (the former default in -mkin, a Levenberg-Marquardt variant from the R package minpack.lm), -and “SANN” (the simulated annealing method - robust but inefficient and without -a convergence criterion).

    - -

    Finally, the maximum number of iterations for the optimisation can be adapted using the -“maxit.modFit” field.

    - +

    The most important fit options of the mkinfit function can be set via the controls in the fit configuration area shown above. If the “plot” checkbox is checked (and on Windows, the R GUI is used for running gmkin), an R graphics device started via the R console shows the fitting progress, i.e. the change of the model solution together with the data during the optimisation.

    +

    The “solution_type” can either be “auto”, which means that the most effective solution method is chosen for the model, in the order of “analytical” (for parent only degradation data), “eigen” (for differential equation models with only linear terms, i.e. without FOMC, DFOP or HS submodels) or “deSolve”, which can handle all model definitions generated by the mkin package. If a compiler (gcc, on Windows install the ‘Rtools’ software package), then the “deSolve” solution method is alway chosen when there are more than one variables in the model.

    +

    The parameters “atol” and “rtol” are only effective if the solution type is “deSolve”. They control the precision of the iterative numerical solution of the differential equation model.

    +

    The checkboxes “transform_rates” and “transform_fractions” control if the parameters are fitted as defined in the model, or if they are internally transformed during the fitting process in order to improve the estimation of standard errors and confidence intervals which are based on a linear approximation at the optimum found by the fitting algorithm.

    +

    If fitting with transformed fractions leads to a suboptimal fit, doing a first run without transforming fractions may help. A final run using the optimised parameters from the previous run as starting values (see comment on “Get initials from” above) can then be performed with transformed fractions.

    +

    If the “error_model” option is set to “obs” or “tc”, then a suitable “error_model_algorithm” has to be selected. The recommended algorithm for these error model is “d_3”, which is the one selected by “mkin” for there error models. Please refer to the mkinfit documentation for more details. IRLS fitting can be configured using the options “reweight.tol” and “reweight.max.iter”.

    +

    The maximum number of iterations for the optimisation can be adapted using the “maxit” field.

    +
    +

    Plot options

    - -

    In the right part of the fit configuration area, the file format can be chosen, -the legend can be turned off, and the observed variables for which the data and -the model fit should be plotted can be selected as shown below.

    - -

    plot options

    - -

    On systems running the Windows operating system, the windows metafile (wmf) format -can be additionally chosen. Changing the file format for plotting will also change -the extension of the proposed filename for saving the plot.

    - +

    In the right part of the fit configuration area, the file format can be chosen, the legend can be turned off, and the observed variables for which the data and the model fit should be plotted can be selected as shown below.

    +
    +plot options +

    plot options

    +
    +

    On systems running the Windows operating system, the enhanced metafile (emf) format can be additionally chosen. Changing the file format for plotting will also change the extension of the proposed filename for saving the plot.

    +
    +

    Parameters

    - -

    Below the fit control area, a table with the Starting parameter list is displayed. While -name and type of the parameters should not be edited, their initial values can be edited -by clicking on a row. Also, it can be specified if the parameters should be fixed -in the optimisation process.

    - -

    If the initial values for the parameters were changed, the resulting model solution -can be visually checked by pressing the button “Plot unoptimised”. This will update the -plot of the model and the data using the specified initial parameter values.

    - -

    If a similar model with a partially overlapping model definition has already be fitted, -initial values for parameters with the same name in both models can also be retrieved -from previous fits by selecting the fit and pressing the button “Get starting parameters -from”. This facilitates stepwise fitting of more complex degradation pathways.

    - -

    After the model has been successfully fitted by pressing the “Run fit” button, the optimised -parameter values are added to the parameter table.

    - +

    Below the fit control area, a table with the Starting parameter list is displayed. While name and type of the parameters should not be edited, their initial values can be edited by clicking on a row. Also, it can be specified if the parameters should be fixed in the optimisation process.

    +

    If the initial values for the parameters were changed, the resulting model solution can be visually checked by pressing the button “Plot unoptimised”. This will update the plot of the model and the data using the specified initial parameter values.

    +

    If a similar model with a partially overlapping model definition has already be fitted, initial values for parameters with the same name in both models can also be retrieved from previous fits by selecting the fit and pressing the button “Get starting parameters from”. This facilitates stepwise fitting of more complex degradation pathways.

    +

    After the model has been successfully fitted by pressing the “Run fit” button, the optimised parameter values are added to the parameter table.

    +
    +

    Fitting the model

    - -

    In many cases the starting parameters and the fit options do not need to be modified -and the model fitting process can simply be started by pressing the “Run fit” button. -In the R console, the progressive reduction in the model cost can be monitored and will -be displayed in the following way:

    - -
    Model cost at call  1 :  15156.12
-Model cost at call  3 :  15156.12
-Model cost at call  7 :  14220.79
-Model cost at call  8 :  14220.79
-Model cost at call  11 :  14220.79
-Model cost at call  12 :  3349.268
-Model cost at call  15 :  3349.268
-Model cost at call  17 :  788.6367
-Model cost at call  18 :  788.6366
-Model cost at call  22 :  374.0575
-Model cost at call  23 :  374.0575
-Model cost at call  27 :  371.2135
-Model cost at call  28 :  371.2135
-Model cost at call  32 :  371.2134
-Model cost at call  36 :  371.2134
-Model cost at call  37 :  371.2134
-Optimisation by method Port successfully terminated.
-
    - -

    If plotting of the fitting progress was selected, a new separate graphics -window should either pop up, or a graphics window previously started for this -purpose will be reused.

    - -

    If your screen size allows for it, you can arrange the R plotting window and the -R console in a way that you can see everything at the same time:

    - -

    Screenshot of arrangement of plot window and console

    - +

    In many cases the starting parameters and the fit options do not need to be modified and the model fitting process can simply be started by pressing the “Run fit” button. In the R console, the progressive reduction in the model cost can be monitored and will be displayed in the following way:

    +
    > Ordinary least squares optimisation
+Sum of squared residuals at call 1: 2388.077
+Sum of squared residuals at call 3: 2388.077
+Sum of squared residuals at call 4: 247.1962
+Sum of squared residuals at call 7: 200.6791
+Sum of squared residuals at call 10: 197.7231
+Sum of squared residuals at call 11: 197.0872
+Sum of squared residuals at call 14: 196.535
+Sum of squared residuals at call 15: 196.535
+Sum of squared residuals at call 16: 196.535
+Sum of squared residuals at call 17: 196.5334
+Sum of squared residuals at call 20: 196.5334
+Sum of squared residuals at call 25: 196.5334
+Negative log-likelihood at call 31: 26.64668
+Optimisation successfully terminated.
    +

    If plotting of the fitting progress was selected, a new separate graphics window should either pop up, or a graphics window previously started for this purpose will be reused.

    +

    If your screen size allows for it, you can arrange the R plotting window and the R console in a way that you can see everything at the same time:

    +
    +Screenshot of arrangement of plot window and console +

    Screenshot of arrangement of plot window and console

    +
    +
    +
    +

    Results and summary

    - -

    Once a fit has successfully been completed, the most important results are shown in several -tables in the “Result” area as shown below.

    - -

    Screenshot of the results

    - +

    Once a fit has successfully been completed, the most important results are shown in several tables in the “Result” area as shown below.

    +
    +Screenshot of the results +

    Screenshot of the results

    +

    The detailed summary can be accessed below these tables.

    - -

    Screenshot of the summary

    - -

    The complete summary can be saved into a text file by specifying a suitable file name -and pressing the button “Save summary”.

    - +
    +Screenshot of the summary +

    Screenshot of the summary

    +
    +

    The complete summary can be saved into a text file by specifying a suitable file name and pressing the button “Save summary”.

    +

    Confidence interval plots

    - -

    Whenever a new fit has been configured or a run of a fit has been completed, the plotting -area is updated with the abovementioned plot of the data and the current model solution.

    - -

    In addition, a confidence interval plot is shown below this conventional plot. In case -a fit has been run and confidence intervals were successfully calculated for the fit (i.e. -if the model was not overparameterised and no other problems occurred), the -confidence intervals are graphically displayed as bars as shown below.

    - -

    confidence

    - +

    Whenever a new fit has been configured or a run of a fit has been completed, the plotting area is updated with the abovementioned plot of the data and the current model solution.

    +

    In addition, a confidence interval plot is shown below this conventional plot. In case a fit has been run and confidence intervals were successfully calculated for the fit ( i.e. if the model was not overparameterised and no other problems occurred), the confidence intervals are graphically displayed as bars as shown below.

    +
    +confidence +

    confidence

    +
    +
    +
    +

    Howtos

    - -

    The following sections show step by step descriptions of how to perform certain -tasks using gmkin. In principle, this should not be necessary as the GUI was -designed to be largely self-explanatory. Nevertheless it may help a beginner to -understand how to use gmkin. At the same time, the gmkin author uses them as -test cases to make sure that the most important functionality is not broken -before releasing a new version.

    - +

    The following sections show step by step descriptions of how to perform certain tasks using gmkin. In principle, this should not be necessary as the GUI was designed to be largely self-explanatory. Nevertheless it may help a beginner to understand how to use gmkin. At the same time, the gmkin author uses them as test cases to make sure that the most important functionality is not broken before releasing a new version.

    +

    1. Use a model and a dataset from a built-in workspace

    -
    • Start gmkin
      • -
    • In the project explorer, select the project 'FOCUS_2006'
      • -
    • In the dataset explorer, select 'FOCUS example dataset C'
      • -
    • In the model explorer, select 'SFO'
      • -
    • In the configuration display, press 'Configure fit'
      • -
    • In the configuration editor in the center, press 'Run fit'
      • -
    • In the pop-up window that appears, press 'Yes'
      • -
    • In the result viewer in the center, press 'Keep fit'
      • +
    • In the project explorer, select the project ‘FOCUS_2006’
      • +
    • In the dataset explorer, select ‘FOCUS example dataset C’
      • +
    • In the model explorer, select ‘SFO’
      • +
    • In the configuration display, press ‘Configure fit’
      • +
    • In the configuration editor in the center, press ‘Run fit’
      • +
    • In the pop-up window that appears, press ‘Yes’
      • +
    • In the result viewer in the center, press ‘Keep fit’
    • Switch to the Project editor in the center
      • -
    • In the project explorer, enter the project name 'Howto test 1'
      • -
    • Press 'Save project to project file'
      • +
    • In the project explorer, enter the project name ‘Howto test 1’
      • +
    • Press ‘Save project to project file’
    - +
    + +

    3. Load a tab separated input file in wide format and evaluate using a newly created model

    -
    • Start gmkin
      • -
    • In the project explorer, enter the project name 'Howto test 3'
      • -
    • Press 'Save project to project file'
      • +
    • In the project explorer, enter the project name ‘Howto test 3’
      • +
    • Press ‘Save project to project file’
    • Select the dataset editor in the center
      • -
    • In the data upload widget, press 'Browse'
      • -
    • Select the file 'testdata/d_synth_DFOP_lin_c.txt' from gmkin installation
      • -
    • Press 'Upload'
      • -
    • Press 'Import using options specified below'
      • -
    • Enter dataset title 'DFOP lin c'
      • -
    • Press 'Keep changes'
      • +
    • In the data upload widget, press ‘Browse’
      • +
    • Select the file ‘testdata/d_synth_DFOP_lin_c.txt’ from gmkin installation
      • +
    • Press ‘Upload’
      • +
    • Press ‘Import using options specified below’
      • +
    • Enter dataset title ‘DFOP lin c’
      • +
    • Press ‘Keep changes’
    • Select the model editor in the center
      • -
    • Press 'New model'
      • -
    • Enter 'DFOP lin' as the model name
      • -
    • Select 'max' in the dropbox 'Use of formation fractions'
      • -
    • Press 'Add observed variable' three times
      • -
    • In the line where 'parent' is selected, in the dropbox after the word 'to', select 'M1'
      • +
    • Press ‘New model’
      • +
    • Enter ‘DFOP lin’ as the model name
      • +
    • Select ‘max’ in the dropbox ‘Use of formation fractions’
      • +
    • Press ‘Add observed variable’ three times
      • +
    • In the line where ‘parent’ is selected, in the dropbox to the right change ‘SFO’ to ‘DFOP’
      • +
    • In the line where ‘parent’ is selected, after the word ‘to’, select ‘M1’
    • Click outside the dropbox
      • -
    • In the line where 'M1' is selected, in the dropbox after the word 'to', select 'M2'
      • +
    • In the line where ‘M1’ is selected, in the dropbox after the word ‘to’, select ‘M2’
    • Click outside the dropbox
      • -
    • Press 'Keep changes'
      • -
    • In the dataset explorer, select 'DFOP lin c'
      • -
    • In the model explorer, select 'DFOP lin'
      • -
    • In the configuration display, press 'Configure fit'
      • -
    • In the configuration editor in the center, press 'Run fit'
      • -
    • In the pop-up window that appears, press 'Yes'
      • -
    • In the result viewer in the center, press 'Keep fit'
      • +
    • Press ‘Keep changes’
      • +
    • In the dataset explorer, select ‘DFOP lin c’
      • +
    • In the model explorer, select ‘DFOP lin’
      • +
    • In the configuration display, press ‘Configure fit’
      • +
    • In the configuration editor in the center, press ‘Run fit’
      • +
    • In the pop-up window that appears, press ‘Yes’
      • +
    • In the result viewer in the center, press ‘Keep fit’
    • Switch to the Project editor in the center
      • -
    • Press 'Save project to project file'
      • +
    • Press ‘Save project to project file’
    - +
    +
    - + + +
    + + + + + diff --git a/vignettes/img/configuration.png b/vignettes/img/configuration.png index 1a18608..12dc195 100644 Binary files a/vignettes/img/configuration.png and b/vignettes/img/configuration.png differ diff --git a/vignettes/img/gmkin_start.png b/vignettes/img/gmkin_start.png index 9b494ec..92d2325 100644 Binary files a/vignettes/img/gmkin_start.png and b/vignettes/img/gmkin_start.png differ diff --git a/vignettes/img/plotoptions.png b/vignettes/img/plotoptions.png index 24cda2d..a3f1b06 100644 Binary files a/vignettes/img/plotoptions.png and b/vignettes/img/plotoptions.png differ -- cgit v1.2.1