4.2 Getting Ready for MagIC.py
4.2.1 Setting up a Project Directory
PmagPy uses a number of default file names. While these can be customized by the expert user, it is preferable to keep the MagIC files for a each paleomagnetic study in separate directories. For each study, create a directory with a name that relates to that study. Here we will call it ThisProject. This directory should have NO SPACES in the name and be placed on the hard drive in a place that has NO spaces in the path. Under Windows, this means you should not use your home directory, but create a directory called for example: D:\MyPmagProjects and place ThisProject in that directory.
Inside ThisProject, create two additional directories: MyFiles and MagIC. All the files that you want to import into the MagIC format should be placed in MyFiles and you should just leave MagIC alone unless you really know what you are doing.
Your Directory tree might look like this now:
4.2.2 Field Information
Paleomagnetists collect samples in the field and record orientation, location and lithology, etc. in field notebooks. This information is necessary for placing the data into a well characterized context and should be included in the MagIC contribution. Importing field data into the MagIC format using PmagPy requires you to fill in a tab delimited text file with a particular format, here called the "orient.txt" format. These should be placed in the MyFiles directory in the Project directory. When importing the data, you must figure out how your orientation and name schemes relate to what MagIC expects. The process is difficult because there are a multitude of possible naming conventions which relate specimen to sample to site, orientation conventions which convert specimen measurements in geographic and stratigraphic coordinates, etc. PmagPy supports a number of conventions and more can be added by Request. Here we go through each of these problems, starting with the orient.txt file format, and then covering sample orientation and naming schemes.
First of all, separate your sampling information into the locations that you plan to designate in the data base. Location name (er_location_name) in MagIC is a rather loosely defined concept which groups together collections of related sites. A location could be for example a region or a stratigraphic section. Location names are useful for retrieving data out of the MagIC database, so choose your location names wisely. Each orient.txt format file contains information for a single location, so fill one out for each of your "locations".
The First Line of the orient.txt file contains two tab delimited fields. The first is the word 'tab' and the second is the location name, in this example it is North Shore Volcanics. Use the same location name EVERY TIME you are asked for it for data related to this collection of samples.
The Second Line of the orient.txt file has the column names. The order of the columns doesn't matter, but the names of the columns do. Some of these are required and others are optional. The example above shows all the REQUIRED fields. Note that latitude and longitude are specified in decimal degrees. mag_azimuth and field_dip are the notebook entries of the sample orientation. Sample class, Lithology and Type are Controlled MagIC Vocabularies, so enter colon delimited lists as appropriate. Also, notice how some fields are only entered once. The PmagPy program (orientation_magic.py) assumes that the last encountered value pertains to all subsequent blank entries.
Optional Fields in orient.txt formatted files are: [date, shadow_angle, hhmm], date, stratigraphic_height, [bedding_dip_direction, bedding_dip], [image_name, image_look, image_photographer], participants, method_codes, site_name, and site_description, GPS_Az
For Sun Compass measurements, supply the shadow_angle, date and time. The date must be in mm/dd/yy format. Be sure you know the offset to Universal Time as you will have to supply that later. Also, only put data from one time zone in a single file. The shadow angle should follow the convention shown in the figure:
All images, for example outcrop photos are supplied as a separate zip file. image_name is the name of the picture you will import, image_look is the "look direction" and image_photographer is the person who took the picture. This information will be put in a file named er_images.txt and will ultimately be read into the er_image table in the console where addiional information must be entered (keywords, etc.).
Often, paleomagnetists note when a sample orientation is suspect in the field. To indicate that a particular sample may have an uncertainty in its orientation that is greater than about 5o, enter SO-GT5 in the method_codes column and any other special codes pertaining to a particular sample from the method codes table. Other general method codes can be entered later. Note that unlike date and sample_class, the method codes entered in orient.txt pertain only to the sample on the same line.
If there is not a supported relationship between the sample_name and the site_name (see sample naming schemes below), you can enter the site name under site_name for each sample. For example, you could group samples together that should ultimately be averaged together (multiple "sites" that sampled the same field could be grouped under a single "site name" here.
Supported sample orientation schemes:
Samples are oriented in the field with a "field arrow" and measured in the laboratory with a "lab arrow". The lab arrow is the positive X direction of the right handed coordinate system of the specimen measurements. The lab and field arrows may not be the same. In the MagIC database, we require the orientation (azimuth and plunge) of the X direction of the measurements (lab arrow). Here are some popular conventions that convert the field arrow azimuth (mag_azimuth in the orient.txt file) and dip (field_dip in orient.txt) to the azimuth and plunge of the laboratory arrow (sample_azimuth and sample_dip in er_samples.txt). The two angles, mag_azimuth and field_dip are explained below.
 Standard Pomeroy convention of azimuth and hade (degrees from vertical down) of the drill direction (field arrow). sample_azimuth = mag_azimuth; sample_dip =-field_dip.
 Field arrow is the strike of the plane orthogonal to the drill direction, Field dip is the hade of the drill direction. Lab arrow azimuth = mag_azimuth-90o; Lab arrow dip = -field_dip
 Lab arrow is the same as the drill direction; hade was measured in the field. Lab arrow azimuth = mag_azimuth; Lab arrow dip = 90o-field_dip.
 Lab arrow orientation same as mag_azimuth and field_dip.
 Same as AZDIP convention explained below - azimuth and inclination of the drill direction are mag_azimuth and field_dip; lab arrow is as in  above. field arrow are lab arrow azimuth is same as mag_azimuth, Lab arrow dip = field_dip-90o
 Lab arrow azimuth = mag_azimuth-90o, Lab arrow dip = 90o-field_dip, i.e., field arrow was strike and dip of orthogonal face:
Supported sample naming conventions:
Because of the ambiguity of strike and dip, the MagIC database uses the dip direction and dip where dip is positive from 0 => 180. Dips > 90 are overturned beds. Plunging folds and multiple rotations are handled with the pmag_rotations table and are not implemented within PmagPy.
4.2.3 Measurement Data
The MagIC database is designed to accept data from a wide variety of paleomagnetic and rock magnetic experiments. Because of this the magic_measurements table is very complicated. Each measurement only makes sense in the context of what happened to the specimen before measurement and under what conditions the measurement was made (temperature, frequency, applied field, specimen orientation, etc). Also, there are many different kinds of instruments in common use, including rock magnetometers, susceptibility meters, Curie balances, vibrating sample and alternating gradient force magnetometers, and so on. We have made an effort to write translation programs for the most popular instrument and file formats and continue to add new supported formats as the opportunity arises. Here we describe the various supported data types and tell you how to prepare your files for importing. In general, all files for importing should be placed in the MyFiles directory or in subdirectories therein as needed.
Rock Magnetometer File Formats:
Supported files and how to prepare for importing:
CIT format: The CIT format is the standard format used in the paleomagnetics laboratory at CalTech and other related labs. This is the default file format used by the PaleoMag software package. This data format stores demagnetization data for individual specimens in separate sample data files. The format for these is described on the PaleoMag website. The file names with specimen data from a given site are listed in a .SAM file along with other information such as the latitude, longitude, magnetic decliantion, bedding orientation, etc. Details for the format for the .SAM files are located here. Place all the files (sample data files and summary .SAM files) in your MyFiles directory and proceed to the section on MagIC.py.
The HUJI format is the standard format used in the paleomagnetics laboratory at Hebrew University in Jerusalem.
The LDEO format is the standard format used in the paleomagnetics laboratory at Lamont Doherty Earth Observatory and other related labs. Here is an example:
The first line is the file name. The second has the latitude and longitude for the site. The third is a header file with column labels. These are: the specimen name, a treatment key, and instrument code, intensity in 10-4 emu, CDECL and CINCL which the declination and inclination in specimen (core) coordinates. Optionally, there are GDECL, GINCL which are declination and inclination in geographic coordinates, BDECL, BINCL which are in stratigraphic coordinates, SUSC which is susceptibility (in 10-6 SI). Data in this format must be separated by experiment type (alternating field demagnetization, thermal demagnetiztation). Place all data files in your MyFiles directorty and proceed to the section on MagIC.py.
The LIV-MW format is the format used for microwave data in the paleomagnetics laboratory at Liverpool.
SIO format: The SIO format has six required columns: Specimen_name Treatment_code Uncertainty Intensity Declination Inclination. These are in a space delimited file with no header.
The specimen name is assumed to have a simple relationship to the sample name using characters at the end of the specimen name. All data in a given file must have the same number of characters relating specimen to sample. For example, in the specimen name ns002a1, the terminal number is the specimen number of sample ns002a. If there are many specimens (more than 10, say), one might have a specimen ns002a01, in which case the last two characters are the specimen identifier. All data in a given file must have the same number of characters that serve as the specimen ID. The relationship of the sample name to site name can follow the sample naming convention described in the section on Field Information.
The treatment code specifies the treatment step as well as information about applied fields or even sometimes orientation during treatment (e.g., during an AARM experiment). The treatment code has the form XXX.YYY where YYY is a variable length modifier that can range from zero to three characters in length. For simple demagnetization experiments, the treatment is either the temperature (in Centigrade) to which the specimen was heated and cooled in zero field prior to measurement or the alternating field (in millitesla) to which the specimen was subjected in zero field prior to measurement.
Measurement uncertainty is the circular standard deviation of repeated measurements at the same treatment step (usually in different orientations in the magnetometer.)
Intensity is assumed to be total moment in emu (kAm2).
Declination and inclination are in specimen coordinates.
The optional meta-data string is of the form:
where: hh is in 24 hour, dC or mT units of treatment XXX (see Treatment code above) for thermal or AF respectively, xx.xxx is the DC field, UNITS is the units of the DC field (microT, mT), INST is the nstrument code, number of axes, number of positions (e.g., G34 is 2G, three axes, measured in four positions), and NMEAS is the number of measurements in a single position (1,3,200...).
Treatment codes for special experiments:
XXX.0 first zero field step
XXX.1 first in field step [XXX.0 and XXX.1 can be done in any order]
XXX.2 second in-field step at lower temperature (pTRM check)
XXX.3 second zero-field step after infield (pTRM check step)
XXX.3 MUST be done in this order [XXX.0, (optional XXX.2), XXX.1 XXX.3]
X.00 baseline step (AF in zero bias field - high peak field)
X.1 ARM step (in field step) where X is the step number in the 15 position scheme described here.
XXX.YYY XXX is temperature step of total TRM and YYY is dc field in microtesla.
The UB format is the standard format in the University of Barcelona Laboratory and is the 2G binary format. These cannot be viewed with a text editor.
The UU format is the standard format in the University of Utrecht Fort Hoofddijk Laboratory that is used by the PalMag software package.
Two University of California Santa Cruz formats are supported - the new standard and a legacy file format.
2G format: 2G Enterprises ships magnetometers with software that saves data in a binary "2G" format. Each file has the data for a given specimen and must have ".dat" or ".DAT" as a file type (e.g., Id1aa.dat).
PMD (ascii) format:There are two formats called '.PMD': an ascii file format used with the software package of Randy Enkin and a binary format. Both are used with the PaleoMac program written by J.P. Cogne. The ASCII file format is the so-called I.P.G. format described on the PaleoMaC web site. The two different file formats, so be sure you know which one you are using. Here is an example of the ascii (I.P.G., AF) file format:
The first line is a comment and the second line has: SPECIMEN a=AZIMUTH b=HADE s= STRIKE d= DIP v=VOLUME DATE TIME. The orientation information AZIMUTH and HADE are of the specimen's 'X' direction (orientation convention #1 in our convention). The third line is a header. The remaining lines are the measurement data. The first column specifies the treatment step: NRM, MXX or TXX. M steps are AF demagnetizing peak fields in mT and T steps are thermal demagnetization temperatures in oC. Columns 2-4 are the X,Y,Z data in specimen coordinates. These are in Am2. Column 5 is the volume normalized magnetization in A/m. Columns 6 and 7 are the Declination and Inclination in geographic coordinates and Columns 8 and 9 are the same in tilt corrected (stratigraphic) coordinates. There are optional columns for alpha95 and susceptibility.
ThellierTool (tdt) format: Here is an example of a TDT formatted file:
To use this option, place all .tdt files in a directory. You will be asked the usual questions about location, and naming conventions. MagIC.py copies each input file into the MagIC Project directory and generates a command to the program TDT_magic.py which creates a magic_measurements formatted file with the same name, but with a .magic extension. It writes and entry to the measurements.log file so that all the .magic files can be combined when you assemble your measurements. Note that all files in a given directory must have the same location and naming conventions.
Anisotropy of Magnetic Susceptibility File Formats:
.s format: The ".s" option allows strings of data with the format: X11 X22 X33 X12 X23 X13 where the Xii are the tensor elements (remembering that X12=X21, X23=X32 and X13=X31):
There is an optional first column with the specimen name and an optional last column with the standard deviation of the measurements (calculated with the Hext method). Here is an example of a file with the optional specimen name and standard deviation columns:
For more on how to measure AMS and calculate tensor elements, see the online textbook chapters of Essentials of Paleomagnetism.
Kly4S format: This data file format is generated by the program described by Gee, J.S., Tauxe, L., Constable, C., AMSSpin: A LabVIEW program for measuring the anisotropy of magnetic susceptibility with the Kappabridge KLY-4S, Geochem. Geophys. Geosyst., 9, Q08Y02, http://dx.doi.org/10.1029/2008GC001976, 2008. It is essentially the same as the .s format (with specimen name in the first column), but has much more information about the frequency, appied field, date and time of measurement, and so on:
k15 format: The .k15 format has the following format:
The first row for each specimen contains the specimen name, the azimuth and plunge of the measurement arrow and the strike and dip of the rock unit. The following three lines are the 15 measurement measurement scheme used with the Kappabridge instruments in static mode.
Susar 4.0 ascii format:
This format is generated by the Susar 4.0 program used for running Kappabridge instruments in spinning mode. It is the default program that comes with the instrument. Here is an example of an output file:
Hysteresis file formats:Hysteresis data can be obtained on a wide variety of instruments from vibrating sample magnetometers (VSM), alternating gradient force magnetic force magnetometers (AGFM), MPMS instruments, etc. As of now, only AGFM data from Micromag instruments are supported and only two of the many possible experiments are supported (basic hysteresis loop and "back-field" curve). These experiments have two different styles of header, the orignal and the "new". Here are some examples:
Basic hysteresis loop:This is an example of the original file format for a "basic" loop".
Back-field curve:This is an example of the original file format for a back-field curve.
New: Both of these experiments can also be saved with the "new" format. Here is an example of the "new" header: