From d32d1b857ea2f92e1d8e0d58880903a0dc592396 Mon Sep 17 00:00:00 2001
From: Holger Frey <frey@imtek.de>
Date: Wed, 17 Feb 2021 14:45:45 +0100
Subject: [PATCH] updated readme

---
 README.md | 67 ++++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 62 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 503ca54..2ffc9f4 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,8 @@
 Sensospot Data Parser
 =====================
 
-Parsing the numerical output from Sensovation Sensospot image analysis.
+Parsing the numerical output from Sensovation Sensospot image analysis and some 
+other useful functions for working with the data.
 
 ## Example:
 
@@ -10,15 +11,71 @@ Parsing the numerical output from Sensovation Sensospot image analysis.
     import sensospot_data
 
     # read the raw data of a folder
-    raw_data = sensospot_data.process_folder(<path to results directory>)
+    raw_data = sensospot_data.parse_folder(<path to results directory>)
+
+    # apply an exposure map to add more data:
+    #   key relates to column "Exposure.Id"
+    #   values are (Exposure.Channel, Exposure.Time)
+    exposure_map = {
+        1: ("Cy3", 100),
+        2: ("Cy5", 150),
+        3: ("Cy5", 15),
+    }
+    enhanced_data = sensospot_data.apply_exposure_map(raw_data, exposure_map)
 
     # split the measurement according to channels
-    channels = sensospot_data.split_channels(raw_data [, optional_exposure_map])
+    channels = sensospot_data.split_data_frame(enhanced_data "Exposure.Channel")
 
-    # normalize one channel to a specific exposure time
-    cy5_normalized = sensospot_data.normalize_channel(channels["cy5"], normalized_time=25)
+    # merge the two cy5 measurements together, creating an extended dynamic range
+    cy5_xdr = sensospot_data.create_xdr(channels["cy5"], normalized_time=25)
 ```
 
+## Avaliable functions:
+
+from .parser import parse_file, parse_folder  # noqa: F401
+ - **parse_folder(path_to_folder)**
+   Searches the folder for parsable .csv files, parses them into one big pandas
+   data frame and will add additional meta data from parameters folder, if 
+   it is present.
+- **parse_file(path_to_csv_file)**
+   Parses the csv file into a pandas data frame and will add additional some
+   meta data from the file name. Is internally also used by `parse_folder()`
+ - **split_data_frame(data_frame, column)**  
+   Splits a data frame based on the unique values of a column. Will return a 
+   dict, with the unique values as keys and the corresponding data frame as 
+   value
+ - **apply_exposure_map(data_frame, exposure_map)**
+   Adds information about the channel and exposure time to a data frame, based 
+   on the exposure id. Will get bonus karma points, if the named tuple 
+   `ExposureInfo` is used:
+   `{1:ExposureInfo("Cy3", 100), 2:ExposureInfo("Cy3", 100), }`
+ - **ExposureInfo(exposure_channel, exposure_time)**  
+   A named tuple for defining an exposure map. Usage will increase readability 
+   and karma points.
+ - **blend(data_frame, [column="Spot.Mean", limit=0.5])**  
+   If provided with a data frame with multiple exposure times for the same 
+   exposure channel, the function will blend theese two times together based
+   on given column and limit.
+ - **normalize_values(data_frame, [normalized_time=None])**  
+   Adds new columns to the data frame with intensity values recalculated to the
+   normalized exposure time. If no time is given, the max exposure time is used.
+ - **create_xdr(data_frame, [normalized_time=None, column="Spot.Mean", limit=0.5])**  
+   This combines the methods `blend()` and `normalize_values()` into one call.
+   What a joy! 
+
+## CLI
+
+For the (propably) most important function, there is even a cli command
+```sh
+Usage: parse_sensospot_data [OPTIONS] SOURCE
+
+Arguments:
+  SOURCE:             Folder with Sensospot measurement
+
+Options:
+  -o, --outfile TEXT  Output file name, relative to SOURCE, defaults to 'raw_data.h5'
+  --help              Show this message and exit.
+```
 
 ## Development