From 28425283bdeb34fac01d1eeb9c8dd40f987934ea Mon Sep 17 00:00:00 2001 From: Johannes Ranke Date: Fri, 13 Oct 2017 09:34:15 +0200 Subject: Static documentation rebuilt by pkgdown --- docs/articles/gmkin_manual.html | 42 ++++++++++++++++++++--------------------- docs/articles/index.html | 6 ++++-- 2 files changed, 25 insertions(+), 23 deletions(-) (limited to 'docs/articles') diff --git a/docs/articles/gmkin_manual.html b/docs/articles/gmkin_manual.html index 44192df..8d07631 100644 --- a/docs/articles/gmkin_manual.html +++ b/docs/articles/gmkin_manual.html @@ -9,7 +9,7 @@ - @@ -53,7 +53,7 @@

Manual for gmkin

Johannes Ranke

-

2017-03-06

+

2017-10-13

@@ -61,13 +61,13 @@

- Introduction

+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

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

@@ -85,13 +85,13 @@

- Three column layout

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

- Project file management

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

@@ -110,7 +110,7 @@

- Dataset editor

+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

@@ -121,7 +121,7 @@

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

- Entering data directly

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

@@ -132,7 +132,7 @@

- Importing data from text files

+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 = ".", 
@@ -164,7 +164,7 @@

- Model editor

+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

Screenshot of the model editor

@@ -176,7 +176,7 @@

- Configuring the fit

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

@@ -184,7 +184,7 @@

- Fit options

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

@@ -197,7 +197,7 @@

- Plot options

+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

plot options

@@ -206,7 +206,7 @@

- Parameters

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

@@ -214,7 +214,7 @@

- Fitting the model

+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 
@@ -242,7 +242,7 @@ Optimisation by method Port successfully terminated.

- Results and summary

+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

Screenshot of the results

@@ -254,7 +254,7 @@ Optimisation by method Port successfully terminated.

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

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

@@ -264,11 +264,11 @@ Optimisation by method Port successfully terminated.

- Howtos

+Howtos

The following sections show step by step descriptions of how to perform certain tasks using gmkin. In principle, this should be necessary as the GUI was designed to be largely self-explanatory. Nevertheless 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

+1. Use a model and a dataset from a built-in workspace
  • Start gmkin
  • In the project explorer, select the project ‘FOCUS_2006’
    • @@ -285,7 +285,7 @@ Optimisation by method Port successfully terminated.

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

+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’
    • diff --git a/docs/articles/index.html b/docs/articles/index.html index 442e3b0..20f744f 100644 --- a/docs/articles/index.html +++ b/docs/articles/index.html @@ -25,12 +25,14 @@ - + + + @@ -70,7 +72,7 @@
    -

    Vignette reference version 0.6.8

    +

    Articles version 0.6.8

    -- cgit v1.2.1