diff options
Diffstat (limited to 'docs/articles/gmkin_manual.html')
| -rw-r--r-- | docs/articles/gmkin_manual.html | 42 |
1 files changed, 21 insertions, 21 deletions
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 @@ <!-- jquery --><script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-BVYiiSIFeK1dGmJRAkycuHAHRg32OmUcww7on3RYdg4Va+PmSTsz/K68vbdEjh4u" crossorigin="anonymous"> <script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script><!-- Font Awesome icons --><link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous"> <!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet"> -<script src="../jquery.sticky-kit.min.js"></script><script src="../pkgdown.js"></script><!-- mathjax --><script src="https://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><!--[if lt IE 9]> +<script src="../jquery.sticky-kit.min.js"></script><script src="../pkgdown.js"></script><!-- mathjax --><script src="https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><!--[if lt IE 9]> <script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script> <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script> <![endif]--> @@ -53,7 +53,7 @@ <h1>Manual for gmkin</h1> <h4 class="author">Johannes Ranke</h4> - <h4 class="date">2017-03-06</h4> + <h4 class="date">2017-10-13</h4> </div> @@ -61,13 +61,13 @@ <div class="contents"> <div id="introduction" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#introduction" class="anchor"> </a></body></html>Introduction</h2> +<a href="#introduction" class="anchor"></a>Introduction</h2> <p>The R add-on package gmkin provides a browser based graphical interface for performing kinetic evaluations of degradation data using the <a href="http://kinfit.r-forge.r-project.org/mkin_static">mkin package</a>. While the use of gmkin should be largely self-explanatory, this manual may serve as a functionality overview and reference.</p> <p>For system requirements and installation instructions, please refer to the <a href="http://kinfit.r-forge.r-project.org/gmkin_static">gmkin homepage</a>.</p> </div> <div id="starting-gmkin" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#starting-gmkin" class="anchor"> </a></body></html>Starting gmkin</h2> +<a href="#starting-gmkin" class="anchor"></a>Starting gmkin</h2> <p>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</p> <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">library</span>(gmkin)</code></pre></div> <p>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.</p> @@ -85,13 +85,13 @@ </div> <div id="three-column-layout" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#three-column-layout" class="anchor"> </a></body></html>Three column layout</h2> +<a href="#three-column-layout" class="anchor"></a>Three column layout</h2> <p>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.</p> <p>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.</p> </div> <div id="project-file-management" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#project-file-management" class="anchor"> </a></body></html>Project file management</h2> +<a href="#project-file-management" class="anchor"></a>Project file management</h2> <p>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.</p> <p>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 <code>.gmkinws</code>.</p> <p>Once a project has been saved by the user, the project explorer to the left will show it in the project list.</p> @@ -110,7 +110,7 @@ </div> <div id="dataset-editor" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#dataset-editor" class="anchor"> </a></body></html>Dataset editor</h2> +<a href="#dataset-editor" class="anchor"></a>Dataset editor</h2> <p>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.</p> <div class="figure"> <img src="img/dataset_Z.png" alt="Screenshot of the GUI after loading a dataset"><p class="caption">Screenshot of the GUI after loading a dataset</p> @@ -121,7 +121,7 @@ <p>However, entering data in these fields is a prerequisite for entering a new dataset directly in the dataset editor.</p> <div id="entering-data-directly" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#entering-data-directly" class="anchor"> </a></body></html>Entering data directly</h3> +<a href="#entering-data-directly" class="anchor"></a>Entering data directly</h3> <p>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.</p> <p>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.</p> <div class="figure"> @@ -132,7 +132,7 @@ </div> <div id="importing-data-from-text-files" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#importing-data-from-text-files" class="anchor"> </a></body></html>Importing data from text files</h3> +<a href="#importing-data-from-text-files" class="anchor"></a>Importing data from text files</h3> <p>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.</p> <p>As an example, we can create a text file from one of the datasets shipped with the mkin package using the following R command:</p> <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">write.table</span>(schaefer07_complex_case, <span class="dt">sep =</span> <span class="st">","</span>, <span class="dt">dec =</span> <span class="st">"."</span>, @@ -164,7 +164,7 @@ </div> <div id="model-editor" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#model-editor" class="anchor"> </a></body></html>Model editor</h2> +<a href="#model-editor" class="anchor"></a>Model editor</h2> <p>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.</p> <div class="figure"> <img src="img/modeleditor.png" alt="Screenshot of the model editor"><p class="caption">Screenshot of the model editor</p> @@ -176,7 +176,7 @@ </div> <div id="configuring-the-fit" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#configuring-the-fit" class="anchor"> </a></body></html>Configuring the fit</h2> +<a href="#configuring-the-fit" class="anchor"></a>Configuring the fit</h2> <p>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.</p> <p>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.</p> <div class="figure"> @@ -184,7 +184,7 @@ </div> <div id="fit-options" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#fit-options" class="anchor"> </a></body></html>Fit options</h3> +<a href="#fit-options" class="anchor"></a>Fit options</h3> <p>The most important fit options of the <code>mkinfit</code> 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.</p> <p>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 <code>mkin</code> 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.</p> <p>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.</p> @@ -197,7 +197,7 @@ </div> <div id="plot-options" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#plot-options" class="anchor"> </a></body></html>Plot options</h3> +<a href="#plot-options" class="anchor"></a>Plot options</h3> <p>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.</p> <div class="figure"> <img src="img/plotoptions.png" alt="plot options"><p class="caption">plot options</p> @@ -206,7 +206,7 @@ </div> <div id="parameters" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#parameters" class="anchor"> </a></body></html>Parameters</h3> +<a href="#parameters" class="anchor"></a>Parameters</h3> <p>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.</p> <p>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.</p> <p>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.</p> @@ -214,7 +214,7 @@ </div> <div id="fitting-the-model" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#fitting-the-model" class="anchor"> </a></body></html>Fitting the model</h3> +<a href="#fitting-the-model" class="anchor"></a>Fitting the model</h3> <p>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:</p> <div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">Model cost at call <span class="dv">1</span> :<span class="st"> </span><span class="fl">15156.12</span> Model cost at call <span class="dv">3</span> :<span class="st"> </span><span class="fl">15156.12</span> @@ -242,7 +242,7 @@ Optimisation by method Port successfully terminated.</code></pre></div> </div> <div id="results-and-summary" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#results-and-summary" class="anchor"> </a></body></html>Results and summary</h2> +<a href="#results-and-summary" class="anchor"></a>Results and summary</h2> <p>Once a fit has successfully been completed, the most important results are shown in several tables in the “Result” area as shown below.</p> <div class="figure"> <img src="img/results.png" alt="Screenshot of the results"><p class="caption">Screenshot of the results</p> @@ -254,7 +254,7 @@ Optimisation by method Port successfully terminated.</code></pre></div> <p>The complete summary can be saved into a text file by specifying a suitable file name and pressing the button “Save summary”.</p> <div id="confidence-interval-plots" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#confidence-interval-plots" class="anchor"> </a></body></html>Confidence interval plots</h3> +<a href="#confidence-interval-plots" class="anchor"></a>Confidence interval plots</h3> <p>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.</p> <p>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.</p> <div class="figure"> @@ -264,11 +264,11 @@ Optimisation by method Port successfully terminated.</code></pre></div> </div> <div id="howtos" class="section level2"> <h2 class="hasAnchor"> -<html><body><a href="#howtos" class="anchor"> </a></body></html>Howtos</h2> +<a href="#howtos" class="anchor"></a>Howtos</h2> <p>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.</p> <div id="use-a-model-and-a-dataset-from-a-built-in-workspace" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#use-a-model-and-a-dataset-from-a-built-in-workspace" class="anchor"> </a></body></html>1. Use a model and a dataset from a built-in workspace</h3> +<a href="#use-a-model-and-a-dataset-from-a-built-in-workspace" class="anchor"></a>1. Use a model and a dataset from a built-in workspace</h3> <ul> <li>Start gmkin</li> <li>In the project explorer, select the project ‘FOCUS_2006’</li> @@ -285,7 +285,7 @@ Optimisation by method Port successfully terminated.</code></pre></div> </div> <div id="enter-a-simple-dataset-and-evaluate-it-using-a-model-from-the-gallery" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#enter-a-simple-dataset-and-evaluate-it-using-a-model-from-the-gallery" class="anchor"> </a></body></html>2. Enter a simple dataset and evaluate it using a model from the gallery</h3> +<a href="#enter-a-simple-dataset-and-evaluate-it-using-a-model-from-the-gallery" class="anchor"></a>2. Enter a simple dataset and evaluate it using a model from the gallery</h3> <ul> <li>Start gmkin</li> <li>In the project explorer, enter the project name ‘Howto test 2’</li> @@ -312,7 +312,7 @@ Optimisation by method Port successfully terminated.</code></pre></div> </div> <div id="load-a-tab-separated-input-file-in-wide-format-and-evaluate-using-a-newly-created-model" class="section level3"> <h3 class="hasAnchor"> -<html><body><a href="#load-a-tab-separated-input-file-in-wide-format-and-evaluate-using-a-newly-created-model" class="anchor"> </a></body></html>3. Load a tab separated input file in wide format and evaluate using a newly created model</h3> +<a href="#load-a-tab-separated-input-file-in-wide-format-and-evaluate-using-a-newly-created-model" class="anchor"></a>3. Load a tab separated input file in wide format and evaluate using a newly created model</h3> <ul> <li>Start gmkin</li> <li>In the project explorer, enter the project name ‘Howto test 3’</li> |