Merge branch 'custom_plots_LB'

Author: Lblackhurst29

.gitignore

@@ -5,4 +5,5 @@ dist/
 *vscode
 __pycache__/
 ethoscopy.egg-info/
-test/
+.gitignore
+*.pkl

README.md

@@ -1,20 +1,56 @@
-**ethoscopy**
+# ethoscopy 
 
-Head to: https://bookstack.lab.gilest.ro/books/ethoscopy for an in-depth tutorial on how to use ethoscopy
+A data-analysis toolbox utilising Pandas, Seaborn, and Plotly to curate, clean, analyse, and visualise behavioural time series data. Whilst the toolbix was created around the data produced from an Ethoscope (a Drosophila monitoring system), if the users data follows the same structure for time series data all methods can be utilised.
 
-A data-analysis toolbox utilising the python language for use with data collected from 'Ethoscopes', a Drosophila video monitoring system.
+<del> Head to the [tutorial](https://bookstack.lab.gilest.ro/books/ethoscopy) for an in-depth walk through. </del>
+- currently the above tutorial is out of date. Use the jupyter notebooks to learn how to use the package
+- I promise to update the tutorial soon so it is aligned with the 2.0 version
 
-For more information on the ethoscope system: https://www.notion.so/The-ethoscope-60952be38787404095aa99be37c42a27
+For more information on the Ethoscope system, click [here](https://www.notion.so/The-ethoscope-60952be38787404095aa99be37c42a27)
+    - If using in conjenction with Ethoscope data this software contains functions for loading the Ethoscope data into ethocopy from .db files both locally and in remote ftp servers.
 
-Ethoscopy is made to work alongside this system, working as a post experiment analysis toolkit. 
+At its core ethoscopy is a subclass of the data manipulation tool Pandas. The dataframe object has been altered to contain a linked metadata dataframe which contains experimental information. This secondary dataframe can be used to filter the data containing dataframe, as well as a store of information per specimen during analysis.
 
-Ethoscopy provides the tools to download experimental data from a remote ftp servers as setup in ethoscope tutorial above. Downloaded data can be curated during the pipeline in a range of ways, all formatted using the pandas data structure.
+Ethoscopy contains methods to perform common analytical techniques per specimen in the data table, such as removing dead specimens, interpolating missing values, or calculating sleep from movement. Addtionally, specialist anlysing tools have been implemented for analysing circadian rhythm, such as periodograms, and for generating hidden Markov models (HMM) to understand latent behavioural states. HMMs are trained utilising hmmlearn in the background and come accompanied with a range of visualisation tools to understand the generated model.
 
-Further the ethoscopy package provides behavpy a subclassed version of pandas that combines metadata with the data for easy manipulation. Behavpy can be used independently of the Ethoscope system data if following the same structure. Within behavpy there are a range of methods to curate your data and then to generate plots using the plotly plotting package. Additionally, there are methods to analyse bout length, contiguous sleep, and many circadian analysis methods including periodograms.
+### -- Update to 2.0 --
 
-Within Behavpy is a wrapped version of the python package hmmlearn, a tool for creating hidden markov models. With the update the user can easy train new HMMs from their data and use bult in methods to create graphs analysing the decoded dataset.
+This new update sees a whole refactoring of the code base to make everything more streamline and keep the package up to date with the new versions of pandas and numpy. Gone are seperate classes for periodograms and HMM based analysis, all are under one class behavpy(). Addtioanlly, now the user can choose between plotter packages, Seaborn and Plotly, and choose a desired colour pallete. The previous used package Plotly can balloon the size of jupyter notebooks, putting a strain on storage, despite being great for data exploration. If you just want static plots, use Seaborn. But be wary of comparison, the backend for Plotly plots is all calculated in ethoscopy applying z-score and bootstrapping to quantification plots, whereas Seaborn based plots will use the Seaborn internal tools for errors and averaging.
 
--- Update to 1.3.0 --
+The latest update is backwards compatible with all previously saved behavpy dataframes. However, post loading they should be re-initiated as the new behavpy class. 
 
-The latest update now allows the user to choose the colour palette from plotly to be applied to all plotting methods, see the updated tutorial on how to do this. 
-Additionally, the .pivot() method has been changed to .analyse_column() to avoid overwriting the original pandas method. Also, puff_mago and find_motifs analysing functions have been renamed to stimulus_response and stimulus_prior respectively.
+Addtionally, the concat method ( behavpy_object.concat() ) for combining dataframes has been shifted to a function that is imported automatically. Call etho.concat(df1, df2) or etho.concat(*[df1, df2]) instead. There are other minor changes to method and argument names, which are reflected in their docstrings and in the tutorial. 
+
+## Getting Started
+
+Ethoscopy can be installed via pip from [PyPi](https://pypi.org/project/ethoscopy/)
+
+We recommned installing ethoscopy into a virtual environment due to specific package versions.
+
+```bash
+python pip install ethoscopy
+```
+
+## Example of use
+
+Ethoscopy is primarily made to work in a Jupyter notebook environment and should be imported in as so:
+
+```bash
+import ethoscopy as etho
+```
+
+Generate a behavpy dataframe object as so:
+
+```bash
+data = pandas_dataframe
+metadata = pandas_dataframe
+
+df = etho.behavpy(data, metadata, check = True, canvas = 'plotly', palette = 'Set2')
+
+# select only the data from specimens in experimental group 2
+filtered_df = df.xmv('experimental_column', 'group_2')
+```
+
+## License
+
+This project is licensed under the [GNU-3 license](LICENSE)