From da09dec4071ebc38a3d98ac71e4e62130808c71c Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?G=C3=BCnter=20Quast?= <Guenter.Quast@online.de>
Date: Wed, 29 Jun 2022 12:07:39 +0200
Subject: [PATCH] updated doc on multiple inputs to run_phyFit and model-only
 plots in plotData

---
 tools/plotData.py   |   4 ++
 tools/run_phyFit.py | 107 +++++++++++++++++++++++++++++++++++++++-----
 2 files changed, 99 insertions(+), 12 deletions(-)

diff --git a/tools/plotData.py b/tools/plotData.py
index 88111c1..65541f4 100755
--- a/tools/plotData.py
+++ b/tools/plotData.py
@@ -64,6 +64,10 @@
     model_function: |
     <Python code of model function>
 
+  If no `y_data` or `raw_data` keys are provided, only the model function 
+  is shown. Note that minimalistic `x_data` and `bin_range` or `bin_edges`
+  information must be given to define the x-range of the graph. 
+
 """
 
 from PhyPraKit import plot_xy_from_yaml,plot_hist_from_yaml
diff --git a/tools/run_phyFit.py b/tools/run_phyFit.py
index 16b8ade..bc6881c 100755
--- a/tools/run_phyFit.py
+++ b/tools/run_phyFit.py
@@ -1,29 +1,112 @@
 #!/usr/bin/env python3
 """**run_phyFit.py** [options] <input file name>
 
-   Perform fit with data and model from yaml file 
+  Perform fit with data and model from yaml file 
 
-   Uses functions xyFit and hFit from PhyPraKit.phyFit
+  Uses functions xyFit and hFit from PhyPraKit.phyFit
 
-   This code performs fits 
+  This code performs fits 
 
-      - to x-y data with independent and correlated, absolute 
-        and relative uncertainties in the x and y directions 
+     - to x-y data with independent and correlated, absolute 
+       and relative uncertainties in the x and y directions 
  
-      - and to histogram data with a binned likelihood fit.
+     - and to histogram data with a binned likelihood fit.
 
-   usage:
+  usage:
 
-      ./run_phyFit.py [options] <input file name>
+     ./run_phyFit.py [options] <input file name>
 
-      ./run_phyFit.py --help for help
+     ./run_phyFit.py --help for help
 
 
-   Input:
+  Input:
 
-      - input file in yaml format
-      - output depending on options
+     - input file in yaml format
+     
+  output:
+      
+     - text and/or file, graph depending on options
+
+
+  **yaml format for x-y fit:**
+
+  .. code-block:: yaml
+
+    label: <str data-set name>
+
+    x_label: <str name x-data>
+    x_data: [  list of float ]   
+
+    y_label: <str name y-data>  
+    y_data: [ list of float ]
+
+    x_errors: <float>, [list of floats], or {dictionary/ies}
+    y_errors:  <float>, [list of floats], or {dictionary/ies}
+
+    model_label: <str model name>
+    model_function: |
+      <Python code>
+
+    format of uncertainty dictionary: 
+    - error_value: <float> or [list of floats]
+    - correlation_coefficient: 0. or 1.
+    - relative: true or false
+    relative errors may be spcified as <float>%
+
+  Simple example of *yaml* input:
+
+  .. code-block:: yaml
+
+    label: 'Test Data'
+
+    x_data: [.05,0.36,0.68,0.80,1.09,1.46,1.71,1.83,2.44,2.09,3.72,4.36,4.60]
+    x_errors: 3%
+    x_label: 'x values'
+
+    y_data: [0.35,0.26,0.52,0.44,0.48,0.55,0.66,0.48,0.75,0.70,0.75,0.80,0.90]
+    y_errors: [.06,.07,.05,.05,.07,.07,.09,.1,.11,.1,.11,.12,.1]
+    y_label: 'y values'
+
+    model_label: 'Parabolic Fit'
+    model_function: |
+      def quadratic_model(x, a=0., b=1., c=0. ):
+        return a * x*x + b*x + c
+
+
+  **Example of yaml input for histogram fit:**
+
+  .. code-block:: yaml
+
+    # Example of a fit to histogram data
+    type: histogram
+
+    label: example data
+    x_label: 'h' 
+    y_label: 'pdf(h)'
+
+    # data:
+    raw_data: [ 79.83,79.63,79.68,79.82,80.81,79.97,79.68,80.32,79.69,79.18,
+            80.04,79.80,79.98,80.15,79.77,80.30,80.18,80.25,79.88,80.02 ]
+
+    n_bins: 15
+    bin_range: [79., 81.]
+    # alternatively an array for the bin edges can be specified
+    #bin_edges: [79., 79.5, 80, 80.5, 81.]
+
+    model_density_function: |
+      def normal_distribution(x, mu=80., sigma=1.):
+        return np.exp(-0.5*((x - mu)/sigma)** 2)/np.sqrt(2.*np.pi*sigma** 2)
+
+
+  *Remark*: more than one input data sets are also possible. 
+  Data sets and models can be overlayed in one plot if option 
+  `showplots = False` ist specified.
+
+  .. code-block:: yaml
 
+    # several input sets to be separated by 
+    ...
+    ---   
 """
 
 from PhyPraKit.phyFit import xyFit_from_yaml, hFit_from_yaml