# Documentation for chemexpy package

### Package version: v1.0.10
### Date: 10/06/2021
### Author: Auste Kanapeckaite


## The package contains the following functions:
1. data_prep
2. molecule_check
3. scatter_plot
4. correlation_plot
5. feature_plot
6. normality_check
7. feature_check
8. feature_violinplots
9. similarity_search
10. similarity_dendogram
11. similarity_heatmap


## Dependencies:

rdkit, pandas, numpy, scipy, seaborn, matplotlib, collections

Rdkit is advised to be installed using conda environment. 


## Introduction

*Chemexpy* package provides a user-friendly and organised approach to explore chemical libraries and identify key features. The information generated by the package functions can be easily integrated into other pipelines or downstream processing. Package provides exploratory plots as well as compound similarity assessment or search for similar compounds. Moreover, there are several additional functions to easily extract chemical descriptors and evaluate chemical libraries.



## Function Description


1. Function __data_prep__

    Function call example: __data_prep(data,*args)__

  
    Function provides a snapshot of the input data as well as returns a processed data file to include information on
    #chemical descriptors, atomic composition, chemicle structure features.
    
    __Input__: path to a csv file that containds compound ID 'CID' and smiles 'SMILES' columns. These columns have to be named as described above.Additional columns can be passed as arguments if, for example, the data file contains other columns of 
    interest.
    
    __Output:__ data frame with added chemical descriptors. The output could be integrated into dowstream analyses,  databases, or used to visualise the structures.

2. Function __molecule_check__

    Function call example: __molecule_check(data,*args)__


    Function allows to visualise molecules of interest as well as returns a  data frame that containts information on the selected list of molecules. It is recommended not to select more than 20 molecules at a time to draw the structures.

    __Input:__ data frame with "CID" (compound ID) and "SMILES" (smiles column). Please note, the IDs for columns need to match the examples.

   __Additional input:__ arguments for "CID", e.g. "2821293". If none is selected first 10 structures will be drawn. Names for compounds have to be in a string format.

    __Output:__ structure visualisation and a data frame that can be used for further visualisations.

3. Function __scatter_plot__

    Function call example: __scatter_plot(data,var1=None,var2=None)__

    Function takes a data file provided by the data_prep function and plots analytical scatter plots for selected variables.

    __Input:__ data frame generated by the data_prep function, as well as variables to plot, e.g. "MW" and "TSPA".

    __Output:__ scatter plot.

4. Function __correlation_plot__

    Function call example: __correlation_plot(data,*args)__


    Function takes data file provided by the data_prep function and plots plots a correlation heatmap.
    
   __Input:__ data frame generated by the data_prep function, as well as variables to calculate correlation and plot, e.g. "MW" and "TSPA".
    
    If the user does not select args, the default values will be used: "Atom_number","MW","TSPA","HBD_count","HBA_count","Rotatable_bond_count","MolLogP","Ring_number","AP".
    
    __Output:__ scatter plot for correlation visualisation and a data frame with correlation values.


5. Function __feature_plot__

    Function call example: __feature_plot(data,*args)__


    Function takes data file provided by the data_prep function and plots analytical scatter plots for multiple features.
    
    __Input:__ data frame generated by the data_prep function, as well as variables for feature ploting, e.g. "MW" and "TSPA".
    
    If the user does not select args, the default values will be used:"Atom_number","MW","TSPA","HBD_count","HBA_count",#       "Rotatable_bond_count","MolLogP","Ring_number","AP".
    
    __Output:__ scatter plot of multiple feature visualisation.



6. Function __normality_check__

    Function call example: __normality_check(data,var=None)__


    Function takes the data file provided by the data_prep function and plots histogram with estimated probability density function.
    
    __Input:__ data frame generated by the data_prep function, as well as a single variable to check normality, e.g. "MW" and "TSPA".
    
    __Output:__ bar plot with an estimated normal distribution line plot based on distribution probability.
 

7. Function __feature_check__

    Function call example: __feature_check(data,var1=None, var2=None, type=None)__


    Function takes the data file provided by the data_prep function and plots analytical contour plots to assess chemical feature distribution when considering a specific chemical entity category. That is,a categorical type data needs to be provided, such as active or inactive, etc.

    __Input:__  data frame generated by the data_prep function, two variables for disctribution check, e.g. "MW" and "TSPA", and
    a column name to select categorical data from.

    __Output:__ contour plot with feature distribution.


8. Function __feature_violinplots__

    Function call example: __feature_violinplots(data,var1=None,type=None)__


    Function takes the data file provided by data_prep function and plots analytical violin plots to assess type distribution for selected fetaures.
    Note categorical type data needs to be provided, such as active or inactive, etc.

    __Input:__ data frame generated by the data_prep function, as well as a variable name which distribution will be checked, e.g. "MW" and "TSPA", also a column name is required to select categorical data specified through "type" designation.

    __Output:__ contour plot with feature distribution.


9. Function __similarity_search__

    Function call example: __similarity_search(data, target=None)__

    Function takes the data file provided by the data_prep function and searches for similar structures based on the target molecule.
    Fingerprinting is based on Morgan fingerprints and similarity search is based on Tanimoto Similarity.

   __Input:__ data frame generated by the data_prep function, as well as a SMILE string (e.g., "target" variable) for a molecule to search the database. 

    __Output:__ data frame of similar structures.

10. Function __similarity_dendogram__

    Function call example: __similarity_dendogram(data)__

    Function takes the data file provided by the data_prep function and plots a dendogram based on compound similarity.

    Fingerprinting is based on Morgan fingerprints and similarity search is based on Tanimoto Similarity.

    __Input:__ data frame generated by data_prep function.

    __Output:__ dendogram and a data frame with similarity values.

11. Function __similarity_heatmap__

    Function call example: __similarity_heatmap(data)__



    Function takes the data file provided by the data_prep function and plots a heatmap based on compound similarity.

    Fingerprinting is based on Morgan fingerprints and similarity search is based on Tanimoto Similarity.

    __Input:__ data frame generated by the data_prep function.

    __Output:__ heatmap and a data frame with similarity values.


## Running tests and example use cases.



The working directory should contain example data (provided with packages PATH="./tests"). There are several datasets, namely data_1.csv and data_2.csv, which can be used to explore various functions.


    #initiative variables to data
    data="./test/data_1.csv"

    #prepare the data for subsequent use
    #we are selecting an additional column to assess the activity based on categorical value
    data=data_prep(data, "Type")


    #assess a selected set of molecules and retrieve a data frame that contains information about these molecules
    data_eval=molecule_check(data,"2821293")


    #evaluate exploratory plots

    scatter_plot(data,"MW","TSPA")

    corr=correlation_plot(data,"MW","TSPA","AP","HBD_count","HBA_count")

    #perform multiple feature assessment
    feature_plot(data,"MW","TSPA","AP","HBD_count","HBA_count")


    #check the normality of data distribution
    normality_check(data,"MW")

    #since we have one categorical value we can perform feature check
    feature_check(data,var1="MW", var2="AP", type="Type")


    #similarity assessment
    target='COC(=O)c1c[nH]c2cc(OC(C)C)c(OC(C)C)cc2c1=O'
    target_matches=similarity_search(data, target)

    #similarity value generation for all pairwise comparisons 

    #dendogram ploting and a data frame preparation with similarity values
    #both functions produce the same data frame
    similarity_data=similarity_dendogram(data)
    similarity_datasimilarity_heatmap(data)



