About csky
==========

.. contents:: :local:
   :depth: 1

Introduction
------------

**csky** is an unbinned likelihood maximization library optimized for the sorts
of analyses commonly performed by the IceCube Neutrino Sources working group.
It tries to strike a balance between flexibility and ease-of-use within that
domain.  It was originally written by Mike Richman (<mike.d.richman@gmail.com> /
@mrichman on `IceCube Slack <http://icecube-spno.slack.com>`_ / hereafter
"I/me/my/etc").

In many ways, csky is a direct response to skylab, whose wiki notes:

    The current inheritance structure is top-down which leads to a fair amount
    of copied code and makes it difficult to follow calculations all the way
    through. It would help to make the likelihood class more modular with
    individual classes for the spatial and energy components.
    -- @jwood

For how csky addresses this and other concerns, see the page on :ref:`design`.

Features
--------

Space PDFs
~~~~~~~~~~

* Single source or multi-source stacking

  - Optional source extension (circular Gaussian)
  - Optional signal subtraction

* Highly-extended source with healpy template

  - Constant spectrum per pixel
  - Energy-binned spectrum per pixel

Energy PDFs
~~~~~~~~~~~

* Fit power law (even for template analysis)
* Fix arbitrary spectrum

Time PDFs
~~~~~~~~~

* Gaussian or box flare fitting (fit peak time and/or flare width)
* Multiflare (box flares)
* *A priori* binned lightcurve
* Fast transients (fixed box or fixed box+tails)

All-sky scans
~~~~~~~~~~~~~

* Supports any single-point-like-source method
* Get full scan results
* Batch all-sky scan hottest-spot search trials
* Optional last-step source position refinement
* Optional spatial prior

Running trials
~~~~~~~~~~~~~~

* Robust sensitivity / discovery potential / upper limit estimation
* Local multi-core multiprocessing
* Optional live feedback during trial batch execution, sensitivity estimation, etc.

Data wrangling
~~~~~~~~~~~~~~

* Automatically mirror datasets
* Cache expensive PDF constructions (e.g. energy PDF ratios, smoothed templates)
* Slurp cluster outputs out of directory hierarchies (e.g. from cluster jobs)

Plotting
~~~~~~~~

* Enable TeX for all text rendering
* Skymap plotting helper
* Silence noisy healpy outputs


Name and origin
---------------

The name "csky" is a bit of a historical accident.  The library was originally
written for use with IceCube cascades.  Over time, it developed into a far more
flexible tool.  Now you can think of it as a tool with which you can "c" (read:
see) the sky (like, with neutrinos)... or something something certain parts of
it are in C++ something something.

csky is the culmination of my (@mrichman's) lessons learned on IceCube,
building on years of experience with now defunct ``grbllh`` , multiple
iterations of cascade-only analysis, and finally a couple of iterations of
multiflavor-tolerant analysis before being distilled into the current form.  I
think I've finally found a :doc:`design <design>` that is sufficiently robust
to apply to nearly every type of astrophysical neutrino source search we do.
And I hope csky will prove useful to 'cubers who outlast me.


.. _Authors:

Authors
-------

* Mike Richman <mike.d.richman@gmail.com>
* Steve Sclafani <steve.sclafani@icecube.wisc.edu>
* Paul Coppin <paul.coppin@icecube.wisc.edu>
* William Luszczak <william.luszczak@icecube.wisc.edu>


Users
-----

Known active users
~~~~~~~~~~~~~~~~~~

Known active users, listed roughly from longest to shortest time using:

* Mike Richman (original author & maintainer)

  - `Cascade 2yr PS GP <https://wiki.icecube.wisc.edu/index.php/Cascade_PS_2yr_Paper>`_
    (but csky almost entirely rewritten `since then <https://wiki.icecube.wisc.edu/index.php/GRB_precursor_search>`_)

  - `Cascade 7yr PS GP <https://wiki.icecube.wisc.edu/index.php/Cascade_7yr_PS_GP>`_
    (`paper draft <https://wiki.icecube.wisc.edu/index.php/Cascade_7yr_PS_GP_Paper>`_)

  - `PKS 1830-211 Flare Follow-up 2019 <https://wiki.icecube.wisc.edu/index.php/PKS_1830-211_Flare_Follow-up_2019>`_

* Steve Sclafani

  - `Cascade_Neutrino_Source_Dataset <https://wiki.icecube.wisc.edu/index.php/Cascade_Neutrino_Source_Dataset>`_

* Paul Coppin

  - `Neutrinos from GRB Precursors <https://wiki.icecube.wisc.edu/index.php/GRB_precursor_search>`_ (focus on GBM directional modeling)
* Devyn Rysewyk

  - `Extended Source Search <https://events.icecube.wisc.edu/event/112/contributions/6073/attachments/5170/5764/Rysewyk_ExtendedSourceAnalysis_Chiba.pdf>`_

* William Luszczak

  - `Multiflare stacking <https://wiki.icecube.wisc.edu/index.php/Multiflare_Stacking_2018>`_ (all-sky scans coming soon)

  - `PKS 1830-211 Flare Follow-up 2019 <https://wiki.icecube.wisc.edu/index.php/PKS_1830-211_Flare_Follow-up_2019>`_

* Kunal Deoskar

  - `Neutrinos from GRB Precursors <https://events.icecube.wisc.edu/event/112/contributions/6186/attachments/5148/5733/GRBs_Kunal.pdf>`_ (focus on precursor-duration fitting)

* Chujie Chen

  - `GRECO all-sky scan <https://events.icecube.wisc.edu/event/112/contributions/6138/attachments/5044/5562/Time-integrated_analysis_with_GRECO_in_csky.pdf>`_ (eventually including transient likelihood)

* Qinrui Liu

  - `Lightcurve correlation analysis <https://wiki.icecube.wisc.edu/index.php/Search_for_Neutrino_Emission_from_Binary_Sources>`_


Interested / getting started
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

People expressing interest / just getting started:

* Mirco Huennefeld

  - interested in performance benchmarking with varied reconstructions and error error estimates

* Christian Haack

  - interested in performance benchmarking with varied reconstructions and error error estimates

* Pablo Correa

  - Ultra-luminous infrared galaxy stacking

* Martina Karl

  - Self-triggered analysis

* Lisa Schumacher

  - UHECRs as spatial priors for source searches


Presentations
-------------

* 2019 Chiba LLH Developers' Workshop

  - `introduction to csky <https://events.icecube.wisc.edu/event/112/contributions/6079/attachments/5052/5572/chiba_2019_csky_mrichman_wluszczak.pdf>`_

  - `csky: Impressions from a person who is not Mike Richman <https://events.icecube.wisc.edu/event/112/contributions/6079/attachments/5052/5595/csky_impressions.pdf>`_

  - `New csky Features: Summer 2019 <https://events.icecube.wisc.edu/event/112/contributions/6080/attachments/5053/5573/llhdev_newcskyfeatures.pdf>`_


* 2019 Madison LLH Developers' Workshop

  - `introduction to csky <https://events.icecube.wisc.edu/event/106/contributions/1097/attachments/891/968/2019-04-29_mrichman_csky.pdf>`_


* 2018 Stockholm LLH Developers' Workshop

  - `Introduction to Csky <https://events.icecube.wisc.edu/event/102/contributions/760/attachments/591/628/2018-09-23_csky_intro.pdf>`_

  - `Status and Plans for Csky <https://events.icecube.wisc.edu/event/102/contributions/761/attachments/593/630/2018-09-23_csky_status_and_plans.pdf>`_