README.md

# plotter-python
Python plot tools for nse projects.

## Installation
Clone current repository and go the downloaded directory

```shell
git clone http://tesla.parallel.ru/Lizzzka007/plotter-nse.git
cd plotter-nse
```

Install it with *pip*
```shell
pip install .
```

Sometimes `pip` refers to *Python 2* package manaager, not *Python 3*. 
In this case install the package with
```shell
python3 -m pip install .
```

Install it with *conda*
```shell
conda develop .
```
## Usage

Data must be stored either in *Tecplot* ASCII file with *.plt* or *.nsx* extensions. 

After installation you can use *plotter-python* tools in your python scripts.  
Import *plotter* module somewhere at the beginning of your script
```python
import plotter
```

### Functions argument description

- `filename` is the name of a file to read for functions `plotter.plot, plotter.plot_contour, plotter.avg_plot` and the template of filenames for the function `plotter.ani_plot`
- `ndim` is the dimensionality of the data contained in `filename`
- `out` is the output directory to save a function result 
- `oname` is the output name of a function result
- `var` is a list or a single variable denoting names(name) to process (may be got from `plotter.dump` function)
- `mval` is a list or a single variable denoting maximum valid absolute values(value) of `var` variables: values which satisfy the condition `var` > `mval` are set as NaN. 
- `min_y` is the minimum value of y-axis for the 1d plotting and the minimum value of the colorbar for the 2d plotting
- `max_y` is the maximum value of y-axis for the 1d plotting and the maximum value of the colorbar for the 2d plotting
- `ifTranspose` if True flips the axis, default = False

### Get variable names from file 
```python
plotter.dump(filename)
```

Positional arguments:
1. string $`filename`$

Function prints names of variables in file `filename`.

### Get data from file 
```python
plotter.get_data(filename, ndim)
```

Positional arguments:
1. string $`filename`$
2. int $`ndim`$

Function returns data contained in file `filename` as a dictionary with key values as variables names.

### Plotting a 1D data
```python
plotter.plot(filename)
```

Positional arguments:
1. string $`filename`$

Optional arguments:
1. string $`out`$
2. string $`oname`$
3. string $`var`$
4. float $`mval`$
5. bool $`ifTranspose`$

Function saves XY plots of 1D data contained in file `filename` into *out/oname* file.

### Plotting animation of a 1D data
 
```python
plotter.ani_plot(filename)
```
Function saves animation of XY plots of 1D data contained in files with the template name `filename` into the *out/oname* file.

Positional arguments:
1. string $`filename`$

Optional arguments:
1. string $`out`$
2. string $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. float $`min\_y`$
6. float $`max\_y`$
7. bool $`ifTranspose`$

### Plotting a 2D data 
```python
plotter.plot_contour(filename)
```
Function saves XY contour plots of 2D data contained in file `filename` into the *out/oname* file.

Positional arguments:
1. string $`filename`$

Optional arguments:
1. string $`out`$
2. string or [string] $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. float or [float] $`min\_y`$
6. float or [float] $`max\_y`$
7. bool $`transpose`$

### Plotting animation of a 2D data 
```python
plotter.ani_plot_contour(filename)
```
Function saves XY contour plots of 2D data contained in file `filename` into the *out/oname* file.

Positional arguments:
1. string $`filename`$

Optional arguments:
1. string $`out`$
2. string or [string] $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. float or [float] $`min\_y`$
6. float or [float] $`max\_y`$
7. bool $`ifTranspose`$

### Plotting an averaged by x and y coordinates 3D data
```python
plotter.avg_plot(filename)
```
Function  saves XY plots of averaged 3D data contained in file `filename` into the *out/oname* file.

Positional arguments:
1. string $`filename`$

Optional arguments:
1. string $`out`$
2. string or [string] $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. bool $`ifTranspose`$

### Plotting slices of 3D data
```python
plotter.slice(filename, plane, slice_position)
```
Function  saves `plane` slice contour plots of  3D data contained in file `filename` into the *out/oname* file.

Positional arguments:
1. string $`filename`$
2. string $`plane`$ can be `xy`, `xz`, `yz`
3. float $`slice_position`$ 

Optional arguments:
1. string $`out`$
2. string or [string] $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. bool $`ifTranspose`$

### Plotting difference of N-d data
```python
plotter.plot_diff(filename, ndim)
```
Function saves plots of the subtraction of the data contained in `filename[1]` from the data contained in `filename[0]` into the *out/oname* file.

Positional arguments:
1. [string] $`filename`$
2. int $`ndim`$

Optional arguments:
1. string $`out`$
2. string or [string] $`oname`$
3. string or [string] $`var`$
4. float or [float] $`mval`$
5. bool $`ifTranspose`$