Feature #1646: Write documentation section: Analysis of IACT data - ctools - CTA IRAP Project Gateway

Feature #1646

Write documentation section: Analysis of IACT data

Added by Mayer Michael almost 9 years ago. Updated over 8 years ago.

Status:

Closed

Start date:

02/26/2016

Priority:

Normal

Due date:

Assigned To:

Mayer Michael

% Done:

100%

Category:

Target version:

1.1.0

Duration:

Description

For the moment, documentation of running a ctools analysis, e.g. with HESS data is internal and rather sparse.
We should add a full user documentation and step-by-step guide to run IACT data analysis. The guide should cover the following parts:

Download IACT data
Inspect IACT data options
Create observation lists (csfindobs)
Create observation XML files (csiactobs)
Create background model XML files (csiactobs)
Inspect model XML files (csmodelinfo)
Inspect observation XML files (csobsinfo)
Run ctselect and properly apply cuts (e.g energy threshold)
Correctly produce data products for stacked analysis (ctbin, ctexpcube, ctpsfcube, ctbkgcube)
Run ctlike with and without energy dispersion
Run several higher level scripts to produce output: (csspec, cslightcrv, csresmap, ctbutterfly, cttsmap, ...)
Indicate location of example plotting scripts

tableofcontents.png (88.6 KB) Mayer Michael, 02/19/2016 08:55 AM

Recurrence

No recurrence.

History

#1 Updated by Mayer Michael almost 9 years ago

File tableofcontents.png added
Assigned To set to Mayer Michael
% Done changed from 0 to 40

The documentation is being written on branch 1646-write-iact-docs.
It is progressing well. Here is a screenshot of the current table of contents. Feedback welcome

#2 Updated by Knödlseder Jürgen almost 9 years ago

This is already an impressive table of contents!

I was wondering whether you want to add a section about stacked analysis, or is this covered already by the binned analysis?

I also see that there is no section about general model fitting (e.g. determining spectral parameters of a model, or th position and size of a source).

#3 Updated by Mayer Michael almost 9 years ago

This is already an impressive table of contents!

Thanks, I believe it will simplify the users life if we give a lot of details here.

I was wondering whether you want to add a section about stacked analysis, or is this covered already by the binned analysis?

Yes, it is probably just a vocabulary thing. In my view a binned analysis is always also stacked. Therefore, in the binned analysis section, only stacked analysis is explained . I will modify the wording to call it stacked analysis.

I also see that there is no section about general model fitting (e.g. determining spectral parameters of a model, or th position and size of a source).

In the unbinned and “binned” analysis sections, I basically explain how to run ctlike. But you are right, I should probably get into more detail regarding the options in model fitting (e.g. tscalc=1). I could add a section “Create a model XML file” and link to the docs of the general models and add some information on the user options. Is that what you mean?

#4 Updated by Knödlseder Jürgen almost 9 years ago

Mayer Michael wrote:

In the unbinned and “binned” analysis sections, I basically explain how to run ctlike. But you are right, I should probably get into more detail regarding the options in model fitting (e.g. tscalc=1). I could add a section “Create a model XML file” and link to the docs of the general models and add some information on the user options. Is that what you mean?

Ok, it is fine to have the model fitting in the unbinned and binned sections. Just wanted to make sure that it’s somewhere.

#5 Updated by Mayer Michael almost 9 years ago

% Done changed from 40 to 60

#6 Updated by Mayer Michael almost 9 years ago

Status changed from New to Pull request
Target version set to 1.1.0
Start date set to 02/26/2016
% Done changed from 60 to 100

I have added all the files and filled all the sections shown above. The new documentation part is available on branch 1646-write-iact-docs.
I am happy for any feedback about it. I am sure I hid a lot of typos and errors

Note that (as always) I have also added some minor updates and improvements to some csiact-cscripts.

#7 Updated by Knödlseder Jürgen almost 9 years ago

Status changed from Pull request to Closed

I merged in the code. It’s in devel now.

I started also reading and did some minor typo corrections.

One comment I have is that some of the documentation copies quite some information from other places (for example the stacked analysis is described at http://cta.irap.omp.eu/ctools/user_manual/getting_started/beyond_stacked.html). It would be better to refer to the existing sections, and only add additional information that is necessary for IACT analysis. Otherwise we duplicate the documentation, and maintenance of the material will become difficult.

#8 Updated by Mayer Michael almost 9 years ago

I merged in the code. It’s in devel now. I started also reading and did some minor typo corrections.

Thanks for merging and correcting the typos.

One comment I have is that some of the documentation copies quite some information from other places (for example the stacked analysis is described at http://cta.irap.omp.eu/ctools/user_manual/getting_started/beyond_stacked.html). It would be better to refer to the existing sections, and only add additional information that is necessary for IACT analysis. Otherwise we duplicate the documentation, and maintenance of the material will become difficult.

I completely agree. I actually wasn’t aware of that section and just wrote down the workflow one by one. We should definitely remove that passage and link to the existing one.

#9 Updated by Knödlseder Jürgen almost 9 years ago

Okay, when I will find some time I will go over the text and modify it to reduce duplications. I will keep this in a separate branch so that you can cross check it before making it public.

#10 Updated by Knödlseder Jürgen almost 9 years ago

Status changed from Closed to In Progress
% Done changed from 100 to 80

Put this back into “In Progress”

#11 Updated by Knödlseder Jürgen over 8 years ago

Are you planning to do anything about this issue before release 1.1.0? If not I would change the target version to the next release.

#12 Updated by Mayer Michael over 8 years ago

Yes indeed, I wanted to go over the sections today and add some information about energy dispersion in stacked analysis. This seems to be related to #1811.

#13 Updated by Mayer Michael over 8 years ago

Status changed from In Progress to Pull request

I have added a section of energy dispersion in stacked IACT analysis and also improved the documentation a little bit in other places of IACT analysis.
The changes are on branch 1646-add-doc-for-iact-edisp .
It is still open to refer to the existing sections. However, I am inclined to keep it like this since users might not want to jump back and forth between documentation sections and just work through e.g. the IACT part.

In addition, I’d also like to have some more documentation about the csworkflow tool (in particular the XML format) but I guess I won’t have time before 1.1.0 for this.

#14 Updated by Knödlseder Jürgen over 8 years ago

Merged into devel.

I propose to keep it like this for the next release, but we really should simplify as much as possible the User documentation and avoid “code” duplication. It will just be a nightmare to maintain this. Already now we have a quite extended documentation code base, and we should think about how to make this slimmer, focusing on the essential things.

I was thinking for example to split the analysis page into subpages which are smaller (the page is now very long), and this would be the occasion to simply link in the ctools description. A reader could then still see this as a linearly connected text, but it would have the advantage of avoiding duplications.

#15 Updated by Knödlseder Jürgen over 8 years ago

Status changed from Pull request to Closed
% Done changed from 80 to 100

#16 Updated by Mayer Michael over 8 years ago

I have added some explanations about cstsmapsplit to the tips and tricks section. The modifications are on branch 1646-add-cstssplit-to-docs. It would be nice if this could still go in 1.1.0.

For 1.2.0, we should make an issue with a reminder to refactor the documentation (this could also be a task for the coding sprint).

#17 Updated by Knödlseder Jürgen over 8 years ago

Yes, I had planned to move this in the release. I’m still in the process to test the release procedure, now the following commands should work:

make dist
make distcheck
make installcheck

The first produces a release tarball, the second checks that tarball and the third checks an installed version of GammaLib and ctools.

#18 Updated by Mayer Michael over 8 years ago

Sounds like a great way to simplify the release procedure.

#19 Updated by Knödlseder Jürgen over 8 years ago