CIS Software User Guide

CIS SOFTWARE USER GUIDE

Index

Overview
Setting up cl
Promoting CIS/HIA data
Plotting CIS/HIA data with cl
Exporting CIS/HIA data from cl
Problem Report

Overview

The CIS (Cluster Ion Spectrometry) Experiment and Double Star TC-1HIA (Hot Ion Analyser) comprise ion spectrometers operating in a comparable energy range to that of PEACE. The Cluster CIS experiment was designed to include two ion sensors on each Cluster spacecraft, each for slightly different tasks. The CODIF (COmposition and DIstribution Function) sensor works best in the magneotail and provides separate measurements of H+, He+, He++ and O+ ions, whereas the HIA (Hot Ion Analyser) sensor works best on the dayside/in the solar wind. HIA does not provide mass descrimination and has a slightly smaller energy range than CODIF, however has a much better angular resolution. Further details can be found in the CIS instrument paper, here.

Unfortunately the full complement of ion sensors is not available over all four Cluster spacecraft. There is no working CIS experiment on spacecraft 2, and no working HIA sensor on spacecraft 4. Additionally, CODIF on spacecraft 3 seems to exhibit a Vz problem and CESR recommend that from 2004 onwards CODIF on spacecraft 1 is to be used only with caution. To summarise, use CODIF on spacecraft 4 and HIA on spacecraft 1 & 3 wherever possible.

The only European ion instrument flying on either of the Double Star spacecraft is an HIA sensor on board TC-1.

It is always advisable to check both the general data caveats for the instruments and any specific data caveats for a particular event.

Data caveats for Cluster CIS are found here.

Data caveats for TC1-HIA are found here.

The software provided by CESR, Toulouse, to plot and export Cluster CIS and Double Star HIA data is known as "cl". At MSSL cl is available for use on the shared computers, msslaa/ab/ac, and on self-adminstered linux desktops through msslwm (usually mounted to /usr/local/plasma). Setup and use of the cl software is slightly different depending on which system you are using.

The installed version of cl is currently 7.06

top

Setting up cl

Setting up cl for use on the shared computers is very simple.

Log in to msslaa/ab/ac.
If it isn't already there, add the following line to your .tcshrc file (located in your home directory):
```
source /soft/soft3/plasma-Linux/tcsh-plasma
```
You also need a copy of the cl.cfg file which tells the software where all of the data it needs is stored, copy this file from my (apw's) home space:
```
 cp /disk/home/apw/cl.cfg ~/ 
```
Log out and re log in to msslab or type the following the command prompt:
```
 source ~/.tcshrc
```
Run cl by typing "cl" at the command prompt.

Setting up cl for use on your own self-administered linux machine is slightly less simple, but still easy enough.

Open a terminal window.
If it isn't already there, add the following line to your .tcshrc file (located in your home directory):
```
source /usr/local/plasma/tcsh-generic
```
Next you need to set up directories for storage of the CIS/HIA data, as long as the directory heirarchy remains the same (CIS/DATA/L1 etc) the root data directory can technically be anywhere, but so you don't have to maintain your own copy of the data promotion scripts, using the locations specified below is easiest (you'll probably need to be logged in as root to do this). I am assuming that you already have a local sddas data directory located at /home/sddas/data, if not just create it in a similar way to that described below.
1. For Cluster:
```
mkdir /home/sddas/data/CIS
```
```
mkdir /home/sddas/data/CIS/DATA
```
```
mkdir /home/sddas/data/CIS/DATA/L1
```
```
mkdir /home/sddas/data/CIS/DATA/L2
```
```
mkdir /home/sddas/data/CIS/DATA/L3
```
2. For Double Star:
```
mkdir /home/sddas/data/HIA
```
```
mkdir /home/sddas/data/HIA/DATA
```
```
mkdir /home/sddas/data/HIA/DATA/L1D
```
```
mkdir /home/sddas/data/HIA/DATA/L2
```
```
mkdir /home/sddas/data/HIA/DATA/L3
```

Make sure all uses have read and write access to the data directories:

For Cluster:

chmod -R a+r /home/sddas/data/CIS

chmod -R a+w /home/sddas/data/CIS

For Double Star:

chmod -R a+r /home/sddas/data/HIA

chmod -R a+w /home/sddas/data/HIA

Next create a symbolic link so that the promotion scripts can find the data directories (if you've set up sddas for use with PEACE data this might have already been done):
```
ln -s /home/sddas /sddas
```

In order for cl to calculate pitch angles correctly, it needs access to prime parameter cdf files, so next you need to create some directories and links to the locations of these files on the SAN, again you will probably need root access to do this:

For Cluster:

mkdir /home/sddas/data/CIS/CDF

mkdir /home/sddas/data/CIS/CDF/FGM

cd /home/sddas/data/CIS/CDF/FGM

ln -s /disk/peace9/other_data/cluster/csds_pp/FGM/C1 CLUSTER1

ln -s /disk/peace9/other_data/cluster/csds_pp/FGM/C2 CLUSTER2

ln -s /disk/peace9/other_data/cluster/csds_pp/FGM/C3 CLUSTER3

ln -s /disk/peace9/other_data/cluster/csds_pp/FGM/C4 CLUSTER4

For Double Star:

mkdir /home/sddas/data/HIA/CDF

cd /home/sddas/data/HIA/CDF

ln -s /disk/peace9/other_data/doublestar/dsds_pp/FGM/T1 FGM

Copy the cl.cfg file to your home space.
```
cp /usr/local/plasma/CIS/cl.cfg ~/ 
```
Run cl by typing "cl" at the command prompt.
If you have kept the directory paths the same then everything should now work, if not you'll need to change the data loactions in the cl general preferences window (the one that pops up at the start). In the "Parameter for Experiment" drop down box select CLUSTER, CDF_CLUSTER, DSP and DSP_CDF and ensure that LOCAL is selected and the path matches the location of your data directories.

top

Promoting CIS/HIA Data for use With cl

In order to do anything with the CIS/HIA data in cl, you need to get them from the servers at CESR. We have some scripts that use wget to make this easier. The use of these scripts is exactly the same whether you are running the software on your own linux machine or on msslaa/ab/ac. The data are stored for different days individually, and are quite large so we don't generally keep a copy of the entire CESR database locally. This means you'll have to individually promote data for each day that you are interested in.

To promote Cluster CIS data type:
```
promote_cis yyyymmdd
```
Where yyyymmdd is the date you are studying. This will get all of the available CODIF and HIA data for each spacecraft.
Similarly, to promote TC-1 HIA data type:
```
promote_hia yyyymmdd
```

At present, data is not deleted regularly from the shared data area (msslab users), however this may change, so if you think you have promoted some data and it isn't there, check the contents of /disk/peace1/other_data/cluster/CIS/DATA/L{1-3}/yyyymmdd, in case it has been deleted to make some space. You are responsible for the maintainance of any data directories on your self-administered linux machine. You might come accross errors regarding permissions while promoting data, ignore these, they shouldn't impact the data promotion process.

top

Plotting CIS/HIA Data With cl

While it is possible to create custom plots using cl, this is a fairly unintuitive process and is best discovered through experimenting with the software. Thankfully there are several pre-defined plot layouts that cover some of the more common uses of the CIS data to get you started. Note you can set a default time range in the general properties on starting cl or individually for each plot layout you load. I'll be assuming that the time range is always set in the general properties.

Calculating Moments With cl

cl can calculate either ground based moments or plot onboard moments for both CODIF (for each species) and HIA. The Cluster HIA moments can be calculated for high and low sensitivity modes, so if you're expecting HIA moments to be there and they don't plot on the first attempt, check the HIA mode panel on the plot to see if you've chosen the correct mode.

To Calculate moments:

Promote the data for the day you are interested in (see above).
Run cl.
In the 'General Preferences' window that appears select the date/time and spacecraft that you want.
Select the moments product you want to plot from the menus, For example:
```
ADD -> CLUSTER -> MOMENTS3D -> moments3d_h1
```
For 3d, ground-calculated proton moments from CODIF.
If you chose the correct time/spacecraft in the general preferences then select 'Use Defaults' otherwise choose a new time/spacecraft.
All being well you should see a screen like this:

Calculated Moments

Things to Note When Calculating and Using CIS Moments

Check the caveats for your event.
It is best to use 3D moments for CODIF and on board moments for HIA.
High velocities, particularly when the spacecraft are in the PSBL, can often be field aligned beams rather than bulk flows. Calculating vperp or looking at the wheel plots (see below) will help distinguish between these.
Velocities, temperatures etc. can be unreliable when in a region of low plasma density, check the number density or spectrogram if you think something odd might be going on.
Often when 3D CODIF moments look 'spiky', it is because of a compression artefact in the data. You can check for this by looking for a red dashed line in the spectrogram. Changing the minimum energy of the moments calculation to 30eV will get around this problem.

To Change the moments integration range go to:
```
EDIT -> PREFERENCES
```
click the 'Data' button and in the moments area change Emin to 30.

Ion Pitch Angle Plots

cl can plot pitch angle spectrograms for both CODIF and HIA on Cluster and HIA on TC-1. HIA works better because of its superior angular resolution.

Promote your data and run cl.
Select the pitch angle distribution product you want.
```
 ADD -> CLUSTER -> PAD -> pad_hia_high
```
Use the default times/spacecraft or change them.
You should end up with a plot like this:
By default, cl uses the processing support magnetic field dataset to calculate pitch angles. This is unvalidated so it is best to use the prime parameters instead.
Right click on the pitch angle spectrogram to bring up the plot properties.
Click the 'Data' button and change the magnetic field resolution from '1 sec' to '4 sec'.
If the plot goes blank, then the paths to the FGM prime parameters are probably not set correctly, check the CDF_CLUSTER or DSP_CDF variables in general preferences as described above.

Wheel Plots

cl can also plot the ion distributions as wheel plots, there is a complex set of options for plotting these and making them look good (I haven't quite mastered it yet), but it's easy enough to use them to browse the distributions.

Promote your data and load cl.
Choose your time range.
Select the product you want. NB it's a bad idea to choose the 'multi' option unless you've specified a very small time range, otherwise the cl window will become overloaded with plots. I normally use 'distributions_XXXXXX'.
```
ADD -> CLUSTER -> SPIN -> DISTRIBUTIONS -> distributions_hia_high_g
```
This will plot first distribution in your time range, you can cylce backward and forward in time using the <-TIME and TIME-> buttons on the right of the cl window.
The default is to plot the distributions in terms of Vx, Vy, Vx GSE. I find the Vpar/Vperp plots more useful.
Right click on one of the columns of distributions to bring up the plot properties.
Change the 'nb spectro' slider to 3 so 3 spectrograms will be plotted in the column
Select spectrogram 1 in the 'spectro' list and change the distribution in the dropdown box to '2D Vperp1 Vpar'.
Select speactogram 2 in the 'spectro' list and change the distribution in the dropdown box to '2D Vperp1 Vperp2'.
Select speactogram 3 in the 'spectro' list and change the distribution in the dropdown box to '2D Vpar Vperp'.
This should give you a plot that lloks a bit like this.
To neaten things up, you can delete the other plots by clicking on them and clicking the 'X' in the blue box that appears around them.

Multi-Spacecraft Plots

HIA Multi-Spacecraft

The look directions plotted for HIA are, in this order, SUN DUSK TAIL DAWN ALL. Note that these are look directions, not plasma flow directions, so a higher flux of ions in the TAIL panel than the SUN panel could mean a net motion of ions in the Sunward direction rather than the Tailward direction.

To obtain a multi-spacecraft plot:

Promote your data and load cl.
Select your time range in the general properties and make sure the default spacecraft is set to none, otherwise multiple copies of one spacecraft's data will be plotted.
choose the product you want from the menus:
```
ADD -> CLUSTER -> SC -> hia_sc13
```

Changing Plot Properties

To change the spacecraft simply click the sc button on the right hand side. This will affect al of the panels of the plot.
To change the time range of a plot click the T1T2 button on the right hand side. This will also affect all of the panels of the plot.
To change other plot properites (energy ranges, units, etc) right click on the panel in question to bring up the properties window, it probably best to leave any of the panels to the left of 'X' alone.
To change spectrogram units, right click a spectrogram, click the data button and change the cjf dropdown box. I have no idea about the different varieties of counts on offer, but as far as I can tell the science units are as follows (though please feel free to correct me if you think I've got these mixed up).
1. JE = Differential Energy Flux
2. fdist = phase space density
To change the Y range of a plot, right click the plot, click the Y button, change the Y range to manual, and input your desired range.
There are many other small changes you can make to plots using the various pages of the properties menu.

Saving/Printing Plots

You can save a cl plot layout to work on later by choosing SAVE from the file menu. this will create a file with the extention .cl.
To save a plot as an image choose PRINT from the file menu and pick your desired image format.
Printing directly from within cl is currently not supported, instead save your plot as a postscript and print that as you would normally.

top

Exporting CIS/HIA Data From cl

While cl is quite good for processing and plotting CIS and HIA data, it isn't ideal for comparing that data with the FGM magnetic field (our Hi-Res data, especially) and does not support PEACE data at all. Fortunately it is possible to export ion data from cl as ascii files that are based on the cef (Cluster Exchange Format) and cdf files, readable by QSAS and idl.

Exporting Vector Time Series From cl

Check the object number of the quantity you want to export (e.g. velocity) by left clicking on the plot. The object number is displayed at the top of the blue box.
Choose either ascii or cdf export from the file menu. A dialogue box will appear asking which object you want to export, choose the object(s) with same number(s) as in the blue box.
If exporting to ascii, you'll also need to choose a time format, value delimiter, and header location.
Click ok to export the data. A file named objX.cdf (or .asc) will be placed in your working directory, where X is the object number selected.
Note that the cdf files created for vector series (e.g. velocity) export each component as a separate variable. You can use the makeVectorXYZ plugin for QSAS to turn it into a proper vector time series and add the frame attribute so QSAS can run calculations on it.

Exporting Spectrograms From cl

Find out the number of the panel you want to export and export it to ascii as for a vector time series.
Leave the time, header, and delimiter settings as they are.
Files named something like this will be saved to your working directory:
```
obj5_Panel01_CIS1_P23_SC1_H1.asc
```
Quit cl (or open a new terminal and navigate to your working directory).
Convert the .asc file to a cdf by entering the following at the command prompt:
```
cistran [infile] [outfile]
```
i.e.
```
cistran obj5_Panel01_CIS1_P23_SC1_H1.asc obj5_Panel01_CIS1_P23_SC1_H1
```
The '.cdf' will be added automatically.
You will be told which data product the file contains and asked if you want to continue.
Note that for some reason the data product in the file name does not always match the one in the file contents, you can check if the file contains the correct data product by putting your mouse over the spectrogram in cl and looking at the titlebar of the window.
It is normally worth converting all of the files even if the product does not match, and plotting them in QSAS to see which looks sensible.
The output cdf files are designed to have a similar structure as those output from Steve Schwartz's QPEACE software, and as such you should be able to plot the spectrograms in QSAS without too much difficulty.

MSSL Only

CIS SOFTWARE USER GUIDE