.. include:: <isogrk1.txt>
.. index:: file-formats
.. _file-formats:

Short description and references to the supported file-formats
==============================================================

Currently the following |mgr|\SR and non-|mgr|\SR file formats are supported (in alphabetic order):

* ascii (non-|mgr|\SR): :ref:`ASCII file format for non-u\SR <ascii-file-format>`
* db (non-|mgr|\SR): :ref:`DB (triumf) <db-file-format>`
* dat (non-|mgr|\SR): :ref:`DAT: CSV like data file <dat-file-format>`
* mdu (|mgr|\SR): :ref:`MDU file format (PSI) <mdu-file-format>`
* mud (|mgr|\SR): :ref:`MUon Data access file format (TRIUMF) <mud-file-format>`
* musr-root (|mgr|\SR): :ref:`MusrRoot - an Extensible Open File Format for uSR <MusrRoot>`
* nexus (|mgr|\SR): used to read NeXus files from ISIS (HDF4 and HDF5): :ref:`NeXus <nexus-file-format>`
* psi-bin (|mgr|\SR): :ref:`PSI-BIN file format (PSI) <psi-bin-file-format>`
* root (|mgr|\SR): specific version for LEM before 2012 :ref:`LEM ROOT file format<root-file-format>`
* wkm (|mgr|\SR): special ascii file format used in the past by the TU Braunschweig (outdated): :ref:`WKM <wkm-file-format>`
  
.. index:: ascii-file-format
.. _ascii-file-format:

ASCII file format for non-|mgr|\SR
----------------------------------

This for instance can be used to fit :math:`1/\lambda^2 ~ \mathrm{vs} ~ T` to study gap properties of superconductors.
Details about the gap-intergrals can be found in the memo *GapIntegrals.pdf* which can be found in the source code of musrfit
under <musrfit-home-dir>/src/external/libGapIntegrals.

This primitive file format has the following structure:

Comment lines start with a '#' or '%' character.
The file can start with some header info. The header is optional, as all its tags, but 
if present it has the following format:

::

  HEADER
  TITLE:  title
  X-AXIS-TITLE: x-axis title
  Y-AXIS-TITLE: y-axis title
  SETUP:  setup
  FIELD:  field
  TEMP:   temperature
  ENERGY: energy

Field has to be given in (G), temperature in (K) and energy in (keV).

The data are read column like and start with the data tag DATA, followed by the
data columns, i.e.:

::

  DATA
  x, y [, error y]

where spaces, column, are a tab are possible separations.
If no error in y is present, the weighting in the fit will be equal.

A full example might look like this:

::

  # libGapIntegrals-test.dat
  # This is a comment
  % This as well
  HEADER
  TITLE: Test superconductor data
  X-AXIS-TITLE: T (K)
  Y-AXIS-TITLE: #lambda^{-2} (#mum^{-2})
  SETUP: H #parallel c
  FIELD: 100
  TEMP: 0.0
  ENERGY: 4200
  # here the data will follow
  DATA
  # x, y, error y
  0.0318411, 7.77455, 0.2
  0.0629929, 7.9869, 0.15
  0.113914, 7.64209, 0.15
  0.202492, 7.37699, 0.15
  0.302725, 7.70893, 0.12
  0.447456, 7.77565, 0.12
  0.611685, 7.45768, 0.12
  0.813613, 7.19287, 0.12
  1.00822, 7.57813, 0.12
  1.24793, 7.31343, 0.12
  1.50635, 7.16818, 0.12
  1.74591, 6.99634, 0.12
  1.99795, 6.90414, 0.12
  2.25061, 6.41393, 0.12
  2.4958, 6.66666, 0.12
  2.75514, 5.93766, 0.12
  3.00753, 5.61992, 0.12
  3.26056, 4.89091, 0.12
  3.49414, 4.52005, 0.08
  3.75356, 3.73799, 0.08
  3.99425, 2.84974, 0.08
  4.30518, 1.35139, 0.08


.. index:: db-file-format
.. _db-file-format:

DB file format for non-|mgr|\SR
-------------------------------

The DB file format is an *archaic* ascii file format from TRIUMF which is intended to be used to collect parameter summaries of various runs, which can be read directly by :ref:`mupp <mupp>`.

The DB file is organized in a couple of tags defining various properties, followed by the parameter data with its errors.
Tags and is content are always separated by an empty line.
The first tag is the **TITLE**. Followed by the title in the next line

::
  
  TITLE
  This is the best data ever

The next tag is the **ABSTRACT**, followed a potentially multi-line abstract, e.g.

::

  ABSTRACT
  Here comes the detailed description ...

The next tag, **LABELS**, are used to define human readable names for the data parameters to be followed:

::

  LABELS
  T (K)
  B (G)
  ...

The number of labels have to fit the number of parameters present!

The next tag is **DATA**, which is a list of the parameter names as found in you msr-file.
Unlike the other tags, here the list of names follow directly after the **DATA** tag

::

  DATA dataT dataB dataE dataTr ...

Next there will be a line with the tag **\\\\-e**, followed by

The parameters are afterwards listed as

::

  param-name = val, pos-err, neg-err,\

After all the parameters listed of a specific run, the **run number** with the run title ends a run data set.
This might look like this (be aware of the comma!):

::

  11231,,, AgPlate 250nm (T5034), T=200.00 K, E=12.99 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00

A full example might look like this:

::

  TITLE
  Ag Plate 2023 runs, Tr12kV, E=13keV, TF B=50G

  Abstract
  Summary of the

  LABELS
  T (K)
  B (G)
  Implantation Energy (keV)
  Transport (kV)
  RAL-RAR (kV)
  RAT-RAB (kV)
  Spin Rotation Angle (degree)
  Asy
  Lambda
  Ph
  Field
  RelPh_L
  N0_L
  N_bkg_L
  RelPh_T
  N0_T
  N_bkg_T
  RelPh_R
  alpha_LR
  N_bkg_R
  RelPh_B
  alpha_TB
  N_bkg_B
  maxLH
  NDF
  maxLHred
  RUN

  Data dataT dataB dataE dataTr dataRALRAR dataRATRAB dataSpinRot Asy Lambda Ph Field RelPh_L N0_L N_bkg_L RelPh_T N0_T N_bkg_T RelPh_R alpha_LR N_bkg_R RelPh_B alpha_TB N_bkg_B maxLH NDF maxLHred RUN
  \-e
  dataT = 200.001, 0.0009, 0.0009,\
  dataB = 49.49, 0, 0,\
  dataE = 12.9952, 0, 0,\
  dataTr = 11.9993, 0, 0,\
  dataRALRAR = -0.008, 0, 0,\
  dataRATRAB = -0.009, 0, 0,\
  dataSpinRot = -10, 0, 0,\
  Asy = 0.22466, 0.00084, -0.00084,\
  Lambda = 0.0081, 0.0014, -0.0014,\
  Ph = 12.14, 0.32, -0.32,\
  Field = 50.837, 0.017, -0.017,\
  RelPh_L = 0, 0, 0,\
  N0_L = 430.67, 0.39, -0.39,\
  N_bkg_L = 6.81, 0.048, -0.048,\
  RelPh_T = -89.95, 0.4, -0.4,\
  N0_T = 422.6, 0.37, -0.37,\
  N_bkg_T = 7.125, 0.047, -0.048,\
  RelPh_R = -178.55, 0.39, -0.39,\
  alpha_LR = 0.9729, 0.0012, -0.0012,\
  N_bkg_R = 7.375, 0.048, -0.048,\
  RelPh_B = 90.38, 0.4, -0.4,\
  alpha_TB = 0.9522, 0.0012, -0.0012,\
  N_bkg_B = 6.546, 0.047, -0.047,\
  maxLH = 20303.3, 0, 0,\
  NDF = 20361, 0, 0,\
  maxLHred = 0.997166, 0, 0,\
  11231,,, AgPlate 250nm (T5034), T=200.00 K, E=12.99 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00
  dataT = 153, 0.7, 0.7,\
  dataB = 49.49, 0, 0,\
  dataE = 12.9952, 0, 0,\
  dataTr = 11.9993, 0, 0,\
  dataRALRAR = -0.008, 0, 0,\
  dataRATRAB = -0.009, 0, 0,\
  dataSpinRot = -10, 0, 0,\
  Asy = 0.22253, 0.00084, -0.00083,\
  Lambda = 0.0055, 0.0014, -0.0014,\
  Ph = 11.53, 0.32, -0.32,\
  Field = 51.026, 0.017, -0.017,\
  RelPh_L = 0, 0, 0,\
  N0_L = 430.31, 0.39, -0.39,\
  N_bkg_L = 6.762, 0.048, -0.048,\
  RelPh_T = -89.3, 0.4, -0.4,\
  N0_T = 422.31, 0.37, -0.37,\
  N_bkg_T = 6.96, 0.047, -0.047,\
  RelPh_R = -178.61, 0.4, -0.4,\
  alpha_LR = 0.975, 0.0013, -0.0012,\
  N_bkg_R = 7.361, 0.048, -0.048,\
  RelPh_B = 90.24, 0.4, -0.4,\
  alpha_TB = 0.9605, 0.0012, -0.0012,\
  N_bkg_B = 6.623, 0.047, -0.047,\
  maxLH = 20435.6, 0, 0,\
  NDF = 20361, 0, 0,\
  maxLHred = 1.00366, 0, 0,\
  11235,,, AgPlate 250nm (T5034), T=151.72 K, E=13.00 keV, B=~50(G)/8.65(A), Tr/Sa=12.00/-1.80 kV, SR=-10.00
  >> here many more run data would follow ...

.. index:: dat-file-format
.. _dat-file-format:

DAT: CSV like file format for non-|mgr|\SR
------------------------------------------

This is typically used when exporting the parameter data from **msr2data** to be used in **mupp**, gnuplot, origin, or whatever parameter plotter you might use.
The first line defines the parameter tags separated by spaces or tabs. If errors are available there are labeled be the ending *Err*.
This is followed by the parameter values and its errors if present. A fill example looks like this:

::

  dataT        dataTErr        dataB        dataE        dataTr       dataRALRAR   dataRATRAB   dataSpinRot  Asy          AsyPosErr          AsyNegErr          Lambda       LambdaPosErr       LambdaNegErr       Ph           PhPosErr           PhNegErr           Field        FieldPosErr        FieldNegErr        RelPh_L      RelPh_LPosErr      RelPh_LNegErr      N0_L         N0_LPosErr         N0_LNegErr         N_bkg_L      N_bkg_LPosErr      N_bkg_LNegErr      RelPh_T      RelPh_TPosErr      RelPh_TNegErr      N0_T         N0_TPosErr         N0_TNegErr         N_bkg_T      N_bkg_TPosErr      N_bkg_TNegErr      RelPh_R      RelPh_RPosErr      RelPh_RNegErr      alpha_LR     alpha_LRPosErr     alpha_LRNegErr     N_bkg_R      N_bkg_RPosErr      N_bkg_RNegErr      RelPh_B      RelPh_BPosErr      RelPh_BNegErr      alpha_TB     alpha_TBPosErr     alpha_TBNegErr     N_bkg_B      N_bkg_BPosErr      N_bkg_BNegErr      maxLH        NDF          maxLHred     RUN          
  200          0.007           99.48        1.11754      10.001       -0.008       -0.008       -10          0.1587        0.0012        0.0012        0.0263        0.003         0.003         29.85         0.64          0.64          101.179       0.035         0.035         0             0             0             219.27        0.27          0.27          2.676         0.033         0.033         -89.79        0.81          0.81          210.42        0.26          0.26          2.723         0.032         0.032         -179.73       0.81          0.81          0.9808        0.0017        0.0017        2.993         0.033         0.033         90.05         0.82          0.82          0.9755        0.0017        0.0017        2.501         0.032         0.032         20444.8      20361        1.00412      11400        
  200          0.009           99.49        2.11668      10.001       -0.008       -0.008       -10          0.1732        0.0012        0.0012        0.0096        0.0025        0.0026        28.88         0.57          0.57          101.231       0.03          0.03          0             0             0             219.86        0.27          0.27          2.749         0.033         0.033         -88.87        0.71          0.71          211.47        0.26          0.26          2.791         0.032         0.032         -178.48       0.72          0.71          0.9678        0.0017        0.0017        2.969         0.033         0.033         90.94         0.73          0.73          0.9608        0.0017        0.0017        2.653         0.032         0.032         20182.5      20361        0.991233     11401        


.. index:: mdu-file-format
.. _mdu-file-format:

MDU file format (psi) for |mgr|\SR
----------------------------------

For details about the PSI-BIN/MDU file format from PSI see `Class_MuSR_PSI <http://lmu.web.psi.ch/docu/manuals/bulk_manuals/software/Class_MuSR_PSI/index.html>`_

.. index:: mud-file-format
.. _mud-file-format:

MUD file format (triumf) for |mgr|\SR
-------------------------------------

For details about the MUD file format from triumf see `MUon Data access <https://cmms.triumf.ca/mud/>`_ .

.. _musr-root-file-format:

MusrRoot file format (PSI) for |mgr|\SR
---------------------------------------

For details see :ref:`MusrRoot - an Extensible Open File Format for uSR <MusrRoot>`. 

.. index:: nexus-file-format
.. _nexus-file-format:

NeXus file format (isis) for |mgr|\SR
-------------------------------------

For details about the NeXus file format from ISIS (UK) see `The application of the NeXus data format to ISIS muon data <https://doi.org/10.1016/S0921-4526(02)01613-7>`_ . For a detailed list of available meta information and data see `NeXus Instrument Definitions for ISIS muon Data <https://www.isis.stfc.ac.uk/Pages/nexus-definition-v27924.pdf>`_ .

.. index:: psi-bin-file-format
.. _psi-bin-file-format:

PSI-BIN file format (psi) for |mgr|\SR
--------------------------------------

For details about the PSI-BIN/MDU file format from PSI see `Class_MuSR_PSI <http://lmu.web.psi.ch/docu/manuals/bulk_manuals/software/Class_MuSR_PSI/index.html>`_.


.. index:: root-file-format
.. _root-file-format:

ROOT file format (psi/lem before 2012) for |mgr|\SR
---------------------------------------------------

For details about the API of ROOT files can be here: `ROOT files <https://root.cern/manual/root_files/>`_.
The structure of the ROOT files (LEM, before 2012) looks like this:

::

  ROOT-file --|
              |-- histos ---|
              |             |-- DecayAnaModule
              |             |-- PileUpAnaModule
              |             |-- ScalerSumRate
              |             |-- SCAnaModule
              |
              |-- RunInfo --|
                            |-- RunSummary

``histos``, ``RunInfo``, ``DecayAnaModule``, ``PileUpAnaModule``, ``ScalerSumRate``, ``SCAnaModule`` are **TFolder** objects.

The ``DecayAnaModule`` object holds the positron spectra

::
  
  DecayAnaModule --|
                   |-- hDecay00
                   |-- hDecay01
                   |-- hDecay02
                   |-- hDecay03
                   |-- hDecay20
                   |-- hDecay21
                   |-- hDecay22
                   |-- hDecay23

The ``hDecayXX`` files or **TH1F** objects containing the positron spectra of the LEM detectors.

The detectors (00, 01, 02, and 03) are the detectors (Left, Top, Right, Bottom). These are non-post-pileup (NPP) histograms.

The detectors (20, 21, 22, and 23) are the detectors (Left, Top, Right, Bottom). These are post-pileup-corrected (PPC) histograms.

The ``SCAnaModule`` contains various **TF1H** objects of slow control data of the run.

The ``RunSummary`` is essentially an ascii dump, with summary information of the run.


.. index:: wkm-file-format
.. _wkm-file-format:

WKM file format for |mgr|\SR
----------------------------

WKM is an obsolete ascii file format, originally introduced by people from the TU Braunschweig.
It starts with a header which shows like this:

::

  - WKM data file converted with any2many
  NEMU_Run:            2466
  nemu_Run:            ./2466.wkm
  Date:                13:22:00 2012-06-03 / 14:04:38 2012-06-03
  Title:               LSCO x=0.02 (224-227), T=12.00 (K), E=5.57 keV, WEW B=~49(G)/8.62(A), Tr=15.02 (kV), Sample=8.70 (kV), SpinRot -10
  Field:               49.11
  Setup:               Sample, WEW, LowTemp-2
  Temp:                11.999
  TOF(M3S1):           nocut
  Groups:              8
  Channels:            66601
  Resolution:          0.0001953125

The header ends with an empty line.

The data are stored as following: there are always 10 bin-counts per line.
Between detectors, there will be an empty line.
