icecube.phys_services.goodrunlist module

Provides simple access in Python to the text file based Good run Lists (GRLs) for pass1 and pass2. The GRL object is just a Python dict (the keys are the run_ids). The values are dicts as well with some metadata from the GRLs and methods to get the files and other data.

Each run entry looks similar to this:

{'active_doms': 5392,
 'active_inice': 5049,
 'active_strings': 86,
 'comment': None,
 'detector': 'IC86.2017',
 'good_i3': 1,
 'good_it': 1,
 'livetime': 28808.34,
 'outdir': '/data/exp/IceCube/2017/filtered/level2/1022/Run00130150',
 'run_id': 130150}

Usage:

import goodrunlist

grl = goodrunlist.GoodRunList()

# Load one specific GRL
grl.load('/data/exp/IceCube/2011/filtered/level2/IC86_2011_GoodRunInfo.txt')

# Add another GRL
grl.load('/data/exp/IceCube/2015/filtered/level2/IC86_2015_GoodRunInfo.txt')

# Loop over all good runs:
for run in grl:
  # get L2 files of run
  l2_files = run.get_files()

  # GCD file
  gcd_file = run.get_gcd_file()

  # get all L2 files + metadata
  l2_files_meta = run.get_files_metadata()
  for f in l2_files_meta:
      filepath = f['path']

      # Livetime in seconds
      livetime_of_file = f['livetime']

      # file number aka subrun
      file_number = f['file_number']

      # Event IDs
      first_event = f['first_event']
      last_event = f['last_event']

      # Time of events (I3Time)
      first_event_time = f['first_event_time'] # Do you want a `datetime` object? f['first_event_time'].date_time
      last_event_time = f['last_event_time']

# Check if run is in GRL
if 127390 in grl:
  print('Run 127390 is a good run')
# or
if grl.has_run(127390):
  print('Run 127390 is a good run')

# Print run data
print(grl[127390])

# Exclude one run
grl.exclude_runs(127390)

# Exclude several runs:
grl.exclude_runs([127390, 127391])
grl.exclude_runs('/path/to/file.txt') # this file may only contain run ids separated by white spaces (space, newline, tab)

# Make some cuts
# Only good InIce runs
grl_good_inice = GoodRunList({k: v for k, v in grl.items() if v['good_i3']})

# Burne sample
grl_burn_samlpe = GoodRunList({k: v for k, v in grl.items() if not k % 10})
# or
grl_burn_samlpe = grl.get_burne_sample()

# IC86.2011 runs only
grl_ic86_2011 = GoodRunList({k: v for k, v in grl.items() if v['detector'] == 'IC86.2011'})

# All strings active
grl_all_strings = GoodRunList({k: v for k, v in grl.items() if v['active_strings'] == 86})

# etc....

You can also load all GRLs since IC79 (included):

import goodrunlist

# Pass1 lists/data
grl_pass1 = goodrunlist.GRL()

# Pass2 lists/data:
# IC79 - IC86.2016 will be pass2 data
grl_pass2 = goodrunlist.GRL(pass2 = True)

Now you can handle those objects the same as shown above.

icecube.phys_services.goodrunlist.GRL(pass2: bool = False, pass2a: bool = False, only_IC86: bool = False) → GoodRunList

Returns a complete list of all good runs since IC79 (included). If you enable pass2 or pass2a, the seasons IC79 - IC86.2016 will be replaced by the pass2 GRL. After IC86.2016, the standard GRLs are added (there is no pass2 after IC86.2016!).

Parameters:

• pass2 (bool, optional) – Weather or not to use pass2 instead of the old level2 for seasons before 2017. Defaults to False.

• pass2a (bool, optional) – Weather or not to use pass2a instead of the old level2 for seasons before 2017. If True, this parameter overrides the pass2 parameter. Defaults to False.

• only_IC86 (bool, optional) – If True, only IC86 seasons will be loaded. Defaults to False.

Returns:

The GoodRunList object with all seasons loaded as

specified.

Return type:

GoodRunList

icecube.phys_services.goodrunlist.GRL_pass2()

icecube.phys_services.goodrunlist.GRL_pass2a()

class icecube.phys_services.goodrunlist.GoodRunList(data={}, columns=['RunNum', 'Good_i3', 'Good_it', 'LiveTime', 'ActiveStrings', 'ActiveDoms', 'ActiveInIce', 'OutDir', 'Comment(s)'], renamed_columns=['run_id', 'good_i3', 'good_it', 'livetime', 'active_strings', 'active_doms', 'active_inice', 'outdir', 'comment'], run_id_column=0, num_decimals=2)

Bases: dict

add_run(data)

Adds a run to the GRL. Usually, you don’t need this method. It is called by the load method.

exclude_runs(arg)

Exclude certain runs from the GRL. You can pass a list of run ids, you can pass exactly one run id, or you can pass a path to a file that contains run ids separated by whitespace (space, new line, tab).

get_burne_sample()

Returns a GRL that contains burn sample runs only.

get_run(run_id)

Alias for self[run_id’].

get_run_ids(good_i3=None, good_it=None)

Returns a sorted list of good run ids.

You can also specify if InIce data needs to be good or not (same for IT data). A few examples:

Note: This method returns run ids only!

grl = GoodrunList()
grl.load(...)

# All good runs (good_i3 or good_it)
run_ids = grl.get_run_ids()

# Only good runs with good InIce (excludes good IT only runs)
run_ids = grl.get_run_ids(good_i3 = True)

# Only good runs with good IT data (excludes good InIce only runs)
run_ids = grl.get_run_ids(good_it = True)

# Only runs that are only good for InIce
run_ids = grl.get_run_ids(good_i3 = True, good_it = False)

# Only runs that are only good for IT
run_ids = grl.get_run_ids(good_i3 = False, good_it = True)

has_run(run_id)

Alias for run_id in self.

load(path)

Loads a text GRL file and adds it to the already loeaded ones. This means you can load as many files as you want.

Note: This function can handle pass1 and pass2 GRls as well as IC79 GRLs. But please do not mix pass1 and pass2 ;)

class icecube.phys_services.goodrunlist.RunInfo(data)

Bases: dict

get_date()

Tries to get the start date of this run from the path.

get_files()

Lists all L2 files of this run (IT, EHE, SLOP, ROOT, DST, etc are excluded).

The output is sorted by filename.

get_files_metadata()

Same as get_files() but with additional metadata.

Returns a list of dictionaries, sorted by file number aka sub run.

get_gcd_file()

Tries to find the GCD file of this run.

get_good_run_times_in_range(start_time, end_time)

Return a list of run ids with their good start/stop times as recorded in the i3live GRL. Be warned: this function should be used sparingly to not overload the I3Live server!

Parameters:

• start_time – a datetime instance corresponding to the start of the time window to request

• end_time – a datetime instance corresponding to the end of the time window to request

Returns:

list of bundled (run id, good start-time of run, good end-time of run) as (int, datetime, datetime) that took place between start_time and end_time

get_run_ids_in_range(start_time, end_time)

Tries to get the run ids from I3Live that are between the start_time and end_time Be warned: this function should be used sparingly to not overload the I3Live server!

Parameters:

• start_time – a datetime instance corresponding to the start of the window to request run ids from

• end_time – a datetime instance corresponding to the end of the window to request run ids from

Returns:

list of bundled (run id, start-time of run, end-time of run) as (int, datetime, datetime) that took place between start_time and end_time