Metadata-Version: 2.1
Name: cytolysis
Version: 0.0.7
Summary: An API to analyze cytosim simulations
Home-page: https://gitlab.com/SergeDmi/cytosim_analysis
Author: Serge Dmitrieff
License: UNKNOWN
Platform: UNKNOWN
Description-Content-Type: text/markdown
Requires-Dist: numpy
Requires-Dist: sio-tools
Requires-Dist: pandas

# Cytosim_analysis
A python module to facilitate the automatic analysis cytosim simulations.
By itself, it does not include many analysis functions but mostly an API.



## Requirements
Requires Python3 and modules numpy, pandas, sio_tools. 
```bash
pip3 install sio_tools 
pip3 install pandas
pip3 install numpy
```

## Practical examples
We provide several examples where we analyze the result of a simulation for an example [config file](examples/example.cym). 
This simulation has two asters of microtubules brought to the center by the rigidity of the microtubules and by the activity of dyneins.
![](examples/example.jpg) 

An example counting the number of fiber points for each filament, and at each time:
```bash
python3 example_fibers.py
```
An example where we compute the fiber bending energy as a function of time
```bash
python3 example_fiber_curvature.py
```
By creating a representation for solid, 


## Interface (examples)
Import the module : 
```python
import cytosim_analysis as ana
```

The main class is *Simulation*, a list of time frames. Create an instance of a simulation analysis via :
```python
microtubule_reports={'points' : 'fiber_points.txt' }
simul = ana.Simulation(reports={'microtubule': microtubule_reports},
                        config='config.cym') 
```

You can specify analysis functions for the different simulation objects, specifying by object name :
```python
def count_points(fiber):
    return fiber.shape[0]

def count_fibers(frame):
    return len(frame.fibers)

analyzer={}
analyzer['microtubule'] = {'pts_number': count_points}
analyzer['frame'] = {'fib_number': count_fibers}
```

You can then run the analysis :
```python
simul.make_analysis(analyzer=analyzer)
```

The analysis of objects is stored as pandas dataframes in the frames. For exemple, the analysis of microtubules for frame *5* is stored in :
```python
simul[5].fibers_analysis['microtubule']
```
Similarly, the analysis for couples 'arp_2_3' at frame 10 is stored in :
```python
simul[10].couples_analysis['arp_2_3']
```
Following this logic, since simul is a set of frames, the results of the analysis of all frames can be accessed in :
```python
simul.frames_analysis
```

The module contains a function to export analysis dataframes into csv files :
```python
ana.export_analysis(simul.frames_analysis, 'frames.csv')
```

## Components

### Simulation
The class *Simulation* is a set of *frames*, instances of the class [Frame](#frame). Input arguments : 
- reports : a dictionary of dictionaries of pathes to report files.
- options : a dictionary of dictionaries of options.
- config : path to the config file

Simulation has a method *make_analysis* to perform the analysis. 
This takes as option *analyzer*, a dictionary of dictionaries of analysis functions.  

*simulation.make_analysis* performs the analysis specified in *analyzer["simulation"]*, 
and the result is stored in *simulation.analysis*.  

As a set of frames , simulation implements *simulation.analyze(frame, analyzer=..., ... )* (see [Object_set](#object_set)).
This performs the analysis specified in *analyzer['frame']*. The results are stored in *simulation.frames_analysis*

### Frame
Each frame contains several types of dictionaries of object_set : *fibers*,  *couples*, *objects* (this last one being generic).  
Each dictionary is of the type : { name : [object_set](#object_set) }.
These dictionaries are :
- *frame.fibers*
- *frame.couples*
- *frame.objects*

Once the analysis has been performed, the analysis results are stored in :
- *frame.fibers_analysis*
- *frame.couples_analysis*
- *frame.objects_analysis*

Frame implements the analysis method *frame.make_analysis(...)* that calls the *object_set.analyze(object, ...)* method of all object sets. 

### Object_set
Object set is a class derived from list. *Fibers_set* and *Couples_set* are derived from *Object_set*. Input arguments :
- *name* : name of the object (e.g. "microtubule")
- *type* : type of the object (e.g. "fiber")  
Optional input arguments :
- *config* : the pile read from the configuration file
- *build* : a function to build the object set from the reports  

Beyond the initialization (*__init__*) method, object set need to implement the methods :
- *object_set.analyze(object, ... )* : a function that analyzes *object*, a given item from the object set
- *object_set.type* : object type 
- *object_set.name* : object name 
- *object_set.id* : object id (a number) 
- *object_set.properties* : a dictionary of properties read from the config file

### Analysis
All the analysis results (*simulation.analysis*, *frame.fibers_analysis*, etc.) are stored as Pandas dataframes and, by default, exported as csv files.
- *frame.fibers_analysis[fiber_name]* is a dataframe with as many rows as there are fibers.
- *frame.couples_analysis[couple_name]* is a dataframe with as many rows as there are couples.
- *frame.objects_analysis[object_name]* is a dataframe with as many rows as there are objects.
- *simulation.frame_analysis* is a dataframe with as many rows as there are frames.
- *simulation.analysis* is a dataframe with a single row.

Therefore, if one wants to look at the distribution of some property among objects for a given frame, 
one would export *frame.object_analysis[object_name]*.  
If one wants to analyze something over time, one would export *simulation.frame_analysis*.  
If one wants a single line to sumarize the simulation, for instance in order to compare different simulations, one would
export *simulation.analysis*.

