sensospot_parser/README.md

Sensospot Data Parser
=====================

Parsing the numerical output from Sensovation Sensospot image analysis and some 
other useful functions for working with the data.

## Example:

```python

    import sensospot_data

    # read the raw data of a folder
    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(enhanced_data "Exposure.Channel")

    # 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, 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_map(data_frame, map, idex_col)**
   Adds information provided in the nested dictionary `map` to a data frame, 
   based on the values in the data_frame column `index_col`. 
 - **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.Saturation", limit=2])**  
   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.Saturation", limit=2])**  
   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

To install the development version of Sensovation Data Parser:

    git clone https://git.cpi.imtek.uni-freiburg.de/holgi/sensospot_data.git

    # create a virtual environment and install all required dev dependencies
    cd sensospot_data
    make devenv

To run the tests, use `make tests` (failing on first error) or `make coverage` for a complete report.