From 36171ae401dd67f4d6dae997f6db54f0debf687f Mon Sep 17 00:00:00 2001
From: Astrid Muennich <amunnich@max-exfl001.desy.de>
Date: Thu, 9 Aug 2018 10:26:41 +0200
Subject: [PATCH] work on docu
---
docs/source/index.rst | 2 +-
docs/source/installation.rst | 22 ++++---
docs/source/tutorial.rst | 91 ++++++++++++++++++++---------
notebooks/Tutorial/calversion.ipynb | 7 ++-
xfel_calibrate/notebooks.py | 28 +++++----
5 files changed, 103 insertions(+), 47 deletions(-)
diff --git a/docs/source/index.rst b/docs/source/index.rst
index b7ac0c626..a55b1f41d 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -17,7 +17,7 @@ Contents:
workflow
available_notebooks
advanced
-
+ tutorial
Indices and tables
diff --git a/docs/source/installation.rst b/docs/source/installation.rst
index 406b7e1d0..ab78aadc0 100644
--- a/docs/source/installation.rst
+++ b/docs/source/installation.rst
@@ -6,6 +6,8 @@ done into a Karabo_ Python_ environment. However, there are no explicit
Karabo dependencies, so any Python3 environment is capable of running
the tools.
+A more detailed step-by-step intruction can be found in the :ref:`tutorial`.
+
Prerequisites
-------------
@@ -36,15 +38,20 @@ by sourcing the activate file in the Karabo path::
source karabo/activate
-For other python enviroments, this step can be skipped. You can then install
-all prerequisites and this tool chain by running::
+For other python enviroments, this step can be skipped. The package for the offline
+calibration can be obtained from the git repository::
+
+ git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
+
+You can then install all prerequisites and this tool chain by running::
pip install -r requirements.txt .
-After installation, you should adjust the :ref:`configuration` and settings to
-match your environment.
+in th emain directoy pycalibration.
+After installation, you should adjust the :ref:`configuration` and settings in the folder
+xfel-calibrate to match your environment.
-The toolchain is then available via the::
+The tool-chain is then available via the::
xfel-calibrate
@@ -54,7 +61,7 @@ Development Installation
------------------------
For a development installation, which automatically picks up (most) changes,
-first install the dependencies as above, but then install the took-chain
+first install the dependencies as above, but then install the tool-chain
separately in development mode::
pip install -e .
@@ -71,4 +78,5 @@ the the tool-chain, without prerequisites, from the package base directory::
Or, in case you are activily developing::
- pip install -e .
\ No newline at end of file
+ pip install -e .
+
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index ecea4557c..7f8d48691 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -1,33 +1,72 @@
+.. _tutorial:
+
+Tutorial
+========
+
+The Tutorial consist of this documentation and two very simple notebooks:
+
+1. notebooks/Tutorial/startversion.ipynb
+
+ A simple notebook with no knowledge of the requirements of the offline calibration.
+
+2. notebooks/Tutorial/calversion.ipynb
+
+ Outcome of adapting the startversion notebook to be able to be run with the offline
+ calibtaion tool-chain.
+
Installation and Configuration
-=============================
-1. log into max-exfl
-2. install karabo in your home directory or under /gpfs/exfel/data/scratch/username:
- wget http://exflserv05.desy.de/karabo/karaboFramework/tags/2.2.4/karabo-2.2.4-Release-CentOS-7-x86_64.sh
- chmod +x karabo-2.2.4-Release-CentOS-7-x86_64.sh
- ./karabo-2.2.4-Release-CentOS-7-x86_64.sh
- source karabo/activate
-3. get pycalibration
- git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
-4. install requirements:
- cd pycalibration
- pip install -r requirements.txt .
-5. adjust xfel_calibrate/settings.py:
- change karabo_activate_path and ipcluster_path according to where you installed karabo
+------------------------------
+
+In order to use the offline calibration tool a few steps need to be carried out
+to install the necessary packages and setup the environment:
+
+1. Log into max-exfl with you own user name/account.
+
+2. Install karabo in your home directory or under /gpfs/exfel/data/scratch/username
+ by typing the following commands on you shell::
+
+ wget http://exflserv05.desy.de/karabo/karaboFramework/tags/2.2.4/karabo-2.2.4-Release-CentOS-7-x86_64.sh
+
+ chmod +x karabo-2.2.4-Release-CentOS-7-x86_64.sh
+
+ ./karabo-2.2.4-Release-CentOS-7-x86_64.sh
+
+ source karabo/activate
+
+3. Get the package pycalibration which contains the offline calibration tool-chain::
+
+ git clone https://git.xfel.eu/gitlab/detectors/pycalibration.git
+
+4. Install the necessary requirements and the package itself::
+
+ cd pycalibration
+ pip install -r requirements.txt .
+
+5. Adjust xfel_calibrate/settings.py by changing "karabo_activate_path"
+ and "ipcluster_path according" to where you installed karabo.
+
Create your own notebook
-========================
-1. Create a new notebook or re-arrange an existing on following the guidelines explained here: https://in.xfel.eu/readthedocs/docs/european-xfel-offline-calibration/en/latest/workflow.html
+------------------------
+
+1. Create a new notebook or re-arrange an existing following the guidelines of this documentation
-2. register you notebook:
- add an entry to xfel_calibrate/notebooks.py
- Note: use all capital letters for DETECTOR and TYPE
-3. update:
- pip install --upgrade .
+2. Register you notebook by adding an entry to xfel_calibrate/notebooks.py following
+ the structure given by the existing notebooks.
+
+ Note: Use all capital letters for DETECTOR and TYPE.
+
+3. Load/register the new notebook by updating the installation::
+
+ pip install -e .
Running the notebook
-====================
-1. make sure output folders exist
-2. run it:
- xfel-calibrate Tutorial TEST
-3. Look at generated report in output folder
+--------------------
+
+1. Make sure output folders you want to use exist
+2. To run your notebook::
+
+ xfel-calibrate Tutorial TEST
+
+3. Look at generated report in the chosen output folder.
diff --git a/notebooks/Tutorial/calversion.ipynb b/notebooks/Tutorial/calversion.ipynb
index e59e77854..93dbf18e0 100644
--- a/notebooks/Tutorial/calversion.ipynb
+++ b/notebooks/Tutorial/calversion.ipynb
@@ -32,7 +32,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
- "First include what we need and set up the cluster profile. Everything that has a written response ina cell will show up in the report, e.g. prints but also return values or errors."
+ "First include what we need and set up the cluster profile. Everything that has a written response in a cell will show up in the report, e.g. prints but also return values or errors."
]
},
{
@@ -61,6 +61,7 @@
"import numpy as np\n",
"import matplotlib.pyplot as plt\n",
"\n",
+ "# make sure a cluster is running with ipcluster start --n=2, give it a while to start\n",
"from ipyparallel import Client\n",
"\n",
"print(\"Connecting to profile {}\".format(cluster_profile))\n",
@@ -223,9 +224,9 @@
],
"source": [
"plt.hist(std, 50)\n",
- "plt.xlabel('mean')\n",
+ "plt.xlabel('std')\n",
"plt.ylabel('counts')\n",
- "plt.title('Mean value')\n",
+ "plt.title('Std value')\n",
"plt.show()"
]
}
diff --git a/xfel_calibrate/notebooks.py b/xfel_calibrate/notebooks.py
index 972d6df66..ef4c8c297 100644
--- a/xfel_calibrate/notebooks.py
+++ b/xfel_calibrate/notebooks.py
@@ -59,14 +59,14 @@ notebooks = {
"default concurrency": None,
"cluster cores": 32},
},
- "XGM_MINE": {
- "notebook": "notebooks/LPD/Mine_RadIntensity_vs_XGM_NBC.ipynb",
- "concurrency": {"parameter": "runs",
- "use function": "create_run_list",
- "default concurrency": [-1],
- "cluster cores": 2},
- },
- },
+ # "XGM_MINE": {
+ # "notebook": "notebooks/LPD/Mine_RadIntensity_vs_XGM_NBC.ipynb",
+ # "concurrency": {"parameter": "runs",
+ # "use function": "create_run_list",
+ # "default concurrency": [-1],
+ # "cluster cores": 2},
+ # },
+ },
"PNCCD": {
"CHARACTERIZE": {
"notebook": "notebooks/pnCCD/Characterize_NBC.ipynb",
@@ -74,6 +74,14 @@ notebooks = {
"default concurrency": None,
"cluster cores": 32},
},
- }
+ },
+ "TUTORIAL": {
+ "TEST": {
+ "notebook": "notebooks/Tutorial/calversion.ipynb",
+ "concurrency": {"parameter": None,
+ "default concurrency": None,
+ "cluster cores": 1},
+ },
+ }
- }
\ No newline at end of file
+ }
--
GitLab