PEARL Procedures rev-distro-1.6.0-0-gcf1399e-dirty Igor procedures for the analysis of PEARL data

- Main Page
- Related Pages
- Packages
- Namespaces
- Files

- File List
- Globals

Namespaces | Functions | Variables
pearl-anglescan-process.ipf File Reference
ARPES package

processing and holographic mapping of angle scanned XPD data. More...

`#include "pearl-vector-operations"`
`#include "pearl-polar-coordinates"`
`#include <New Polar Graphs>`

Go to the source code of this file.

## Namespaces
| PearlAnglescanProcess
| processing and holographic mapping of angle scanned XPD data.

## Functions
variable | strip_delete_frames (wave strip, variable qlo, variable qhi, wave theta, wave tilt, wave phi)
| delete a contiguous range of frames from a strip. More...
variable | normalize_strip_x (wave strip, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
| divide the strip by the average X distribution. More...
variable | normalize_strip_phi (wave strip, wave theta, wave phi, variable theta_offset=defaultValue, variable theta_range=defaultValue, variable check=defaultValue)
| divide the strip by a sine function in phi (wobble correction). More...
variable | normalize_strip_theta (wave strip, wave theta, variable theta_offset=defaultValue, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
| divide the strip by the average polar distribution. More...
variable | normalize_strip_2d (wave strip, wave theta, variable theta_offset=defaultValue, variable smooth_method=defaultValue, variable smooth_factor=defaultValue, variable check=defaultValue)
| divide the strip by a two-dimensional normalization function. More...
variable | crop_strip (wave strip, variable xlo, variable xhi)
| crop a strip at the sides. More...
variable | pizza_service (wave data, string nickname, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue, variable xpdplot=defaultValue)
| create a pizza plot from a measured (energy-integrated) data strip More...
variable | pizza_service_2 (wave data, string nickname, wave m_theta, wave m_tilt, wave m_phi, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue, variable xpdplot=defaultValue)
| create a pizza plot from a measured (energy-integrated) data strip More...
variable | show_analyser_line (variable theta, variable tilt, variable phi, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable xpdplot=defaultValue)
| calculate and display the line seen by the analyser for a specific emission angle More...
variable | convert_angles_ttpd2polar (wave theta, wave tilt, wave phi, wave data, wave polar, wave azi)
| convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates. More...
variable | convert_angles_ttpa2polar (wave theta, wave tilt, wave phi, wave analyser, wave polar, wave azi)
| convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates. More...
static variable | line_average (wave source, wave dest)
static variable | calc_nth (variable Theta_st, variable Theta_in, variable th, variable Phi_ran, variable Phi_ref, string Holomode)
| calculate the number of phis for a given theta More...
static variable | calc_phi_step (variable Theta_in, variable th, variable Theta_st, variable Phi_ran, variable Phi_ref, string Holomode)
| calculate delta-phi for a given theta More...
static variable | Calc_The_step (variable th, variable Theta_st, string Holomode)
| calculate delta-theta for a given theta More...
static variable | CalcN_Theta (string HoloMode, variable Theta_in, variable Theta_ran, variable Theta_st)
| calculate the number of thetas for a pattern More...
variable | make_hemi_grid (variable npol, string nickname, variable xpdplot=defaultValue)
| create a hemispherical, constant solid angle grid More...
string | get_hemi_nickname (wave w)
| finds the nick name given any hemi wave More...
string | get_hemi_prefix (wave w)
| finds the prefix given any hemi wave More...
dfr | find_hemi_data (string nickname, string *prefix, string *intwave)
| finds the folder, prefix and name of holo waves given their nick name More...
variable | clear_hemi_grid (string nickname)
| clear a hemispherical scan grid More...
variable | duplicate_hemi_scan (string source_nickname, dfref dest_folder, string dest_nickname, variable xpdplot=defaultValue)
| duplicate a hemispherical scan dataset. More...
variable | rotate_hemi_scan (string nickname, variable angle)
| azimuthally rotate a hemispherical scan dataset. More...
string | display_hemi_scan (string nickname, variable projection=defaultValue, variable graphtype=defaultValue, variable do_ticks=defaultValue, variable do_grids=defaultValue, string graphname=defaultValue)
| display a plot of a hemispherical angle scan. More...
static string | display_polar_graph (string graphname, variable angle_offset=defaultValue, variable do_ticks=defaultValue)
| displays an empty polar graph More...
static string | draw_hemi_axes (string graphname, variable do_grids=defaultValue)
| draw polar and azimuthal grids in an existing polar graph. More...
variable | draw_diffraction_cone (string graphname, string groupname, variable theta_axis, variable theta_inner, variable phi)
| draw the circle of a diffraction cone in a stereographic polar graph. More...
string | display_scanlines (string nickname, variable alpha_lo, variable alpha_hi, wave m_theta, wave m_tilt, wave m_phi, variable folding=defaultValue, variable projection=defaultValue)
| display a polar graph with lines indicating the angles covered by an angle scan. More...
threadsafe variable | calc_graph_radius (variable polar, variable projection=defaultValue)
| calculate the projected polar angle More...
threadsafe variable | calc_graph_polar (variable x, variable y, variable projection=defaultValue)
| calculate polar angle from Cartesian coordinate More...
threadsafe variable | calc_graph_azi (variable x, variable y, variable projection=defaultValue, variable zeroAngle=defaultValue)
| calculate azimuthal angle from Cartesian coordinate More...
static variable | update_polar_info (string graphname)
| update the angles info based on cursors A and B of a given polar graph window More...
static variable | polar_graph_hook (WMWinHookStruct *s)
| polar graph window hook More...
variable | set_polar_graph_cursor (string nickname, string cursorname, variable polar_angle, variable azim_angle, string graphname=defaultValue)
variable | hemi_add_anglescan (string nickname, wave values, wave polar, wave azi, wave weights=defaultValue)
| add an arbitrary angle scan to a hemispherical scan grid. More...
variable | hemi_add_aziscan (string nickname, wave values, variable polar, wave azi, wave weights=defaultValue)
| add an azimuthal scan to a hemispherical scan grid. More...
variable | interpolate_hemi_scan (string nickname)
| interpolate a hemispherical scan onto a rectangular grid More...
variable | quick_pizza_image (wave data, string nickname, variable theta_offset, variable tilt_offset, variable phi_offset, variable npolar=defaultValue, variable nograph=defaultValue, variable folding=defaultValue)
| map angle scan data onto a rectangular grid in stereographic projection More...
variable | save_hemi_scan (string nickname, string pathname, string filename)
| save a hemispherical scan to an Igor text file More...
variable | load_hemi_scan (string nickname, string pathname, string filename)
| load a hemispherical scan from an Igor text file More...
variable | import_tpi_scan (string nickname, wave theta, wave phi, wave intensity, variable folding=defaultValue, variable npolar=defaultValue, variable nograph=defaultValue, variable xpdplot=defaultValue)
| import a hemispherical scan from theta-phi-intensity waves and display it More...
variable | trim_hemi_scan (string nickname, variable theta_max)
| trim a hemispherical scan at grazing angle More...
wave | hemi_polar_cut (string nickname, variable azim)
| extract a polar cut from a hemispherical scan. More...
wave | hemi_azi_cut (string nickname, variable pol)
| extract an azimuthal cut from a hemispherical scan More...
static variable | check_contrast (wave values, variable pcmin, variable pcmax, variable *vmin, variable *vmax)
variable | set_contrast (variable pcmin, variable pcmax, string graphname=defaultValue, string colortable=defaultValue)
| set the pseudocolor contrast by percentile. More...

## Variables
const variable | kProjDist = 0
const variable | kProjStereo = 1
const variable | kProjArea = 2
const variable | kProjGnom = 3
const variable | kProjOrtho = 4
static const variable | kProjScaleDist = 2
static const variable | kProjScaleStereo = 2
static const variable | kProjScaleArea = 2
static const variable | kProjScaleGnom = 0.06744519021
static const variable | kProjScaleOrtho = 2

## Detailed Description

processing and holographic mapping of angle scanned XPD data.

the functions in this file map angle scanned data measured at PEARL onto a hemispherical angle grid which is compatible with XPDplot. the resulting data are in a canonical polar coordinate system (normal emission <=> polar angle = 0, azimuthal axis right-handed) which is anchored in the sample surface. the orientation of polar graphs (phi = 0 at 3 o'clock) created by this procedure corresponds to a top view of the sample surface at normal emission, and the handle of the sample plate pointing to the left (phi = 180). this is the canonical orientation of a spherical coordinate system where phi = 0 corresponds to the positive part of the x axis.

Note
  the orientation of the sample coordinate system has changed in version 1.6. the change was necessary for compatibility with other data analysis software and calculation programs.
  data imported with version 1.5 and earlier, must be offset by 180 deg in phi to be compatible with the new version. data imported and displayed by the same code version will give the same picture but with different azimuthal axis. the new graph functions shows a warning if they are applied to code imported with earlier versions.

the measurement geometry is hard-coded but may be parametrized in the future. the theta rotation axis is perpendicular to the scattering plane. the angle dispersive axis of the analyser is parallel to the theta rotation axis. the tilt rotation axis is in the scattering plane. it rotates with theta. at normal emission it is perpendicular to the axis of the lens stack of the analyser. the phi rotation axis corresponds to the surface normal of the sample. it rotates with theta and with tilt. at normal emission it is parallel to the axis of the lens stack of the analyser.

coordinate transformations: (to be revised - v1.6)

    *      theta_sample = theta_manipulator - theta_offset
    *      phi_sample = phi_manipulator - phi_offset
    *

valid for theta_manipulator = normal emission only: (to be revised - v1.6)

    *      theta_sample = | -(tilt_manipulator - tilt_offset) |
    *      phi_sample = 270 if tilt_manipulator - tilt_offset > 0
    *      phi_sample = 90 if tilt_manipulator - tilt_offset < 0
    *

Author
  matthias muntwiler, matth.nosp@m.ias..nosp@m.muntw.nosp@m.iler.nosp@m.@psi..nosp@m.ch

Copyright
  2013-17 Paul Scherrer Institut
  Licensed under the Apache License, Version 2.0 (the "License");
  you may not use this file except in compliance with the License.
  You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Version
  1.8 canonical orientation of spherical coordinate system.

Definition in file pearl-anglescan-process.ipf.

## Function Documentation

threadsafe variable calc_graph_azi | ( | variable | x,
|  | variable | y,
|  | variable | projection = `defaultValue`,
|  | variable | zeroAngle = `defaultValue`
| ) |  |

calculate azimuthal angle from Cartesian coordinate

Parameters

  x,y | projected Cartesian coordinate
  projection | mapping function from polar to cartesian coordinates. all supported projections are azimuthal, they have no effect on the azimuthal coordinate. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic
  zeroAngle | zeroAngleWhere parameter of polar graphs 0 (default) zero is at the 3 o'clock position 180 zero is at the 9 o'clock position other values not tested

Returns
  polar angle in degrees

Definition at line 2118 of file pearl-anglescan-process.ipf.

threadsafe variable calc_graph_polar | ( | variable | x,
|  | variable | y,
|  | variable | projection = `defaultValue`
| ) |  |

calculate polar angle from Cartesian coordinate

this is the reverse mapping to calc_graph_radius()

Parameters

  x,y | projected Cartesian coordinate
  projection | mapping function from polar to cartesian coordinates. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic

Returns
  polar angle in degrees

Definition at line 2065 of file pearl-anglescan-process.ipf.

threadsafe variable calc_graph_radius | ( | variable | polar,
|  | variable | projection = `defaultValue`
| ) |  |

calculate the projected polar angle

Parameters

  polar | polar angle in degrees
  projection | mapping function from polar to cartesian coordinates. see Projections for details. kProjDist = 0 azimuthal equidistant kProjStereo = 1 stereographic (default) kProjArea = 2 azimuthal equal-area kProjGnom = 3 gnomonic (0 <= polar < 90) kProjOrtho = 4 orthographic

Returns
  projected radius. the radius is scaled such that grazing emission maps to 2.

Definition at line 2020 of file pearl-anglescan-process.ipf.

static variable calc_nth | ( | variable | Theta_st,
|  | variable | Theta_in,
|  | variable | th,
|  | variable | Phi_ran,
|  | variable | Phi_ref,
|  | string | Holomode
| ) |  |
| static

calculate the number of phis for a given theta

adapted from XPDplot 8.03

Definition at line 935 of file pearl-anglescan-process.ipf.

static variable calc_phi_step | ( | variable | Theta_in,
|  | variable | th,
|  | variable | Theta_st,
|  | variable | Phi_ran,
|  | variable | Phi_ref,
|  | string | Holomode
| ) |  |
| static

calculate delta-phi for a given theta

adapted from XPDplot 8.03

Definition at line 964 of file pearl-anglescan-process.ipf.

static variable Calc_The_step | ( | variable | th,
|  | variable | Theta_st,
|  | string | Holomode
| ) |  |
| static

calculate delta-theta for a given theta

adapted from XPDplot 8.03

Definition at line 1008 of file pearl-anglescan-process.ipf.

static variable CalcN_Theta | ( | string | HoloMode,
|  | variable | Theta_in,
|  | variable | Theta_ran,
|  | variable | Theta_st
| ) |  |
| static

calculate the number of thetas for a pattern

adapted from XPDplot 8.03

Definition at line 1039 of file pearl-anglescan-process.ipf.

static variable check_contrast | ( | wave | values,
|  | variable | pcmin,
|  | variable | pcmax,
|  | variable * | vmin,
|  | variable * | vmax
| ) |  |
| static

Definition at line 2916 of file pearl-anglescan-process.ipf.

variable clear_hemi_grid | ( | string | nickname | ) |

clear a hemispherical scan grid

values and weights waves are set to zero. the intensity wave is set to NaN.

Parameters

  nickname | folder name or name prefix of holo waves. may be empty.

Definition at line 1318 of file pearl-anglescan-process.ipf.

variable convert_angles_ttpa2polar | ( | wave | theta,
|  | wave | tilt,
|  | wave | phi,
|  | wave | analyser,
|  | wave | polar,
|  | wave | azi
| ) |  |

convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates.

the angles are in the manipulator coordinate system.

Parameters

  [in] | theta | offset-corrected theta angle, normal emission = 0, grazing emission = 90. one dimensional wave.
  [in] | tilt | offset-corrected tilt angle, normal emission = 0 same dimension size and scale as theta
  [in] | phi | phi angle, range -360 < phi < +360 offset correction is optional as long as the angles lie in the accepted range. same dimension size and scale as theta
  [in] | analyser | analyser angle scale corresponding to the slices scale of Scienta. one dimensional wave. this values are constant regardless of manipulator angle.
  [out] | polar | wave to receive the polar coordinates.
  [out] | azi | wave to receive the azimuthal coordinates.

for the output parameters polar and azi, you need to pass in existing numeric waves. dimension size does not matter, the waves are redimensioned by the function so that they have the same dimensions as the intensity data set. X dimension = analyser scale, Y dimension = manipulator scan.

Definition at line 874 of file pearl-anglescan-process.ipf.

variable convert_angles_ttpd2polar | ( | wave | theta,
|  | wave | tilt,
|  | wave | phi,
|  | wave | data,
|  | wave | polar,
|  | wave | azi
| ) |  |

convert angles from TTPA (theta-tilt-phi-analyser) scheme to polar coordinates.

similar to convert_angles_ttpa2polar() but reads the analyser angles from the X scale of data

Definition at line 835 of file pearl-anglescan-process.ipf.

variable crop_strip | ( | wave | strip,
|  | variable | xlo,
|  | variable | xhi
| ) |  |

crop a strip at the sides.

the strip is cropped in place, data outside the region of interest is lost.

Parameters

  [in,out] | strip | 2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
  [in] | xlo | lowest analyser angle to keep (will be rounded to nearest existing point)
  [in] | xhi | highest analyser angle to keep (will be rounded to nearest existing point)

Remarks
  cropping should be done after smoothing and normalization operations to reduce artefacts.

Definition at line 495 of file pearl-anglescan-process.ipf.

string display_hemi_scan | ( | string | nickname,
|  | variable | projection = `defaultValue`,
|  | variable | graphtype = `defaultValue`,
|  | variable | do_ticks = `defaultValue`,
|  | variable | do_grids = `defaultValue`,
|  | string | graphname = `defaultValue`
| ) |  |

display a plot of a hemispherical angle scan.

the scan data must exist in the current data folder. azimuth = 0 should be at 9 o'clock. then the orientation is the same as the sample at normal emission and phi = 0, the handle of the sample plate pointing to the left.

Parameters

  nickname | name prefix of holo waves. may be empty.
  projection | mapping function from polar to cartesian coordinates 0 linear 1 stereographic (default) 2 azimuthal 3 gnomonic (0 <= polar < 90).
  graphtype | type of graph 1 (pol, az) trace in Igor "New Polar" (default). 2 XPDplot (reserved, not implemented). 3 matrix in Igor "New Polar". the matrix wave is a 2D wave with X and Y scaling corresponding to the selected projection. matrix waves can be created by interpolate_hemi_scan(). note: the pol and az waves are required as well.
  do_ticks | select which ticks to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 major azimuthal 2 minor azimuthal S
  do_grids | select which grids to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 radius at 0 and 90 degree azimuth 2 circle at 30 and 60 degree polar
  graphname | name of graph window. default: nickname if empty, a default name is assigned. if a window with this name is existing, the function brings it to the front, and does nothing else.

Returns
  the name of the graph window

Definition at line 1516 of file pearl-anglescan-process.ipf.

static string display_polar_graph | ( | string | graphname,
|  | variable | angle_offset = `defaultValue`,
|  | variable | do_ticks = `defaultValue`
| ) |  |
| static

displays an empty polar graph

the graph is drawn using Wavemetrics "New Polar Graphs.ipf".

initially the graph is empty. hemispherical scans are displayed by adding a trace that coveres the whole plot area, and setting the trace color to a function of the intensity. traces are added by calling WMPolarAppendTrace.

the following items of the graph > packages menu might be useful:

- modify polar graph
- color table control
- show polar cursors
- polar graph legend

parameters can be changed programmatically as shown in the code of this function. after programmatic parameter changes, call WMPolarAxesRedrawGraphNow(graphname).

Parameters

  graphname | requested name of new graph window. if empty, a default name is assigned. if a window with this name is existing, the function brings it to the front, and does nothing else.
  angle_offset | azimuth (on screen) where angle 0 is plotted (zeroAngleWhere parameter of polar graphs). starting with version 1.6, the default is 0. for hemi grids created with earlier versions, it should be set to 180 for correct orientation.
  do_ticks | select which ticks to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 major azimuthal 2 minor azimuthal

Returns
  the name of the graph window.

Version
  1.7 interface change: the trace drawing code is moved to display_hemi_scan, so that this function can be reused by other graph types, e.g. display_scanlines.

Definition at line 1654 of file pearl-anglescan-process.ipf.

string display_scanlines | ( | string | nickname,
|  | variable | alpha_lo,
|  | variable | alpha_hi,
|  | wave | m_theta,
|  | wave | m_tilt,
|  | wave | m_phi,
|  | variable | folding = `defaultValue`,
|  | variable | projection = `defaultValue`
| ) |  |

display a polar graph with lines indicating the angles covered by an angle scan.

Parameters

  nickname | nick name for output data. this will become the name of a child folder containing the output.
  alpha_lo | low limit of the analyser angle.
  alpha_hi | high limit of the analyser angle.
  m_theta | manipulator theta angles, 0 = normal emission. size = dimsize(data, 1)
  m_tilt | manipulator tilt angles, 0 = normal emission. size = dimsize(data, 1)
  m_phi | manipulator phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
  folding | rotational averaging, default = 1
  projection | mapping function from polar to cartesian coordinates. see calc_graph_radius().

Remarks
  this function is extremely slow.

Definition at line 1905 of file pearl-anglescan-process.ipf.

variable draw_diffraction_cone | ( | string | graphname,
|  | string | groupname,
|  | variable | theta_axis,
|  | variable | theta_inner,
|  | variable | phi
| ) |  |

draw the circle of a diffraction cone in a stereographic polar graph.

the diffraction cone consists of a circle marking the diffraction ring, and a dot marking the axis. the cone is drawn as a group of draw objects on the UserFront layer. the objects can be edited interactively.

Parameters

  graphname | name of graph window (not implemented yet).
  groupname | name of a drawing group. if the group exists (from a previous cone) it is replaced. if the group doesn't exist, a new one is created.
  theta_axis | polar angle of the cone axis in degrees.
  theta_inner | polar angle of the innermost point of the circle in degrees.
  phi | azimuthal angle of the cone axis in degrees.

Warning
  EXPERIMENTAL! this function is under development. the interface and behaviour of this function may change significantly in future versions.

Definition at line 1841 of file pearl-anglescan-process.ipf.

static string draw_hemi_axes | ( | string | graphname,
|  | variable | do_grids = `defaultValue`
| ) |  |
| static

draw polar and azimuthal grids in an existing polar graph.

the function adds the following draw objects to a polar graph:

- concentric circles at polar angles 0, 30, and 60 degrees with labels.
- radial axes at 0 and 90 degree azimuth.

the objects are added to the ProgFront drawing layer and will appear in front of the data trace. in interactive drawing mode, you can select the active drawing layer by clicking the tree icon while holding the Alt key.

the graph must have been created by display_polar_graph(). the function reads the projection mode from the window user data "projection".

Parameters

  graphname | name of graph window.
  do_grids | select which optional grids to draw. value must be the arithmetic OR of all selected items. default: 3 0 none 1 radius at 0 and 90 degree azimuth 2 circle at 30 and 60 degree polar

Warning
  EXPERIMENTAL! this function is under development. the interface and behaviour of this function may change significantly in future versions.

Definition at line 1769 of file pearl-anglescan-process.ipf.

variable duplicate_hemi_scan | ( | string | source_nickname,
|  | dfref | dest_folder,
|  | string | dest_nickname,
|  | variable | xpdplot = `defaultValue`
| ) |  |

duplicate a hemispherical scan dataset.

this function works only for hemi scans created by make_hemi_grid() (or compatible functions). the angle grid is recreated rather than copied point-by-point. the new dataset is independent from the original one.

if the version of the source dataset is pre 1.6, it is converted to version 1.6.

Parameters

  source_nickname | name prefix for waves. source data must be in current data folder.
  dest_folder | destination folder. folder must exist.
  dest_nickname | name prefix for destination waves. must be unique in the current data folder. otherwise existing waves get overwritten. may be empty.
  xpdplot | XPDplot compatibility 0 (default) create the data structures required by this module 1 create additional waves and notebook required by XPDplot

Definition at line 1365 of file pearl-anglescan-process.ipf.

dfr find_hemi_data | ( | string | nickname,
|  | string * | prefix,
|  | string * | intwave
| ) |  |

finds the folder, prefix and name of holo waves given their nick name

the function looks for holo waves in the following order:

1. if nickname is empty, check for prefix-less waves in current folder.
2. if nickname is the name of a child folder in the current data folder, clear the (prefix-less) waves in the child folder.
3. nickname is prefix of waves in current folder.
4. nickname is prefix of waves in root folder.

Parameters

  [in] | nickname | folder name or name prefix of holo waves. may be empty.
  [out] | prefix | name prefix of waves. may be empty.
  [out] | intwave | name of intensity/values wave

Returns
  reference of the data folder which contains the waves

Definition at line 1284 of file pearl-anglescan-process.ipf.

string get_hemi_nickname | ( | wave | w | ) |

finds the nick name given any hemi wave

the nick name is either the name of a child folder in the current data folder (PEARL specification), or a prefix of the hemi wave names (XPDplot specification).

Returns
  the nick name

Definition at line 1228 of file pearl-anglescan-process.ipf.

string get_hemi_prefix | ( | wave | w | ) |

finds the prefix given any hemi wave

the prefix is the part of the wave name before the first underscore. the prefix is used by XPDplot where it is identical to the nick name. the prefix is empty in the PEARL specification.

Returns
  the prefix

Definition at line 1253 of file pearl-anglescan-process.ipf.

variable hemi_add_anglescan | ( | string | nickname,
|  | wave | values,
|  | wave | polar,
|  | wave | azi,
|  | wave | weights = `defaultValue`
| ) |  |

add an arbitrary angle scan to a hemispherical scan grid.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. the function determines the bin size at the given polar angle, and adds all data points which fall into a bin. a point which lies exactly on the upper boundary falls into the next bin. this function does not clear previous values before adding new data. values are added to the _tot wave, weights to the _wt wave. the intensity (_i) wave is calculated as _tot / _wt.

Definition at line 2263 of file pearl-anglescan-process.ipf.

variable hemi_add_aziscan | ( | string | nickname,
|  | wave | values,
|  | variable | polar,
|  | wave | azi,
|  | wave | weights = `defaultValue`
| ) |  |

add an azimuthal scan to a hemispherical scan grid.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. the function determines the bin size at the given polar angle, and calculates the mean values of the data points which fall into a bin. a point which lies exactly on the upper boundary falls into the next bin.

Definition at line 2333 of file pearl-anglescan-process.ipf.

wave hemi_azi_cut | ( | string | nickname,
|  | variable | pol
| ) |  |

extract an azimuthal cut from a hemispherical scan

the function extracts all azimuthal angles that are present for the given polar angle.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. correct ordering is required.

Parameters

  nickname | name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
  pol | polar angle in degrees

Returns
  reference of the created wave. the wave has the same name as the intensity wave of the dataset with the suffix "_azi" and the azimuthal angle rounded to integer. it is created in the same datafolder as the original data.

Definition at line 2863 of file pearl-anglescan-process.ipf.

wave hemi_polar_cut | ( | string | nickname,
|  | variable | azim
| ) |  |

extract a polar cut from a hemispherical scan.

for each polar angle, the function first extracts all azimuthal angles. the intensity is then interpolated between the nearest neighbours of the given azimuth.

the hemi grid must have been created in the current data folder by the make_hemi_grid function. correct ordering is required.

Parameters

  nickname | name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
  azim | azimuthal angle in degrees

Returns
  reference of the created wave. the wave has the same name as the intensity wave of the dataset with the suffix "_azi" and the azimuthal angle rounded to integer. it is created in the same datafolder as the original data.

Definition at line 2777 of file pearl-anglescan-process.ipf.

variable import_tpi_scan | ( | string | nickname,
|  | wave | theta,
|  | wave | phi,
|  | wave | intensity,
|  | variable | folding = `defaultValue`,
|  | variable | npolar = `defaultValue`,
|  | variable | nograph = `defaultValue`,
|  | variable | xpdplot = `defaultValue`
| ) |  |

import a hemispherical scan from theta-phi-intensity waves and display it

in the tpi format, the hemi scan data is represented by a triple of flat one-dimensional waves corresponding to the polar angle (theta), azimuthal angle (phi) and intensity. no specific sort order is required.

Parameters

  nickname | nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
  theta | theta angles, 0 = normal emission.
  phi | phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
  intensity | intensity wave, see requirements above.
  npolar | number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
  folding | rotational averaging. example: 3 = average to 3-fold symmetry. default = 1.
  nograph | display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
  xpdplot | XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Definition at line 2689 of file pearl-anglescan-process.ipf.

variable interpolate_hemi_scan | ( | string | nickname | ) |

interpolate a hemispherical scan onto a rectangular grid

the interpolated data is written to a new two-dimensional wave "matrix". the wave has a fixed size of 181 x 181 points optimized for 1-degree polar steps.

the function requires the ster_x and ster_y waves that are created by display_hemi_scan, and thus implicitly uses the same projection.

missing values (nan) are interpolated. this works well only if the missing values are reasonable sparse. the function also applies a gaussian filter to smooth the image. empty rings at high polar angles map are preserved.

to display the result call display_hemi_scan() with graphtype=3.

Definition at line 2439 of file pearl-anglescan-process.ipf.

static variable line_average | ( | wave | source,
|  | wave | dest
| ) |  |
| static

Definition at line 917 of file pearl-anglescan-process.ipf.

variable load_hemi_scan | ( | string | nickname,
|  | string | pathname,
|  | string | filename
| ) |  |

load a hemispherical scan from an Igor text file

Todo:
  function not implemented

Definition at line 2640 of file pearl-anglescan-process.ipf.

variable make_hemi_grid | ( | variable | npol,
|  | string | nickname,
|  | variable | xpdplot = `defaultValue`
| ) |  |

create a hemispherical, constant solid angle grid

all necessary waves are created in the current data folder with step size 90 / (npol - 1)

adapted from XPDplot 8.03

Parameters

  npol | number of polar angles, determines polar and azimuthal step size. recommended 91 for 1-degree steps.
  nickname | name prefix for waves. nick name must be unique in the current data folder. otherwise existing waves get overwritten. may be empty.
  xpdplot | XPDplot compatibility 0 (default) create the data structures required by this module 1 create additional waves and notebook required by XPDplot

Definition at line 1077 of file pearl-anglescan-process.ipf.

variable normalize_strip_2d | ( | wave | strip,
|  | wave | theta,
|  | variable | theta_offset = `defaultValue`,
|  | variable | smooth_method = `defaultValue`,
|  | variable | smooth_factor = `defaultValue`,
|  | variable | check = `defaultValue`
| ) |  |

divide the strip by a two-dimensional normalization function.

Warning
  experimental. this function is under development.

Parameters

  check | enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns
  if check waves are enabled, the following waves are created (overwritten if existing):
  - check_dist average theta distribution
  - check_smoo smoothed distribution used to normalize the strip

Definition at line 435 of file pearl-anglescan-process.ipf.

variable normalize_strip_phi | ( | wave | strip,
|  | wave | theta,
|  | wave | phi,
|  | variable | theta_offset = `defaultValue`,
|  | variable | theta_range = `defaultValue`,
|  | variable | check = `defaultValue`
| ) |  |

divide the strip by a sine function in phi (wobble correction).

the sine function is a curve fit to the intensity integrated over detector angle with a period of 360.

this normalization may be useful if the intensity varies with a 360 periodicity in the azimuthal angle, e.g. due to misalignment of the surface normal and the azimuthal rotation axis of the manipulator (wobble). note, however, that this function does not correct other effects of wobble such as angle shifts.

the strip is normalized in place, previous data is overwritten.

Parameters

  [in,out] | strip | 2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
  [in] | theta | polar manipulator angle.
  [in] | phi | azimuthal manipulator angle, arbitrary offset.
  [in] | theta_offset | theta value corresponding to normal emission (default 0).
  [in] | theta_range | maximum (offset corrected) theta to consider in the sine fit (default 10).
  | check | enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns
  if check waves are enabled, the following waves are created (overwritten if existing):
  - check_dist average theta distribution
  - check_smoo smoothed distribution used to normalize the strip

Definition at line 270 of file pearl-anglescan-process.ipf.

variable normalize_strip_theta | ( | wave | strip,
|  | wave | theta,
|  | variable | theta_offset = `defaultValue`,
|  | variable | smooth_method = `defaultValue`,
|  | variable | smooth_factor = `defaultValue`,
|  | variable | check = `defaultValue`
| ) |  |

divide the strip by the average polar distribution.

this is a simple way to remove the polar angle dependence. the strip is normalized in place, previous data is overwritten.

Parameters

  [in,out] | strip | 2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
  [in] | theta | polar manipulator angle, 0 = normal emission, 90 = grazing emission
  [in] | theta_offset |
  [in] | smooth_method | smoothing method 0 none 1 binomial (requires monotonic theta), see Igor's Smooth operation 2 boxcar (requires monotonic theta), see Igor's Smooth operation 3 polynomial fit per slice 4 (default) Loess, see Igor's Loess operation caution: binomial and boxcar smoothing are not aware of theta. this may give unpredictable results if theta is non-monotonic.
  [in] | smooth_factor | smoothing parameter, depends on smooth_method binomial/boxcar: see Igor's Smooth operation loess: see Igor's Loess operation, 0 <= smooth_factor <= 1, default 0.5 polynomial fit: polynomial degree, 1 = linear (default), 2 = quadratic
  | check | enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns
  if check waves are enabled, the following waves are created (overwritten if existing):
  - check_dist average theta distribution
  - check_smoo smoothed distribution used to normalize the strip

Definition at line 353 of file pearl-anglescan-process.ipf.

variable normalize_strip_x | ( | wave | strip,
|  | variable | smooth_method = `defaultValue`,
|  | variable | smooth_factor = `defaultValue`,
|  | variable | check = `defaultValue`
| ) |  |

divide the strip by the average X distribution.

this is a simple way to remove the effect of the angle-dependence of the analyser transmission function. the strip is normalized in place, previous data is overwritten.

Parameters

  [in,out] | strip | 2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan
  [in] | smooth_method | smoothing method 0 none 1 (default) binomial, see Igor's Smooth operation 2 boxcar, see Igor's Smooth operation 3 scienta_ang_transm() function fit 4 LOESS smoothing, see Igor's Loess operation
  [in] | smooth_factor | num parameter of Igor's Smooth operation. the default value depends on smooth_method. it is 0.5 for LOESS smoothing, 2 otherwise.
  [in] | check | enable output of intermediate results 0 (default) don't create additional waves 1 create check waves in the current folder 2 calculate check waves only, do not modify strip

Returns
  if check waves are enabled, the following waves are created (overwritten if existing):
  - check_dist average X distribution
  - check_smoo smoothed distribution used to normalize the strip

Definition at line 185 of file pearl-anglescan-process.ipf.

variable pizza_service | ( | wave | data,
|  | string | nickname,
|  | variable | theta_offset,
|  | variable | tilt_offset,
|  | variable | phi_offset,
|  | variable | npolar = `defaultValue`,
|  | variable | nograph = `defaultValue`,
|  | variable | folding = `defaultValue`,
|  | variable | xpdplot = `defaultValue`
| ) |  |

create a pizza plot from a measured (energy-integrated) data strip

accepts angle-scan data as returned by adh5_load_reduced(), maps them onto a hemispherical scan grid, and displays a polar graph.

Parameters

  data | 2D intensity wave, see requirements above X-axis analyser angle Y-axis manipulator scan. no specific ordering required. manipulator angle waves (ManipulatorTheta, ManipulatorTilt, ManipulatorPhi) must be in the subfolder attr below the data wave.
  nickname | nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
  theta_offset | manipulator theta angle corresponding to normal emission. the offset is subtracted from the ManipulatorTheta wave before processing.
  tilt_offset | manipulator tilt angle corresponding to normal emission the offset is subtracted from the ManipulatorTilt wave before processing.
  phi_offset | manipulator phi angle corresponding to phi_result = 0 the offset is subtracted from the ManipulatorPhi wave before processing.
  npolar | number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
  folding | rotational averaging, default = 1
  nograph | display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
  xpdplot | XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Attention
  if you modify the structure of the data wave, e.g. delete some angles, this function cannot be used because the manipulator settings do not correspond to the original manipulator waves! instead, create your own manipulator waves and use pizza_service_2().

Definition at line 555 of file pearl-anglescan-process.ipf.

variable pizza_service_2 | ( | wave | data,
|  | string | nickname,
|  | wave | m_theta,
|  | wave | m_tilt,
|  | wave | m_phi,
|  | variable | npolar = `defaultValue`,
|  | variable | nograph = `defaultValue`,
|  | variable | folding = `defaultValue`,
|  | variable | xpdplot = `defaultValue`
| ) |  |

create a pizza plot from a measured (energy-integrated) data strip

accepts angle-scan data as returned by adh5_load_reduced(), maps them onto a hemispherical scan grid, and displays a polar graph.

the behaviour of this function is the same as pizza_service() except that the manipulator waves are specified explicitly.

Parameters

  data | 2D intensity wave, see requirements above X-axis analyser angle Y-axis manipulator scan. no specific ordering required. manipulator angle waves (ManipulatorTheta, ManipulatorTilt, ManipulatorPhi) must be in the subfolder attr below the data wave.
  nickname | nick name for output data in default mode, this will become the name of a child folder containing the output. in XPDplot mode, this will become a prefix of the generated data in the root folder.
  m_theta | manipulator theta angles, 0 = normal emission. size = dimsize(data, 1)
  m_tilt | manipulator tilt angles, 0 = normal emission. size = dimsize(data, 1)
  m_phi | manipulator phi angles, 0 = azimuthal origin. size = dimsize(data, 1)
  npolar | number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
  folding | rotational averaging, default = 1
  nograph | display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
  xpdplot | XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Definition at line 648 of file pearl-anglescan-process.ipf.

static variable polar_graph_hook | ( | WMWinHookStruct * | s | ) |
| static

polar graph window hook

this hook converts the cursor positions to polar coordinates and displays them in a text box on the graph. the text box is visible while the cursor info box is visible.

Definition at line 2198 of file pearl-anglescan-process.ipf.

variable quick_pizza_image | ( | wave | data,
|  | string | nickname,
|  | variable | theta_offset,
|  | variable | tilt_offset,
|  | variable | phi_offset,
|  | variable | npolar = `defaultValue`,
|  | variable | nograph = `defaultValue`,
|  | variable | folding = `defaultValue`
| ) |  |

map angle scan data onto a rectangular grid in stereographic projection

accepts angle-scan data as returned by adh5_load_reduced, maps them onto a rectangular grid in stereographic projection

Parameters

  data | 2D data wave, X-axis = analyser angle, Y-axis = manipulator scan (no specific ordering required)

Precondition
  manipulator angles as attributes in attr folder next to the data wave

Warning
  EXPERIMENTAL

Definition at line 2496 of file pearl-anglescan-process.ipf.

variable rotate_hemi_scan | ( | string | nickname,
|  | variable | angle
| ) |  |

azimuthally rotate a hemispherical scan dataset.

this function works only for hemi scans created by make_hemi_grid() (or compatible functions).

Parameters

  nickname | name prefix for waves. source data must be in current data folder.
  angle | azimuthal rotation angle in degrees.

Definition at line 1440 of file pearl-anglescan-process.ipf.

variable save_hemi_scan | ( | string | nickname,
|  | string | pathname,
|  | string | filename
| ) |  |

save a hemispherical scan to an Igor text file

Definition at line 2607 of file pearl-anglescan-process.ipf.

variable set_contrast | ( | variable | pcmin,
|  | variable | pcmax,
|  | string | graphname = `defaultValue`,
|  | string | colortable = `defaultValue`
| ) |  |

set the pseudocolor contrast by percentile.

set the minimum and maximum values of the pseudocolor scale such that a specified percentile of the distribution lies outside the limits.

the new contrast is applied to traces and images of the selected graph that have pseudocolor tables.

the function is not specific to angle scans. it can be used for any pseudocolor trace or image plots except contour plots.

Parameters

  pcmin | percentile below the minimum color (0-100).
  pcmax | percentile above the maximum color (0-100).
  graphname | name of graph. default: top graph.
  colortable | name of new colortable. default: keep current table.

Definition at line 2952 of file pearl-anglescan-process.ipf.

variable set_polar_graph_cursor | ( | string | nickname,
|  | string | cursorname,
|  | variable | polar_angle,
|  | variable | azim_angle,
|  | string | graphname = `defaultValue`
| ) |  |

Definition at line 2218 of file pearl-anglescan-process.ipf.

variable show_analyser_line | ( | variable | theta,
|  | variable | tilt,
|  | variable | phi,
|  | variable | theta_offset,
|  | variable | tilt_offset,
|  | variable | phi_offset,
|  | variable | npolar = `defaultValue`,
|  | variable | nograph = `defaultValue`,
|  | variable | xpdplot = `defaultValue`
| ) |  |

calculate and display the line seen by the analyser for a specific emission angle

this can be used to compare to an hemispherical plot and check the manipulator angle.

Parameters

  theta | manipulator theta angle
  tilt | manipulator tilt angle
  phi | manipulator phi angle
  theta_offset | manipulator theta angle corresponding to normal emission
  tilt_offset | manipulator tilt angle corresponding to normal emission
  phi_offset | manipulator phi angle corresponding to phi_result = 0
  npolar | number of polar angles, determines polar and azimuthal step size. default = 91 (1 degree steps)
  nograph | display a new graph window? 0 (default) display a new polar graph 1 don't display a new graph
  xpdplot | XPDplot compatibility 0 (default) create waves in child folder $nickname 1 create waves in root folder (compatible with XPDplot)

Remarks
  the function creates angle scan data under the nickname analyser.

Definition at line 765 of file pearl-anglescan-process.ipf.

variable strip_delete_frames | ( | wave | strip,
|  | variable | qlo,
|  | variable | qhi,
|  | wave | theta,
|  | wave | tilt,
|  | wave | phi
| ) |  |

delete a contiguous range of frames from a strip.

this can be used to remove a region of bad frames due to, e.g., measurement problems. the function operates on 2D intensity data and manipulator coordinates at the same time.

Parameters

  [in,out] | strip | 2D data, X-axis = analyser angle, Y-axis = arbitrary manipulator scan. the result is written to the original wave.
  [in,out] | theta | 1D data, manipulator scan. the result is written to the original wave.
  [in,out] | tilt | 1D data, manipulator scan. the result is written to the original wave.
  [in,out] | phi | 1D data, manipulator scan. the result is written to the original wave.
  [in] | qlo | point index of first frame to delete.
  [in] | qhi | point index of last frame to delete. qhi must be greater or equal than qlo.

Definition at line 105 of file pearl-anglescan-process.ipf.

variable trim_hemi_scan | ( | string | nickname,
|  | variable | theta_max
| ) |  |

trim a hemispherical scan at grazing angle

the function recalaculates the values wave from totals and weights but sets elements above a given polar angle to nan.

Parameters

  nickname | name of the scan dataset. can be empty if no prefix is used. the dataset must be in the current datafolder.
  theta_max | highest polar angle to keep (0...90 degrees).

Definition at line 2738 of file pearl-anglescan-process.ipf.

static variable update_polar_info | ( | string | graphname | ) |
| static

update the angles info based on cursors A and B of a given polar graph window

the function reads the projection mode from the user data of the graph window and the zeroAngleWhere variable from the associated WMPolarGraph data folder.

the calculated angles are written to the csrA_theta, csrA_phi, csrB_theta, and csrB_phi global variables in the polar graph data folder. the angles text box of the graph updates from to these variables dynamically.

Parameters

  graphname | name of polar graph window

Definition at line 2163 of file pearl-anglescan-process.ipf.

## Variable Documentation

const variable kProjArea = 2

Definition at line 1995 of file pearl-anglescan-process.ipf.

const variable kProjDist = 0

Definition at line 1993 of file pearl-anglescan-process.ipf.

const variable kProjGnom = 3

Definition at line 1996 of file pearl-anglescan-process.ipf.

const variable kProjOrtho = 4

Definition at line 1997 of file pearl-anglescan-process.ipf.

const variable kProjScaleArea = 2
| static

Definition at line 2001 of file pearl-anglescan-process.ipf.

const variable kProjScaleDist = 2
| static

Definition at line 1999 of file pearl-anglescan-process.ipf.

const variable kProjScaleGnom = 0.06744519021
| static

Definition at line 2003 of file pearl-anglescan-process.ipf.

const variable kProjScaleOrtho = 2
| static

Definition at line 2004 of file pearl-anglescan-process.ipf.

const variable kProjScaleStereo = 2
| static

Definition at line 2000 of file pearl-anglescan-process.ipf.

const variable kProjStereo = 1

Definition at line 1994 of file pearl-anglescan-process.ipf.