Irena package for analysis of small-angle scattering data

Irena is data manipulations and analysis toolbox for small-angle scattering (SAXS, SANS, USAXS, USANS) data. It is mostly used for analysis of data in materials science, chemistry, polymers, metallurgy, physics, and other systems of typically solid or liquid samples. It addresses complex systems with size distributions, hierarchical structures, diffraction peaks, etc. Irena also contains simple X-ray and neutron reflectivity tool, for more complex systems use Motofit. Irena also provides set of tools for bioSAXS users and can utilize its own tools and gnom from ATSAS package to generate PDDF. More bioSAXS tool may be added. 

Irena requires commercial package Igor Pro from Wavemetrics, Inc.  

Current version contains main tools:

•     Unified fit
•     Modeling            - Direct modeling of SAS from up to 10 populations on up to 10 data sets at once. Selection of form factors and structure factors, Unified fit, Mass or Surface Fractal, and Diffraction peaks.
•     Size distribution - using Max. Ent., TNNLS and Regularization
•     Guinier-Porod model
•     Fractal model (combination of mass and surface fractals)
•     X-ray and Neutron reflectivity using Parrat's recursive method
•     Small-angle diffraction tool (up to 6 diffraction peaks)
•     Powder diffraction peak fitting tool (WAXS)
•     System specific models
  • Debye-Bueche,
  • Ciccariello-Benedetti,
  • Treubner-Streus models
  • Hermans, Modified Hermans, and Unified Born Green (correlated lamellae systems)
• Pair distance distribution function (PDDF, P(r))
• Hermans Orientation Parameter. See e.g., Macromolecules 2004, 37, 5327-5336, formula 1. 
•     Visualization tools    
  • Mass Fractal Aggregate - 3D Monte Carlo shape reconstruction
•     bioSAXS tools 
  • Basic/simple fits (Guinier, Porod,...)
  • PDDF/Molecular weight using GNOM and other tools. 

    Support tools

•     Data import - imports data from ASCII & XML (CanSAS XML) files
•     Data export - exports data to ASCII files
•     Data plotting tools - 2D, 3D, can create movies of plots.
•     Data manipulation tools
  • Merging of two overlapping data sets (SAXS curves from different distances etc.).
  • Subtract, scale, multiply, etc. - change data as needed.
•     Scattering contrast calculator, including anomalous effects using Croman-Liberman code
•     Desmearing using Lake method
•     Data "mining" tool, Metadata browser, etc. 
•     Scripting tool - scripts Unified fit, Modeling II, Plotting tool, and Size distribution to run automatically on multiple data sets
•     bioSAXS tools 
  • Import simple ASCII
  • Average multiple measurements
  • Subtract buffer and scale
  • Concentration extrapolation tool

For more detailed description, please see here: http://saxs-igorcodedocs.readthedocs.io/en/stable/Irena/Introduction.html

On-line manual : We now have on-line manual, you can open it in you web browser and read it here: http://saxs-igorcodedocs.readthedocs.io/

Wiki : There is now wiki for Irena and Nika packages on our Github depository. Check it up - questions of general importance may be answered there, if someone already asked them.

Mailing group for Irena users: If you want to be informed about Irena updates and possibly have place to inquire about SAXS/SANS analysis problems, visit the page: http://www.aps.anl.gov/mailman/listinfo/irena_users where you can join this group.

Workshops on using Irena & Nika packages... since 2012 we organize at the APS 1-3 sessions per year workshops on use of Irena and Nika packages. Next course will be TBA as satellite to APS users meeting, see here, to request to be put on waiting list for next workshops send e-mail to Connie.

Current version :  2.72 released 7/18/2023, 
                              July2023 release. 

Current beta version : 2.711 released 2/16/2023, February2023beta release

How to install:

Obtaining help:

•     Read manual : http://saxs-igorcodedocs.readthedocs.io/
•     Need help and understanding of Igor Pro? Check Wavemetrics youtube channel!
•     Watch Help movies. Try my Youtube channel!
•     Participate in one of the workshops
•     E-mail author a question

New for this version........:

2.72 7/16/2023

• Fixed Anomalous Contrast calculator which failed to run in old experiments due to lookup tables incompatibility. Needed proper reinitialization. 
• Fixed Guinier-Porod fitting where fitting small Q range was failing. 
• Fixes for IP9.02 where Wavemetrics changed some internal code
• Minor fixes and improvements on new tools. 

2.711 2/15/2023

• Few new tools.
• Converting to ne GUI which is easier to use with many data sets. 

2.71 10/7/2021

• Igor 9 compatible. 
• Fix All tools using the new Multi-GUI (MultiPlot, Simple Fits, bioSAXS...) to handle data with liberal names, apparently that was forgotten.  
• New tools:
  • System Specific models - this is replacement of Analytical models with new GUI. Mostly working. Needs testing and may be add more functionality. 
  • Analyze Results - new tool with new GUI for analysis of results Irena produces. For now, Size distributions. Replaced Analyze Size Distribution tool. Can be extended as needed. 
  • Data Manipulation III - WIP, not finished yet. Multi sample selection tool and ability to modify data. Can delete data (finished). 
• Simple Fits & Analysis tool - added 1D correlation model. 
• All - changed wrong spelling Ploting into correct Plotting. This may leave some windows opened on restart. 
• Fixed all fixed length wave names (hopefully). Now should use long names if user chooses so in Configuration for all waves and folders. 
• Merge data tool - fix use of long folder names. It was not following user choice on use of long names. Add merging parameters into the wave note. 
• Merge data tool - Added Optimization method: "Optimize Overlap, trim Data1" when data122 are trimmed at the very start of overlap, removing noise at overlap. 
• Unified fit - fixed fitting problem when "Link B to G/Rg/P?" was selected, code was not refreshing calculated B during fitting. Caused misfits.  
• Unified fit - set automatically k as P varies, this reduces clutter on GUI and behaves more reasonable. 
• Multi data plotting tool - added Contour plot and Waterfall plot. 
• Export data tool - add option to export SAXS/WAXS data against Q, d, or Two theta. 
• Form factor - add disk form factor with thickness as dimension. 
• Structure factor - added Distorted crystal SF. 
• ASCII export - fix export of USAXS data to ASCII which failed to export correct Q values.  
   

2.70 9/3/2020

• Require Igor 8.03 or higher. 
• DataBrowser - Igor 8 - added Buttons to display w1 vs w2 and extract info from USAXS Folder name strings. Same tools are in Igor 9 right click. 
• Added for every graph right click option to export as jpg and pxp. Also to duplicate graph (which Igor does on ctrl/cmd-D) but with duplicate of all data in the graph. 1D graphs only.   
• WAXS - changed how JCPDS cards are named (using chemical name or formula+PDF number) + enabled long name support for Igor 8 and when user chooses. 
• WAXS - added "Distance correction" for sticks. Tweaks calculated 2Theta angle using distance ratio correction.  
• Fractals - added optional use of Unified Fit Sphere form factor. This removes high-q Bessel function oscillations which are not reasonable for most cases. 
• Added Multi Data Plot tool, new tool to plot quickly many data sets. New ipf file... 
• Added Metadata Browser tool, enables relatively easy extraction of values from metadata in wave notes. 
• Added Basic fits + Simple Analysis tool, new tool and new capabilities. Guinier, Porod, Sphere and Spheroid, more to come as needed
• Added group of bioSAS tools - specialized simple import, data averaging and buffer subtraction, etc. Linked to menu also some existing tools for other functions bioSAS needs. 
• tools: Import ASCII, Average/Subtract/Scale tool, and PDDF + Molecular weight calculator. Uses ATSAS to get PDDF. 
• Added Concentration series extrapolation tool, it is BioSAXs tool. 
• Many smaller fixes. 
•  

2.69 2/9/2020

• 3D models - added new set of tools : 3DAggregate for now. 
• Due to verification issues, SAXSMorph code in release version of Irena is disabled. use Master version if you want to test the code. 
• Many tools - changed code compiler instruction to rtGLobals=3, this is less forgiving compile which prevents more accidental bugs, but may generate new errors in old code. Report as many errors as possible to author, please.  
• Scripting tool - added save individual Populations data when running from Scripting tool. 
• Added new group of Anisotropy characterization tools, first one is HOP - Hermans Orientational Parameter. 
• Unified fit added info about k value on the panel.
• Data manipulation II - fixed issues with liberal names and actually very long names. Now should create long names, if Igor 8 and user enabled it. 
• Guinier-Porod - fixed fitting of structure factor parameters. Was not working at all (forgot to include that). 
• Data picker - fixed use of root folder for data (BAD IDEA), use of weird characters in names (like [], etc=bad idea) and use of QIS data (not tested very well, do not have much test data).  
• Create QRS folder structure should now handle also QIS data. 
   

2.68  12/7/2018

• Igor 8 OSX XOPs now available. version 2.0 of 64-bit xops. 
• Removed link to pdf manual, does not exist anymore. 
• Control procedures - increases speed about twice of generating the menu strings. 
• ASCII SAS data import - improve importing of slit smeared data. 
• Unified fit - add left axis units which match units inside the Intensity wave note. 
• Size distribution, Guinier-Porod, Analytical models, SASDiffraction - add left axis units which match units inside the Intensity wave note. 
• Size distribution - add new parameters introduced in version 2.67 to wave note and arrange their saving and recovery. Somehow this was forgotten during the original work. 
• Plotting - remove CanSAS data type. Not used... 
• Plotting tool - changed the mirror size axis to show 2pi/Q and modified label to "Diameter/dimension 2pi/q [A]" 
• Modified "Configure GUI..." menu name and added warning on name shortening. Should generate dialog when names are too long and users are not using Igor 8 with long names enabled. Only once per Igor experiment.  
• Evaluate Size distributions - fixed failure with data from Modeling (II) when user used Pop1 as non-size distribution and used Size distribution in higher Pops. GUI and parameter readout failed at that situation. Checked (and fixed) for data from Modeling package - using Number of Volume distribution and using Radius or Diameter. Previously problem was with Number density of particles and Specific surface area = all worked well only for Diameters. Needed to add hooks for Radius conversion as needed... 
• Nexus export - fixed Nexus export to output files compatible with SasView (beta version for now). Should work with both desmeared and slit smeared data now. 
• Merge data - added more functionality, ability to shift in Q data 1 as well as 2, and modified graph for WAXS and SAXS display. Completely reworked optimization routines to make all more robust and easier to fix. Removed lots of ugly repetitive code. 

2.67  7/7/2018

• Igor 8.0 tested. 
• Size distribution - added power law slope to Background so one can subtract also low-q power law slope. Added buttons to perform power law fit and background fit. Added option to fit the parameters when data are added to the tool.
• Nexus exporter - changed to use 1/angstrom for Q as sasView below 4.1.2 (probably below 4.3 at least) cannot convert Q units on import. 
• Nexus Importer - fixed and modified to be able to import NXcanSAS files from DAWN and Mantid. 
• Unified fit - modified how the limits and steps are handled when user set value to 0. Fixed Uncertainty analysis in Unified fit which seems to have failed on Igor 8. 
• Created depository for user contributed form factors on Github: https://github.com/jilavsky/SAXS_IgorCode/tree/master/User%20form%20fac…

2.66 1/27/2018

• Converted all procedure files to UTF8 to prevent text encoding issues.
• Fixed Case spelling of USAXS Error data to SMR_Error and DSM_Error
• Plotting tool I - added control which enforces maximum number of items in legend (default=30). If more waves are in graph, legend gets decimated by necessary integer(2, 3, 4,...). First and last are always included. This presents selection of data names when too many data sets are used.
• MergeData - added ability to fit-extrapolate data 1 at high q end and added possibility to fit arbitrary combination of merging parameters. Lots of changes. More capable and more complicated.
• Unified Fit - added button "Copy/Swap level" which will move content of existing level to another level.
• Checked that - with reduced functionality - code will work without Github distributed xops.
• Tested and fixed for Igor 8 beta version.

2.65 11/05/2017

• Promoted required minimum version to 7.05 due to bug in Igor prior of this version.
• Panels now restore prior size and position. This is set when you drag lower-left corner to scale them up. Data stored on the user computer and size is limited to 50% width and 90% height of current screen size. Hold down any modifier key and size will be reset to original default state.
• Merge two data sets - added option of sorting qrs names by xyz_string, needed for Nika. Added SMR and DSM data to USAXS.
• Modeling - added calculation of Rg for size distributions. Requested by Dale Schaefer.
• Unified fit - changes to two phase systems requested by Dale. Added ability to handle multiple levels at the same time where possible…
• Data merging tool - modified Optimize code to prevent failures, hopefully improved fitting capabilities.
• WAXS - Added option to import free AMS diffraction data (http://rruff.geo.arizona.edu/AMS/result.php) - this database contains d, hkl, intensities for minerals.
• All packages - internal changes and improvements resulting in less and cleaner code.
• Removed pdf manual from distribution. It is obsolete, use on-line version and if needed, download pdf from the on-line source.
• Added Update Message to CheckForUpdate code. If present, it will display a message for users.

2.64, 5/1/2017

• Made Igor 7 compatible ONLY. Thanks to GeneralProcedures changes will not work on Igor 6.
• Added buttons with links to web based manual pages to each tool.
• Version check - using Github now.
• Smearing/Desmearing data support - increased smearing speed about 3x
• Unified Fit - Modified to handle Slit smeared data which do not extend beyond slit length. Same logic as in Modeling II - extend temporary data to 3*slit length and then truncate.
• Data merging - added name modifier string and defaulted to new folder name even for QRS name systems.
• Size distribution - removed limitation that Qmax > 3*slit length for slit smeared data. Optimized speed (2x improvement)
• Size distribution - fixed bug introduced in MaximumEntropy
• Fixed more slow debugging calls, few more packages see improvement in speed now.
• Completely removed Modeling I - about 2k lines of code. Moved code where needed and removed about 3 ipf files from loading.

2.63, 5/1/2017

• Version 2.62 updated with on line manuals, for Igor 6 only.

2.62

• Updated manual
• Modified Nexus support, added new library to use it.
• Moved some common functions to IN2G_GeneralProcedures
• Fix to QRS names which failed on names containing string "spec" in the name.
• Added checkbox for slit smeared/desmeared USAXS data in Merge 2 data sets tool.
• Small-angle diffraction - when user selects "oversample" the parameters for peaks (d, q, width) are now calculated at 5x higher resolution than measured Q points.
• Desmearing - propagate dQ and if does not exist, create dQ based on points distance.
• Pair Distance Distribution - changed Matrix solving method since the one used was deprecated by Igor 7.
• Plotting tool - added ability to add top 2pi/Q linked axis. Using Transform axis package from Igor Pro. Added few new styles and modified existing settings. Fixed Gizmo for Igor 7 which stopped working due to Gizmo function syntax changes.
• WAXS - removed LaueGo capability and added import of PDF-4+ xml files. Fixed help file.
• Modeling II - if you hold any modifier key (shift/ctrl/opt/alt…) while clicking on parameters change arrows, the step for next step is set 10x smaller. This enables making small changes to the values. Just keep holding the modifier key, first step is still large, subsequent are small.
• Size distribution - fixed Regularization for Igor 7, modified trust ranges which were using wrong logic. Now large size is estimated 2pi/Q while small size pi/Q.
• Fixed slow down caused by debugging messages function

Disclaimer:

This set of macros is currently being developed for use on any SAS data. Their use by anyone for open science is free of charge. If you want to use them for proprietary work, please contact me, the author, Jan Ilavsky, for permission. There are no warrantees with respect to functionality of these macros, please, verify all results by independent methods.