Package: anisoms
anisoms: a Python library for reading AMS dataIntroductionAGICO kappabridges write AMS (anisotropy of magnetic susceptibility) data in
two formats: ASC and RAN. The first is an ASCII file formatted for easy
perusal; the second is a compact binary format. Neither format is entirely
straightforward to read for further processing. anisoms provides a Python
library with functions to read and plot data from RAN and ASC files into
Python dictionaries. As well as the main libraryanisoms, the package also
contains a few short command-line scripts. These scripts demonstrate the usage
of the anisoms API, as well as being potentially useful in their own right.Documentation for anisoms is available onreadthedocs.AMS file formatsThe file formats are described in more detail in user manuals for
AGICO equipment (AGICO, 2003; AGICO, 2009).The RAN file contains a limited amount of data for each sample, most crucially
the orientation tensor. In the RAN file, this tensor is given only in the
geographic co-ordinate system (not, as might be expected, in the "raw"
specimen co-ordinate system). A RAN file is sometimes used in conjunction with
a GED ("geological data") file, which contains some additional sample data
such as orientation conventions and additional co-ordinate systems; currently,
anisoms does not read GED files.The structure of the ASC file corresponds to the format of the data displayed
on the screen during usage of the SUSAR, SUSAM, or SAFYR program, and varies
slightly according to the program version and measurement settings. The ASC
file contains a more extensive range of data than the RAN file, including
anisotropy as both tensors and principal directions, in all the co-ordinate
systems which were specified during measurement.anisoms usageThis is a brief overview; the API is fully detailed by the docstrings in
the source code andon readthedocs.The functionsread_ranandread_ascread a file of the respective types
and return a nested dictionary structure containing the data from the file.TheDirectionclass represents a direction in three-dimensional space, and
includes a method to plot itself on an equal-area plot using the pyx graphics
library.ThePrincipalDirsclass represents the three principal directions of an
anisotropy tensor. It can be initialized from the directions themselves or
from a tensor.Thedirections_from_ran,directions_from_asc_tensors, anddirections_from_asc_directionsfunctions read a data file and return a
corresponding dictionary containing aPrincipalDirsobject for each sample in
the file.Thecorrected_anisotropy_factorfunction calculates the corrected anisotropy
factor (P′orPj) (Jelínek, 1981; Hrouda, 1982).Overview of scriptsams-asc-to-csvconverts AMS data from ASC format to CSV format.ams-params-from-ascprints selected parameters from an ASC file.ams-plotplots AMS directions from ASC and RAN files.ams-print-ran-tensorreads RAN files and prints their AMS tensors.ams-tensor-to-dirprints the first principal directions of supplied tensors.More detailed documentation for the scripts is available in their
docstrings, in their output when run with a--helpargument, andon readthedocs.Precision considerationsIn the RAN file, the components of the orientation tensor are stored as
32-bit floating point numbers, which have a precision of around 7 significant
figures. In the ASC file, they are given as decimals with 5 significant figures
of precision. So, for maximal precision, the tensors should be read from the
RAN file; since the RAN file only gives tensors in the geographic co-ordinate
system, they may have to be rotated into the desired co-ordinate system after
reading.anisomscurrently focuses on data reading, and does not provide
functions for these rotations, but it does provide a function for converting
tensors to principal directions.When obtaining principal directions solely from an ASC file, the most precise
method is to read directly the directions stored there, rather than reading
the tensor and calculating directions from it. I have confirmed this by
comparing both methods with the directions calculated from the high-precision
tensor in the corresponding RAN file. The principal directions stored in the
ASC file are presumably calculated directly from the full-precision floats.
Calculating principal directions from the GED tensor is still more precise
than reading the directions from the ASC file, since the latter are rounded to
the nearest degree.LicenseCopyright 2019 Pontus Lurcock; released under theGNU General Public License,
version 3.0ReferencesAGICO, 2003.KLY-3 / KLY-3S / CS-3 / CS-L / CS-23 user’s guide, Brno, Czech
Republic: Advanced Geoscience Instruments Co.https://www.agico.com/downloads/documents/manuals/kly3-man.pdfAGICO, 2009.MFK1-FA / CS4 / CSL, MFK1-A / CS4 / CSL, MFK1-FB, MFK1-B user’s
guide4th ed., Brno, Czech Republic: Advanced Geoscience Instruments Co.https://www.agico.com/downloads/documents/manuals/mfk1-man.pdfHrouda, F., 1982. Magnetic anisotropy of rocks and its application in geology
and geophysics.Geophysical Surveys, 5, pp.37–82.Jelínek, V., 1981. Characterization of the magnetic fabric of rocks.Tectonophysics, 79, pp.T63–T67.