ReSim: chemoREsistance SIMulator
================================
ReSim (chemoREsistance SIMulator) is a python package that simulates cancer
chemoresistance dynamics based on a stochastic model. The model describes the
interaction between chemotherapeutics and various cancer cell subpopulations
(including sensitive, primary resistant, acquired resistant and quiescent
cancer cells).

ReSim provides both GUI (powered by `Flask <http://flask.pocoo.org>`) and CUI.

**Remarks**: Simulation result is greatly depended on input params, therefore
ReSim is intended to use in parallel with *in vitro* assay. Procedures or
details in identifying input params *in vitro* is out of scope here and will be
documented in elsewhere (hope to get it publish soon).

Dependencies
____________
* flask
* Flask-WTF
* numpy
* scipy
* pandas
* matplotlib
* seaborn
* plotly
* sdeint

Installation
------------
We **strongly** recommend everyone to install resim within a virtual
environment. Setup the venv as usual and run ::

  $ pip install resim

Otherwise, install it locally.

Getting Start - GUI
-------------------
Open your command prompt, simply run ::

  $ resim-flask

ReSim is now available at http://localhost:5000/resim .

**Note** GUI provides a simplified & handy version of resim with interactive
plotly plots. Please use CUI if you need more control of input params.

Advanced Usage
--------------
Using defaults params (calibrated from the case of sorafenib and liver cancer)::

  >>> import resim

  >>> model = resim.Simulator()
  >>> res = model.simulate()

  >>> snsplt_cells = resim.plot_cells(res, subplot=True)
  >>> snsplt_drug = resim.plot_drug(res)
  >>> snsplt_fht = resim.plot_fht(res)

  >>> snsplt_cells.figure.savefig('resim_cells.png')
  >>> snsplt_drug.figure.savefig('resim_drug.png')
  >>> snsplt_fht.figure.savefig('resim_fht.png')

You may set your own params. For examples, input the growth rate of sensitive cells and resistant cells determined *in vitro*::

  >>> import resim

  >>> model = resim.Simulator(gr=[0.2, 0.1, 0.1])
  >>> res = model.simulate()

`model.simulate()` returns a dict of dictionary containing `pd.DataFrame` or
`np.array`. To extract the result,::

  >>>  df_cells = res['case']['cells']
  >>>  df_drugs = res['case']['drugs']

  >>> l_fht_control = res['control']['fht'])
  >>> l_fht_treatment = res['case']['fht'])

**Notes** GUI outputs are generated by `Plotly <https://plot.ly/>`. But both
`plot_cells`, `plot_drug` and `plot_fht` in CUI return `seaborn
<https://seaborn.pydata.org/>` plot object. You may customize your own theme,
title, layout.

Documentation
-------------
Available at https://resim.readthedocs.io/.

TODO
----
* Add class methods for conventional first-line/second-line chemos in HCC, PC.
* Add tool for converting tumor's diameter/volume to number of cells.
* Add tool for converting doubling time to growth rate.
* Add tool for converting half-life to k.
* Add command line module.
* Integrate parallel programming sde solver module `nsim
  <https://github.com/mattja/nsim>` to speed up the computation.
