pypaws 0.6.7

the Platform for Automated Workflows by SSRL

paws: the Platform for Automated Workflows by SSRL
==================================================


Description
-----------

`paws` stands for the Platform for Automated Workflows by SSRL.
It was conceived to serve as a fast, lean, and modular
workflow manager for image-like data.

`paws` provides machinery
to build and execute data processing workflows,
including an ever-growing library of Operations
that connect together to form a workflow
with somewhat of a directed graph structure.

The core modules of `paws`
are pure Python and have very few dependencies.
`paws` exposes a simple API
that interacts with these core modules,
for users to write scripts based on `paws`,
or to import the `paws` API to perform
back-end computations for other applications or widgets.
The current state of `paws` is alpha-
nothing has been tested,
and even less has been optimized.

The `paws` package also includes a graphical application
built on the `PySide` `Qt` bindings.
Through this GUI, users can build and configure workflows,
examine existing `paws` Operations,
develop new `paws` Operations,
and visualize the outputs of their workflows.
Various simplified GUIs are currently in development
for interacting with specific workflows.


Example
-------

Here is an example of how to use `paws`
to write a data processing script.
Note: at the time this was written,
the example does not display in github.
Open the source file for this README
to see the example.
Complete instructions are included in the user manual.
See the `doc` directory of this repository.

This script performs a common diffraction data processing workflow:
it reads some calibration parameters (in Nika format),
converts them to PONI (PyFAI) format,
reads an image, uses the calibration parameters
to calibrate and reduce the image with PyFAI,
and windows the useful part of the data.
After executing, the useful data is extracted
and plotted using matplotlib.

.. code-block:: python
import paws.api
from matplotlib import pyplot as plt

mypaw = paws.api.start()

# Start a workflow, name it
mypaw.add_wf('test')

# Instantiate operations, name them, add them to the workflow
mypaw.add_op('read_cal','INPUT.CALIBRATION.NikaToPONI')
mypaw.add_op('read_img','INPUT.TIF.LoadTif')
mypaw.add_op('cal_reduce','PROCESSING.CALIBRATION.CalReduce')
mypaw.add_op('window','PACKAGING.WindowZip')

# Set up the input routing:
# WXDToPONI reads a WXDiff calibration result
# and translates it to PONI (PyFAI) format
mypaw.set_input('read_cal', 'wxd_file',
src='filesystem', tp='path', val='/path/to/file.nika')

# LoadTif loads a tif image
mypaw.set_input('read_img', 'path',
src='filesystem', tp='path', val='/path/to/image.tif')

# CalReduce takes a PONI dict and an image,
# calibrates and reduces to I(q) vs. q
mypaw.set_input('cal_reduce', 'poni_dict',
src='workflow', tp='reference', val='read_cal.outputs.poni_dict')
mypaw.set_input('cal_reduce', 'image_data',
src='workflow', tp='reference', val='read_img.outputs.image_data')

# WindowZip takes x and y data and a window (xmin<x<xmax),
# outputs the x and y data that live within the window
mypaw.set_input('window','x',
src='workflow', tp='reference', val='cal_reduce.outputs.q')
mypaw.set_input('window','y',
src='workflow', tp='reference', val='cal_reduce.outputs.I')
mypaw.set_input('window','x_min', src='text', tp='float', val=0.02)
mypaw.set_input('window','x_max', src='text', tp='float', val=0.6)

# Execute the workflow
mypaw.execute()

# Grab the reduced data
q_I_out = mypaw.get_output('window','x_y_window')

# Plot the reduced data
plt.semilogy(q_I_out[:,0],q_I_out[:,1])
plt.show()


Installation
------------

The full `paws` package is now available on PyPI.
To install in a working Python (>=2.6,<3) environment, invoke `pip`:
`pip install pypaws`

The dependencies of `paws` are not yet properly declared in the package.
In a near future version, the core and graphical modules will be distributed in separate PyPI channels,
and the dependencies of individual Operations will be checked and handled at run time.


Attribution
-----------

`paws` was written at SSRL by Chris Tassone's research group.
If you use `paws` in your published research,
we will greatly appreciate a citation.

Before citing `paws`, it is of primary importance that you cite
the authors of the original work that produced your results:
in most cases this will be separate from the citation for `paws`.
Citations for your specific operations can be found
by looking those operations up in the `paws` documentation:
(TODO: insert readthedocs link here).
If the documentation is unclear for the operations you need to cite,
please contact us at `[e-mail]`,
and we will return the correct citation
and fix the missing documentation.

A proper citation for `paws` itself can be found
at the beginning the `paws` documentation:
(TODO: insert readthedocs link here.)


Contribution
------------

Contribution to `paws` is encouraged and appreciated.
Whether you are a researcher looking to contribute operations to the `paws` library,
or a software developer looking to contribute to the platform itself,
the `paws` development team would love to hear from you.

See the documentation (TODO: insert readthedocs link here)
for basic instructions on contributing,
and/or get in touch with the `paws` development team
at `[e-mail]`.


License
-------

The 3-clause BSD-like license attached to this software
can be found in the LICENSE file in the source code root directory.