Options and parameters

PDFgetX3 is very flexible in allowing users to customize the actions of the program. It has a number of parameters that can be specified either in configuration file or as a command line options. Here is a complete description of the parameters and options used by the program.

Note

The command line options start with a leading “-” and can be only used as command line arguments when starting the pdfgetx3 program. Within configuration file the parameter names are plain words without any leading dashes. Finally, parameters can be also set in the interactive mode as attributes of the config object, but the assignments must be valid Python statements. Here are examples of setting composition of a processed specimen using each of these forms:

1. assigned in the configuration file pdfgetx3.cfg:

   ...
   composition = CaTiO3
   ...
   

2. set as a command-line option when starting pdfgetx3:

   pdfgetx3 --composition=CaTiO3
   

3. set in the IPython interactive mode:

   pdfgetx3 -i
   ...
   In [1]: config.composition = "CaTiO3"
   

Program operation

-h, --help

Display a brief usage information with a list of command line options and exit.

-V, --version

Display the program version and exit.

--manual

Open this manual in a Web browser and exit.

-f, --find

Select input files that match all filename patterns. The command line arguments are normally taken as input files. However, with the --find option the arguments are understood as filename patterns and the matching files are all used as inputs. The input files are searched in the current and datapath directories. The file search stops at the first directory that contains any matching files. The search patterns are interpreted as fixed strings, all of which must be present in the matching file name. The syntax supports several special patterns:

^	match at the beginning of the string, i.e., ^start matches only filenames that start with “start”.
$	match the end of string, for example, .chi$ matches file names that end with “.chi”.
<N>	match number N preceded by any number of leading zeros, e.g., <7> would match in “f7.chi”, “f007.chi”, but not in “f77.chi”.
<N-M>	match an integer range from N to M inclusive. The matched number may have one or more leading zeros.
<7->	match number 7 or larger.
<-7>	match number 7 or smaller.
<->	match any integer number.

The ^$<> characters are often special to the Unix or Windows command shells, therefore they need to be enclosed in double quotes (") when used on the command line.

See also datapath, PDFGETX3PATH and tutorial examples.

-l, --list

List all input files and exit. This is useful with the --find option to verify if the input files are matched as intended.

Configuration file options

-c CONFIG, --config=CONFIG

Read custom configuration file after loading the default ones. Do not load any configuration file when “NONE”.

-s NAME, --section=NAME

Load the custom configuration file section [SectionName] after loading the [DEFAULT] section. This is useful for creating several configuration variants in a single configuration file.

--createconfig=FILE

Write template configuration to a new FILE and exit. Write to the standard output when FILE is “-“.

See also the configuration file section for further details.

Input and output options

inputfile

This parameter allows to specify one or more input files in the configuration file, one file per line. The inputfile is only used if no input files were provided on the pdfgetx3 command line.

dataformat

--format=FORMAT

Format of input files. Available formats are: twotheta, QA, Qnm corresponding to a two-column text data where the first column is either the scattering angle 2Θ in degrees, Q in inverse ångströms or Q in inverse nanometers.

backgroundfile

-b FILE, --background=FILE

Optional datafile with background intensities from an empty sample holder. It must be in the same dataformat as other input files.

datapath

-d DATAPATH, --datapath=DATAPATH

One or more extra directories to be searched for input or background data files. The default path is given by the PDFGETX3PATH environment variable. The -d option can be specified several times to add more directories, these are prepended in front of any default value. Within configuration file the datapath directories have to be listed each on a separate line.

A special value “NONE” (or “none”) clears any previously defined paths and only the further paths, if any, would be searched for inputs.

output

-o OUTPUT, --output=OUTPUT

Output file name, write to the standard output when “-“. The -t, --outputtypes option controls what results are being saved. Normally the OUTPUT is used as a custom basename for the output files. The OUTPUT may contain @f, @h, @r, @e, @t, @b, @o tokens, which are expanded as follows:

token	example	definition
@h	dir1/dir2	the input file head directory or ‘.’
@r	dir1/dir2/filename	the input path with extension removed
@e	dat	the input file extension without ‘.’
@t	filename.dat	the tail component of the input file
@b	filename	the tail component with extension removed
@o	gr	the output extension iq, sq, fq or gr

An empty value works the same as “@b.@o” and saves the data in the current directory with a proper extension for the saved results. When “@o” is not present in the OUTPUT, it is appended as a default filename extension.

outputtypes

-t TYPES, --outputtypes=TYPES

Result types to be saved, one or more comma separated values. Supported values are “iq”, “sq”, “fq”, “gr”, corresponding to the I(Q), S(Q), F(Q) and G(r) curves; these are also used as output file extensions.

Result files are not written when empty, “none” or “NONE”.

force

--force=FORCE

Overwrite existing output files. By default the output files are not written if they already exist. Possible values in a configuration file are “true”, “yes”, “on”, “1” or “false”, “no”, “off”, “0” or “once”. The special value “once” permits one overwrite and then resets config.force to False. Note that in interactive mode the values assigned to config.force are converted to Python bool unless equal to “once”.

PDF parameters

wavelength

-w FLOAT, --wavelength=FLOAT

X-ray wavelength in ångströms. This value is required for the “twotheta” dataformat in order to convert the scattering angles 2Θ to a momentum transfer Q. For other data formats the wavelength is not necessary and may be left undefined.

composition

--composition=STRING

Chemical composition of the sample. Supported formats are “PbTi0.5Zr0.5O3”, “Pb 1 Ti 1/2 Zr 1/2 O 3” or “CH3 (CH2)3 OH”. Space characters are ignored, unit counts can be omitted, but it is important to use a proper upper and lower case in atom symbols. Elements can appear several times in the formula, e.g., “CH3 CH3”, and the formula may contain parentheses or fractional stoichiometries.

bgscale

--bgscale=FLOAT

Scaling of the background intensities loaded from the backgroundfile, by default 1.

rpoly

--rpoly=FLOAT

r-limit for the maximum frequency in the F(Q) correction polynomial. The PDF is unreliable at shorter r, however a very small rpoly would disable polynomial correction and give noisy PDF. Larger values produce closer fits with a higher degree polynomial, but when too large, they might smooth-out a useful signal in the data. The default is 0.9.

qmaxinst

--qmaxinst

The Q cutoff for the meaningful input intensities in inverse ångströms. Some data files may contain trailing zeros or unreliable intensities at the upper bound of the detector range. The qmaxinst defines a threshold for unreliable data. The parameter is also used as an upper boundary for the polynomial fit correction of the S(Q) data.

qmin

--qmin

The lower Q-limit for the Fourier transformation of the F(Q) curve in inverse ångströms.

qmax

--qmax

The upper Q-limit for the Fourier transformation of the F(Q) curve in inverse ångströms. This is essentially a limit, where sample signal decays to the level of data noise.

rmin

--rmin=FLOAT

Lower bound of the r-grid for the calculated PDF in ångströms.

rmax

--rmax=FLOAT

Upper bound of the r-grid for the calculated PDF in ångströms.

rstep

--rstep=FLOAT

Spacing of the r-grid for the calculated PDF in ångströms.

Other parameters

plot

-p TYPES, --plot=TYPES

Plot the specified results. A comma separated list with one or more items from “iq”, “sq”, “fq”, “gr”. No plot is produced when empty, “none” or “NONE”. Setting this option turns on the interactive mode.

interact

-i, --interact

Start an IPython interactive session after processing all files. Useful for tuning the configuration parameters or interactive plotting. This is always on when plot option has been set. See also Interactive mode for further details.

verbose

--verbose=VALUE

Level of detail for the program to report about its actions. Possible values are “error”, “warning”, “info”, “debug”, “all” or an integer number from 0 to 5. Messages are completely suppressed when 0, all messages are printed when verbose is 5 (“all”) or higher. This option is useful for diagnostics of any unexpected behavior in the program.