Interactive Xtc with iPython

iPython has several features useful for inspecting Python objects and object hierarchies, in particular Tab completion/expansion of attributes, very handy in this case for inspecting the structure of Xtc data.

Once you've cloned the LCLS2 PSDM repository and built the executables therein, generate sample Xtc data files and inspect with iPython and psana. These notes are current as of tag Ric-180309c.

Setting Up

Switch to PSDM conda Environment

Return to the PSDM conda environment, if necessary.

# At the top of the PSDM lcls2 git repo
user@host> bash
user@host-BASH> source ./setup_env.sh
(ps-0.1.2) [user@host-BASH]$

Generate a Sample Data File

Generate a file of simple Xtc-formatted dummy data.

In the current release, this generates a 2-event data file.

# Usage: xtcwriter [-f <filename> -t -h]
(ps-0.1.2) [user@host-BASH]$ xtcwriter -f test.xtc

Create a Basic psana Data Import Script

We need a simple script, let's call it quick.py, to execute in the iPython session.

from psana import DataSource

ds = DataSource('test.xtc')

for evt in ds.events():
	pass

Inspecting Xtc Data in iPython

Start iPython and Run Import Script

1. Start iPython.

   (ps-0.1.2) [user@host-BASH]$ ipython
   
   Python 3.6.6 |Anaconda, Inc.| (default, Jun 28 2018, 17:14:51) 
   Type 'copyright', 'credits' or 'license' for more information
   IPython 6.5.0 -- An enhanced Interactive Python. Type '?' for help.
   
   In [1]:

2. Run quick.py.

   # In iPython session
   In [1]: run quick.py

Examine Data Per Event

With the import script executed, examine the events in the DataSource object. The iPython %who and %whos magic functions are useful at this stage.

1. Take a look at what's in scope.

   # In iPython session
   In [2]: %whos
   Variable     Type          Data/Info
   ------------------------------------
   DataSource   type          <class 'psana.datasource.DataSource'>
   ds           DataSource    <psana.datasource.DataSou<...>object at 0x7fa4e8838a58>
   evt          Event         <psana.event.Event object at 0x7fa4e8838ba8>

2. Query the psana DataSource object for the number of events read from the file.

   # In iPython session
   In [3]: list(ds.events())
   Out []: [<psana.event.Event at 0x7fa4d811d0f0>, <psana.event.Event at 0x7fa4d811d198>]

3. Store a couple events so we can inspect them.

   # In iPython session
   In []: ev1 = next(ds.events())
   In []: ev2 = next(ds.events())
   

4. Now use Tab completion to look at the psana representation of these events and drill down. Look at the structure inside ev1 (event1) by typing "ev1." at the console and hitting the Tab key to see a list of attributes and methods inside the ev1 object.

   # In iPython session
   In []: evt.
                evt.dgrams      evt.next        evt.replace     evt.to_bytes    
                evt.from_bytes  evt.offsets     evt.seconds                     
                evt.nanoseconds evt.position    evt.size

5. To access detector data inside this event, we'll drill down into the datagrams associated with the event.

   # In iPython session
   In []: ev1.dgrams
   Out []: [<dgram.Dgram at 0x7f73938206c0>]
   
   # evt1.dgrams is a single-item list. Store the datagram.
   In []: ev1dg1 = ev1.dgrams[0]
   In []: ev1dg1
   Out []: <dgram.Dgram at 0x7f73938206c0>

6. Continue the drill-down into ev1dg1 with "ev1dg1." and the Tab key. Now we reach attributes that look like XPP science data.

   # In iPython session
   In []: ev1dg1.
                       ev1dg1.seq      
                       ev1dg1.xppcspad 
                       ev1dg1.xpphsd