afps.powdRlib: Automated full pattern summation
In powdR: Full Pattern Summation of X-Ray Powder Diffraction Data

Description Usage Arguments Details Value References Examples

afps returns estimates of phase concentrations using automated full pattern summation of X-ray powder diffraction data. It is designed for high-throughput cases involving mineral quantification from large reference libraries.

## S3 method for class 'powdRlib'
afps(
  lib,
  smpl,
  harmonise,
  solver,
  obj,
  refs,
  std,
  force,
  std_conc,
  omit_std,
  closed,
  normalise,
  tth_align,
  align,
  manual_align,
  shift,
  tth_fps,
  lod,
  amorphous,
  amorphous_lod,
  weighting,
  ...
)

`lib`	A `powdRlib` object representing the reference library. Created using the `powdRlib` constructor function.
`smpl`	A data frame. First column is 2theta, second column is counts
`harmonise`	logical parameter defining whether to harmonise the `lib` and `smpl`. Default = `TRUE`. Harmonises to the intersecting 2theta range at the coarsest resolution available using natural splines.
`solver`	The optimisation routine to be used. One of `"BFGS", "Nelder-Mead", or "CG"`. Default = `"BFGS"`.
`obj`	The objective function to minimise. One of `"Delta", "R", "Rwp"`. Default = `"Rwp"`. See Chipera and Bish (2002) and page 247 of Bish and Post (1989) for definitions of these functions.
`refs`	A character string of reference pattern IDs or names from the specified library. The IDs or names supplied must be present within the `lib$phases$phase_id` or `lib$phases$phase_name` columns. If missing from the function call then all phases in the reference library will be used.
`std`	The phase ID (e.g. "QUA.1") to be used as internal standard. Must match an ID provided in the `refs` parameter.
`force`	An optional string of phase ID's or names specifying which phases should be forced to remain throughout the automated full pattern summation. The ID's or names supplied must be present within the `lib$phases$phase_id` or `lib$phases$phase_name` columns.
`std_conc`	The concentration of the internal standard (if known) in weight percent. If unknown then either omit the argument from the function call of use `std_conc = NA`, in which case it will be assumed that all phases sum to 100 percent (default).
`omit_std`	A logical parameter to be used when the `std_conc` argument is defined. When `omit_std = TRUE` the phase concentrations are recomputed to account for value supplied in `std_conc`. Default `= FALSE`.
`closed`	A logical parameter to be used when the `std_conc` argument is defined and `omit_std = TRUE`. When `closed = TRUE` the internal standard concentration is removed and the remaining phase concentrations closed to sum to 100 percent. Default `= FALSE`.
`normalise`	deprecated. Please use the `omit_std` and `closed` arguments instead.
`tth_align`	A vector defining the minimum and maximum 2theta values to be used during alignment (e.g. `c(5,65)`). If not defined, then the full range is used.
`align`	The maximum shift that is allowed during initial 2theta alignment (degrees). Default = 0.1.
`manual_align`	A logical operator denoting whether to optimise the alignment within the negative/position 2theta range defined in the `align` argument, or to use the specified value of the `align` argument for alignment of the sample to the standards. Default = `FALSE`, i.e. alignment is optimised.
`shift`	A single numeric value denoting the maximum (positive or negative) shift, in degrees 2theta, that is allowed during the shifting of selected phases. Default = 0.
`tth_fps`	A vector defining the minimum and maximum 2theta values to be used during automated full pattern summation (e.g. `c(5,65)`). If not defined, then the full range is used.
`lod`	Optional parameter used to define the limit of detection (in weight percent) of the internal standard (i.e. the phase provided in the `std` argument). The `lod` value is used to estimate the lod of other phases during the fitting process and hence remove reference patterns that are considered below detection limit. Default = 0.1. If `lod = 0` then limits of detection are not computed.
`amorphous`	A character string of any phase IDs that should be treated as amorphous. These must match phases present in `lib$phases$phase_id`.
`amorphous_lod`	Optional parameter used to exclude amorphous phases if they are below this specified limit (percent). Must be between 0 and 100. Default = 0.
`weighting`	an optional 2 column data frame specifying the 2theta values in the first column and a numeric weighting vector in the second column that specifies areas of the pattern to either emphasise (values > 1) or omit (values = 0) when minimising the objective function defined in the `obj` argument. Use this weighting parameter with caution. The default is simply a weighting vector where all values are 1, which hence has no effect on the computed objective function.
`...`	other arguments

Applies automated full pattern summation to an XRPD measurement to quantify phase concentrations. Requires a powdRlib library of reference patterns with reference intensity ratios in order to derive mineral concentrations. Details provided in Butler and Hillier (2021).

a powdRafps object with components:

`tth`	a vector of the 2theta scale of the fitted data
`fitted`	a vector of the count intensities of fitted XRPD pattern
`measured`	a vector of the count intensities of original XRPD measurement (aligned)
`residuals`	a vector of the residuals (measured minus fitted)
`phases`	a dataframe of the phases used to produce the fitted pattern
`phases_grouped`	the phases dataframe grouped and summed by phase_name
`obj`	named vector of the objective parameters summarising the quality of the fit
`weighted_pure_patterns`	a dataframe of reference patterns used to produce the fitted pattern. All patterns have been weighted according to the coefficients used in the fit
`coefficients`	a named vector of coefficients used to produce the fitted pattern
`inputs`	a list of input arguments used in the function call

Butler, B. M., Hillier, S., 2021.powdR: An R package for quantitative mineralogy using full pattern summation of X-ray powder diffraction data. Comp. Geo. 147, 104662. doi:10.1016/j.cageo.2020.104662

Bish, D.L., Post, J.E., 1989. Modern powder diffraction. Mineralogical Society of America.

Chipera, S.J., Bish, D.L., 2013. Fitting Full X-Ray Diffraction Patterns for Quantitative Analysis: A Method for Readily Quantifying Crystalline and Disordered Phases. Adv. Mater. Phys. Chem. 03, 47-53. doi:10.4236/ampc.2013.31A007

Chipera, S.J., Bish, D.L., 2002. FULLPAT: A full-pattern quantitative analysis program for X-ray powder diffraction using measured and calculated patterns. J. Appl. Crystallogr. 35, 744-749. doi:10.1107/S0021889802017405

Eberl, D.D., 2003. User's guide to RockJock - A program for determining quantitative mineralogy from powder X-ray diffraction data. Boulder, CA.

#Load the minerals library
data(minerals)

# Load the soils data
data(soils)

## Not run: 
afps_sand <-  afps(lib = minerals,
                 smpl = soils$sandstone,
                 std = "QUA.2",
                 align = 0.2,
                 lod = 0.2,
                 amorphous = "ORG",
                 amorphous_lod = 1)

afps_lime <- afps(lib = minerals,
                smpl = soils$limestone,
                std = "QUA.2",
                align = 0.2,
                lod = 0.2,
                amorphous = "ORG",
                amorphous_lod = 1)

afps_granite <- afps(lib = minerals,
                   smpl = soils$granite,
                   std = "QUA.2",
                   align = 0.2,
                   lod = 0.2,
                   amorphous = "ORG",
                   amorphous_lod = 1)

#Alternatively run all 3 at once using lapply

afps_soils <- lapply(soils, afps,
                     lib = minerals,
                     std = "QUA.2",
                     align = 0.2,
                     lod = 0.2,
                     amorphous = "ORG",
                     amorphous_lod = 1)

#Automated quantification using the rockjock library

data(rockjock)
data(rockjock_mixtures)

#This takes a few minutes to run
rockjock_a1 <- afps(lib = rockjock,
                    smpl = rockjock_mixtures$Mix1,
                    std = "CORUNDUM",
                    align = 0.3,
                    lod = 1)

#Quantifying the same sample but defining the internal standard
#concentration (also takes a few minutes to run):
rockjock_a1s <- afps(lib = rockjock,
                     smpl = rockjock_mixtures$Mix1,
                     std = "CORUNDUM",
                     std_conc = 20,
                     align = 0.3,
                     lod = 1)


## End(Not run)