Commit 4c752986 authored by Yori Fournier's avatar Yori Fournier
Browse files

Update README

parent 04813a55
* Introduction
** Motivation
As a scientist you need to produce plots.
The question is how to plot?
You usually face large data sets
That you want to process in different manner
and plot one aspect of it.
You also may want to compair a single aspect
of different data set, or different aspect of
a single data set.
And you may want to do in a fast and interactive
manner, but most of it, you want to control what
you do and be sure of what you plot.
Finally, after spending time on a single plot
you want to be able to use it for various data sets,
make it pretty, and be able to keep track of your
plots, reusing them and having a consistency between
version of the plot. Processing large dataset with
the same ploting procedure. And also you don't want
to rethink tomuch when you come back after a week or
two how you did that plot.
These are the basic reason of myplotlib.
myplotlib allows you to design a plot, that consist
of only one single file that can be combined with any
other plot, or alone.
This plot contains it own data processing and can be
used for any data you provide.
It can be called interactively for comparing, and reads
only one the large raw data set. In case the raw data
processing is long you can also prevent extra computation.
After comparing the data, you may also want to roduce a
large amount of files, that plot the same things for
various datasets. The script mode is designed for that.
You can use myplotlib from command line and give it
arguments.
In case you are fine with a plot, but after some time
your recognise that some change are required, because
your plot is in a unique file indpendntly how many time
you use it in various configurations, any changes will
be spread, allowing fast and consistent corrections.
to summarize myplotlib can:
- interactive mode
- script mode
- consistent corrections
- versatile dataset
- full user control on IOs and data processing
making it fast and safe
** Conceptual workflow
It is important to understand that myplotlib is a data-oriented
plot library. A class represents a figure and an instance of a class
is a realisation of this class (plot) with a given data set.
This fact is important to understand since pyplot of matplotlib
adopt a different approach. Ideed matplotlib consider an empty
figure as an instance of figure class. So not only the data but
also the aspect of the plot are part of the instance.
We made the choice to disantangle both aspect for more transparency
and a better control on what is plotted. As usual this aproach has
advantage and drawbacks.
The major adavntage is a deep understanding and control on what you
are doing, that is an important aspect for scientists.
The major drawback is a longer (but more awared) process for to
plot. You should know what to plot, and somehow how, before starting.
** Organisation of this document
* Requirements
- matplotlib
- texlive-latex-extra (latex package for tex fonts in plots)
- dvipng (dvi to png for print to file)
* Structure of the Package
** The subpackages
** The class structure
An object MyFig is an object-plot made of MyAxes objects which
represents the plots.
In order to make a new object-plot, you should create a class MyNewFig
being inheritant from MyFig, at least 3 functions: __init__,
printDebug, plot and update. like:
* Exemples
** The MyFig object
# ======== myNewFig.py ================================================
# Import --------------------------------------------------------------
from interface import *
# Default values ------------------------------------------------------
dMyNewParam = None
dfigsize=(<width in inches>, <height in inches>)
# CLASS MyNewFig ------------------------------------------------------
class MyNewFig(MyFig):
# Constructor -------------------------------------------------------
def __init__(self, figsize=dfigsize, # needed
myNewParam=dMyNewParam, <some args>, # optional
*args, **kwargs): # needed
# Parent constructor
MyFig.__init__(self, figsize=dfigsize, *args, **kwargs)
# add your parameters
# i.e.: self.myNewParam = myNewParam
# Print debug function ----------------------------------------------
# This function is called when debug=True
def printDebug(self):
# print some stuff
print('\n'+INFO+"MyNewFig: myNewParam = "+str(self.myNewParam))
# Plot function -----------------------------------------------------
def plot(self):
ratio=6./8. # this is the aspect ratio of the MyAxes object
# frame is the rect of the area which will be covered by the
# MyAxes object. Including axis title...
frame=[<posx>, <posy>, <width>, <height>]
# frame=[0,0,1,1] # for a single plot.
# create at least one MyAxes with MyPrettyAxes being inheretied
# from MyAxes.
ax1 = myplots.MyPrettyAxes(self, ratio, frame)
ax2 = myplots.MyOtherPrettyAxes(self, ratio, frame)
# ...
# add the axes
self.add_axes(ax1)
self.add_axes(ax2)
# plot the axes
ax1.plotting()
ax2.plotting()
# Update function ---------------------------------------------------
def update(self, # nedded
myNewParam=dMyNewParam, <some args>, # optional
*args, **kwargs): # needed
MyFig.update(self, *args, **kwargs)
# This is important to redraw the function, in the same fig.
self.myNewParam = myNewParam
# =====================================================================
** The MyAxes object
# ======== myplots/myNewAxes.py =======================================
# Import --------------------------------------------------------------
from interface.myplots import *
# CLASS MyNewAxes------------------------------------------------------
class MyNewAxes(MyAxes):
# Constructor -------------------------------------------------------
def __init__(self, fig, ratio, frameRect, **kwargs):
# Parent constructor
MyAxes.__init__(self, fig, ratio, frameRect, **kwargs)
# extra parameters
self.fig = fig
self.MyNewParam = self.fig.MyNewParam
# Plotting function -------------------------------------------------
def plotting(self):
# print some stuff if you need
# print...
# read some data if you need
# data=readData(self.MyNewParam)
# this way is also nice
# self.readData()
# compute some stuff if you need
# x, y = computeData(data)
# xlabel, ylabel
xlabel=r'X Axis'
ylabel=r'Y Axis'
self.xaxis.set_label_text(xlabel)
self.yaxis.set_label_text(ylabel)
# plot stuff
self.plot(x,y)
# put some limits
self.set_xlim([-1, 1])
self.set_ylim([-1, 1])
# other pretty stuff ...
# =====================================================================
** Usage
# import interface
>> from interface import *
# to show the fig on the screen
>> screen(MyNewFig, MyNewParam=12.)
# to print it into a file
>> print2file(MyNewFig, 'myNewFig.png')
* Test
to test just type:
python2.7 -m myplotlib -t
it will run a test should not show any error.
* TODOS
** TODO make beter test series with test repport
** TODO make a get opt for the testing to run various test series
** DONE reload the data only when needed
CLOSED: [2016-02-10 mer. 11:31]
** DONE Make a GIT repo
CLOSED: [2016-12-28 Wed 20:19]
** TODO When saving png or ps add meta data of the class version if exists and version of myplotlib
# Motivation
>>>
As a scientist you need to produce plots.
The question is how to plot?
>>>
**plot and compare subsets of large data sets**
>>>
You usually face large data sets,
which you want to process in different manner
to extract and plot a single aspect of this data set.
But you may also want to compare a single aspect
of different data sets, or on the contrary different aspects
of a single data set.
>>>
**plot fast and interactively**
>>>
And you may want to do in a fast and interactive
manner.
>>>
**be sure what you plot**
>>>
But the most important for a scientist is to control what
you do and be sure of what you plot.
>>>
**clear and transparent way to plot**
>>>
Plots are the key value of your work.
You want to spend time on the quality of the content and form.
Not on the technical aspect of how to plot what.
>>>
**reuse, improve, and combine your plots**
>>>
After spending time on designing the content and the
form of a single plot you want to be able to use it for
various data sets without loosing consistence between
versions of the plot.
>>>
**keep track of your plots over long periods**
>>>
Finally, when you come back on some former work,
you don't want to rethink about the technique,
you want to start from the same point as before
from another point of view.
>>>
**These are the basic features of `myplotlib` and much more.**
# The power of `myplotlib`
`myplotlib` allows you to design a plot, that consist
of a single file.
It can then plotted alone or combined with any other plot.
This plot contains it own data processing method and
can be used for any compatible raw data you provide.
A plot can be called interactively from a python interpreter,
or from the command line.
The same plot can be drawn on screen or directly in a file
making sure that what you see is what you get.
Producing files of the same aspect of large number of
data sets is possible thanks to the scripting mode.
Because a plot is in a unique file, any changes will
be spread, allowing fast and consistent corrections.
## `myplotlib` can:
- interactive mode
- script mode
- consistent corrections
- versatile dataset
- full user control on IOs and data processing
making it fast and safe
\ No newline at end of file
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment