.\" powder_plot man page
.\"
.\" Copyright © 2012 Andrew Aquila <andrew.aquila@cfel.de>
.\" Copyright © 2012 Thomas White <taw@physics.org>
.\"
.\" Part of CrystFEL - crystallography with a FEL
.\"

.TH POWDER\_PLOT 1
.SH NAME
powder\_plot \- generate 1D powder patterns
.SH SYNOPSIS
.PP
.B powder\_plot
-i mypatterns.{stream,hkl,h5} -o mydata.dat [options]

.SH DESCRIPTION

This program takes as input the data stream from "indexamajig", an hkl file
or an HDF5 file.  It sums the many individual intensities, Bragg peaks or pixels
in the HDF5 file together to form a 1D powder histogram.

The output of powder_plot consists of a three line header followed by a tab
delimited list of 6 values:

 1/d of the histogram bin, where d is the Bragg law d spacing in meters
 the total number of peaks (N)
 the total intensity in the N peaks
 the mean intensity of the N peaks
 the standard deviation of the distribution
 the standard deviation of the mean of the data

The sigma of the mean is not the same as the sigma of the intensities
themselves.  The former quantity measures how accurately the mean intensity has
been determined, whereas the latter quantity measures the spread of the
intensities.

.SH HISTOGRAM OPTIONS

You can set the mininum and maximum 1/d values, in units of inverse meters,
with the options --min=<n> and  --max=<n>.  The default behaviour is to use the
entire detector extent from the geometry description file,loaded with the -g flag).

You can also adjust the number of histogram bins with the option --bins=<n>,
where n is an integer.

Scaling can be set to produce linearly, quadratically or cubically spaced 1/d
values using --spacing=<type>.  Possible types of spacing are:
 linear      : linear (default)
 wilson      : even spacing in Wilson plots (quadratic)
 volume      : constant volume (cubic)

.SH DATA TYPE OPTIONS

When taking input from stream, the d-spacing for a particular intensity can be
generated in a variety of different ways.  You can choose which one with
--data=<type>.  Possible types are:

 reflection  : use peak positions from indexed reflections
 hkl         : use the Miller indicies from indexed reflections, combined
                 with a unit cell from PDB file provided with -p.
 d           : use the 1/d values in the stream for indexed reflections,
                 which were calculated at the time of indexing using the
                 unit cell for the individual crystal.  The individual
                 unit cell should be close to the actual cell, meaning
                 that this option should give a result close to "hkl".
 peaks       : use peak positions from peak search
 h5          : use all pixels in the HDF5 file, excluding bad regions

The default is "--data=d".

.SH OPTIONS FOR MORE CONTROL

 --no-sat-corr
Don't correct values of saturated peaks using the table included in the HDF5 file.
See the help for indexamajig for more information.

 --only-indexed
Use with --data=peaks or h5 if you want to use the peak list of only indexed patterns.
This is useful for finding differences between patterns which could be indexed and
those which could not.

 --no-d-scaling
Do not scale the intensities in the powder plot by d^2.  This should be used when
creating a powder plot from a reflection list.

 --ring-corr
Do not correct for the fractional area sampled of the powder ring.  This might be
useful for detectors with gaps.

 --use-redundancy
Divide intensities by the number of measurements (the redundancy column in the
reflection list), and not the number of symmetrical equivalent reflections as the
number of times a reflection occurs in the powder.