82a4ca57a2a8c5adda4f7f7a22d5eae0c9082351
[igor.git] / README
1 ====
2 Igor
3 ====
4
5 :Authors: W. Trevor King <wking@tremily.us>;
6           Paul Kienzle <paul.kienzle@nist.gov>
7 :License: GNU General Public License, version 3+
8
9 Python parsers for Igor Binary Waves (.ibw) and Packed Experiment
10 (.pxp) files written by WaveMetrics' IGOR Pro software.
11
12 Installation
13 ============
14
15 Packages
16 --------
17
18 If `igor` already exists in your package manager's repository, you
19 should install `igor` in the usual way.
20
21 Gentoo
22 ~~~~~~
23
24 I've packaged `igor` for Gentoo.  You need layman_ and my `wtk
25 overlay`_.  Install with::
26
27     # emerge -av app-portage/layman
28     # layman --add wtk
29     # emerge -av sci-misc/igor
30
31 Dependencies
32 ------------
33
34 If you're installing by hand or packaging `igor` for another
35 distribution, you'll need the following dependencies:
36
37 ===========  =================  ============================
38 Package      Debian_            Gentoo_
39 ===========  =================  ============================
40 Numpy_       python-numpy       dev-python/numpy
41 Matplotlib_  python-matplotlib  dev-python/matplotlib
42 Nose_        python-nose        dev-python/nose
43 ===========  =================  ============================
44
45 Installing by hand
46 ------------------
47
48 `igor` is available as a Git_ repository::
49
50     $ git clone git://tremily.us/igor.git
51
52 See the homepage_ for details.  To install the checkout, run the
53 standard::
54
55     $ python setup.py install
56
57 You can also automate this installation with pip_.
58
59     $ pip install igor
60
61 Usage
62 =====
63
64 See the docstrings and unit tests for examples using the Python API.
65 The package also installs to scripts, ``igorbinarywave.py`` and
66 ``igorpackedexperiment.py`` which can be used to dump files to stdout.
67 For details on their usage, use the ``--help`` option.  For example::
68
69   $ igorbinarywave.py --help
70
71 For users transitioning from igor.py_, there's a compatibility module
72 exposing the old interface.  Just change::
73
74   import igor
75
76 to::
77
78   import igor.igorpy as igor
79
80 in your calling code.
81
82 Testing
83 =======
84
85 Run internal unit tests with::
86
87     $ nosetests --with-doctest --doctest-tests igor test
88
89 The data in the ``test/data`` directory is in the Git repository, but
90 it is not bundled with the source code.  If you want the test data,
91 you'll have to clone the Git repository or download a snapshot.
92
93 Licence
94 =======
95
96 This project is distributed under the `GNU Lesser General Public
97 License Version 3`_ or greater, see the ``COPYING`` file distributed
98 with the project for details.
99
100 Maintenance
101 ===========
102
103 Maintainer
104 ----------
105
106 W. Trevor King
107 wking@tremily.us
108 Copyright 2008-2012
109
110 Release procedure
111 -----------------
112
113 When a new version of the package is ready, increment __version__
114 in ``igor/__init__.py`` and run update-copyright_::
115
116     $ update-copyright.py
117
118 to update the copyright blurbs.  Then run::
119
120     $ python setup.py sdist upload
121
122 This will place a new version on PyPI.
123
124
125 .. _layman: http://layman.sourceforge.net/
126 .. _wtk overlay: http://blog.tremily.us/posts/Gentoo_overlay/
127 .. _Debian: http://www.debian.org/
128 .. _Gentoo: http://www.gentoo.org/
129 .. _NumPy: http://numpy.scipy.org/
130 .. _Matplotlib: http://matplotlib.sourceforge.net/
131 .. _Nose: http://somethingaboutorange.com/mrl/projects/nose/
132 .. _Git: http://git-scm.com/
133 .. _homepage: http://blog.tremily.us/posts/igor/
134 .. _pip: http://pypi.python.org/pypi/pip
135 .. _igor.py: http://pypi.python.org/pypi/igor.py
136 .. _GNU Lesser General Public License Version 3:
137     http://www.gnu.org/licenses/lgpl.txt
138 .. _update-copyright: http://blog.tremily.us/posts/update-copyright/