modeleditor.txt

NAME

    ModelEditor - Create and edit XML model files

USAGE

    ModelEditor (infile)

DESCRIPTION

    This program allows the user to create model files for use as input to
    the Fermi likelihood estimation program. The model files are XML
    files, and thus plain text, but the format is moderately complex, and
    must be followed precisely. This program eases that process by
    allowing the user to concentrate on correct data input, leaving the
    task of proper data formatting to the program. This program also
    provides limited capability to convert likelihood model files to the
    format required by the Fermi observation simulator, which uses a
    different XML format for model files.

    The user will typically use ModelEditor to prepare a file of source
    models for input the the Fermi likelihood estimator. This is a
    critical step in the analysis of Fermi data, and is an iterative
    process. Once the user has prepared a model file, the likelihood
    program computes the likelihood that this particular set of models can
    give rise to the observed data. The model parameters are then adjusted
    until a high-likelihood scenario is found.

    Screen controls

    N.B.: Context-sensitive help is available for all on-screen
    controls. Moving the mouse over any screen element will invoke a popup
    balloon containing a capsule summary of the function of that screen
    element.

    Source selection box

        This box on the left side of the window contains a scrolling list of
        sources in the current model file. Each source is identified by a
        unique name. When a source is selected by clicking on its name in the
        list box, the parameters for that source are used to populate the
        editor on the right side of the window. Most of those parameters may
        then be edited. When a source is selected in the list box, the
        Source/Remove Source menu item may be selected to remove that source
        from the list of sources.

        Title entry

        This entry field displays the title of the collection of sources in
        the current file. Note that this is not the same as the name of the
        file. The user may edit this title by editing the contents of the
        title entry field.

        Source Name entry

        This entry field displays the name of the currently selected source in
        the source selection box. The user may edit this name by editing the
        contents of the Source Name entry field.

        Source Type label

        This (fixed) label displays the current source type: PointSource or
        DiffuseSource. It is not editable by the user.

        Spectrum Type menu button

        This popup button displays the type of spectrum used for this
        source. A new spectrum type may be selected by pressing the popup
        button, and selecting one of the displayed spectrum types. When a new
        spectrum type is selected, the parameters displayed in the spectrum
        parameter grid immediately below the spectrum type button are updated
        to reflect the new spectrum type, using all default values. The
        different spectrum types are described in the documentation for the
        likelihood tool (gtlike), so please refer to that document for more
        information.

        (Spectrum) File entry

        This field displays the path to a data file used by the spectrum. This
        field is only used by the FileFunction spectrum type. For other
        spectrum types, this field is deactivated. When active, the user may
        edit the path by editing the contents of this entry field.

        (Spectrum) Browse button

        This button summons a standard file dialog allowing the user to browse
        to a file to use for the current FileFunction spectrum. This file
        dialog functions in the standard "file/open" fashion for whichever
        platform the ModelEditor is running on. This provides a convenient
        alternative to editing the text in the adjacent file entry field.

        (Spectrum) Parameter Editor grid

        This grid contains 7 rows and six columns. Each row corresponds to one
        parameter which characterizes the current spectrum, and each column
        corresponds to one of the 6 attributes of the parameter (name, value,
        scale, min, max, free). The name column contains the name of the
        current parameter, and this field may be freely edited (but the
        likelihood code will probably not behave correctly if you change the
        parameter names). The value column contains the unscaled value of the
        parameter, and the scale column contains the scale factor for the
        parameter. The product value*scale is the actual quantity used by the
        likelihood software. The min and max columns display the allowed
        minimum and maximum values for the value column (the unscaled
        values). These fields are "live"; changing the value field
        automatically invokes a range check using the min and max fields, and
        the user is prevented from entering bad or out-of-range values. If the
        user wishes to enter a value outside of the current range, the min
        and/or max fields should be edited prior to editing the value
        field. The final column (free) contains checkboxes. When a checkbox is
        checked, that parameter is marked as adjustable by the likelihood
        code, and will be modified to provide the best likelihood
        estimate. The value specified in the value field is used as the
        starting value for that parameter for the computation.

        SpatialModel Type menu button

        This popup button displays the type of spatial model used for this
        source. A new spatial model type may be selected by pressing the popup
        button, and selecting one of the displayed spatial model types. When a
        new spatial model type is selected, the parameters displayed in the
        spectrum parameter grid immediately below the spatial model type
        button are updated to reflect the new spatial model type, using all
        default values.

        (Spatial Model) File entry

        This field displays the path to a data file used by the spatial
        model. This field is only used by the SpatialMap and MapCubeFunction
        spatial model types. For other spatial model types, this field is
        deactivated. When active, the user may edit the path by editing the
        contents of this entry field.

        (Spatial Model) Browse button

        This button summons a standard file dialog allowing the user to browse
        to a file to use for the current SpatialMap or MapCubeFunction spatial
        model. This file dialog functions in the standard "file/open" fashion
        for whichever platform the ModelEditor is running on. This provides a
        convenient alternative to editing the text in the adjacent file entry
        field.

        (Spatial Model) Parameter Editor grid

        This grid contains 7 rows and six columns. Each row corresponds to one
        parameter which characterizes the current spatial model, and each
        column corresponds to one of the 6 attributes of the parameter (name,
        value, scale, min, max, free). The name column contains the name of
        the current parameter, and this field may be freely edited (but the
        likelihood code will probably not behave correctly if you change the
        parameter names). The value column contains the unscaled value of the
        parameter, and the scale column contains the scale factor for the
        parameter. The product value*scale is the actual quantity used by the
        likelihood software. The min and max columns display the allowed
        minimum and maximum values for the value column (the unscaled
        values). These fields are "live"; changing the value field
        automatically invokes a range check using the min and max fields, and
        the user is prevented from entering bad or out-of-range values. If the
        user wishes to enter a value outside of the current range, the min
        and/or max fields should be edited prior to editing the value
        field. The final column (free) contains checkboxes. When a checkbox is
        checked, that parameter is marked as adjustable by the likelihood
        code, and will be modified to provide the best likelihood
        estimate. The value specified in the value field is used as the
        starting value for that parameter for the computation.

    Menu commands

        File menu

        New

        Create a new default model document and use it to populate the
        editor. If the current document has been changed, the user is prompted
        to save the changes before the new document is created.

        Open...

        Summon a standard file open dialog to allow the user to select a file
        to load into the editor. If the user presses the Cancel button in the
        dialog, the new file is not loaded, and the current document is
        retained.

        Close

        Close the current document and create a new default document. If the
        current document has been changed, the user is prompted to save the
        changes before closing the document. This is functionally equivalent
        to the New command (for now).

        Save

        Save the current document under its existing name. If the current
        document has no name, the user is prompted for a name using a standard
        file/save dialog.

        Save As...

        Save the current document under a new name. A standard file/save
        dialog is summoned to allow the user to specify the path to the saved
        file.

        Export to ObsSim...

        Convert the current model file to a format usable by the Fermi
        observation simulator. Note that this capability is experimental -
        only PowerLaw, PowerLaw2, BrokenPowerLaw, and BrokenPowerLaw2 spectrum
        types are supported for the conversion, and only SkyDirFunction
        spatial models are supported. If a model file cannot be converted
        (usually by having an unsupported spectrum or spatial model type), the
        program will likely crash. But this will be fixed RSN.

        Exit

        Exit from the ModelEditor. If the current document has been edited,
        the user is prompted to save changes prior to exit.

        Edit menu

        Cut

        This item is a stub, and currently performs no function.

        Copy

        This item is a stub, and currently performs no function.

        Paste

        This item is a stub, and currently performs no function.

        Undo

        This item is a stub, and currently performs no function.

        Source menu

        Add Source

        Add a new default source to the list of sources for this document. A
        default source has a unique name based on the current number of
        sources created. The default source is a PointSource with a PowerLaw
        spectrum (with typical values for the parameters) and a SkyDirFunction
        spatial model (pointing at the origin of the (RA,DEC) coordinate
        system). The user may then edit any of these parameters as needed.

        Remove Source

        Remove the currently selected source from the list of sources in the
        current document.

        Add Point Source

        Add a default point source to the list of sources in the current
        document. The content of a default source is described in the 'Add
        Source' item above.

        Add Diffuse Source

        Add a default diffuse source to the list of sources in the current
        document. Currently, this fills in a default source just like the 'Add
        Point Source' command, but the source name indicates a diffuse
        source. This capability will be improved in a future version of the
        ModelEditor.

        Add Fermi Catalog Sources

        Add all sources from the Fermi Catalog within 5 degrees of a selected
        region on interest (ROI) as defined by a user supplied Fermi event file
        or counts map file created by gtbin.
        Upon selecting this option a dialog box is presented that allows the
        user to input the Fermi Catalog and event files, select diffuse model
        files and model names and enter other parameters related to the source
        selection.  Once the parameters are entered, all sources from the catalog
        file that are within the ROI are loaded into the current model with their
        parameters being free or fixed based on the selected input parameters and
        their distance from the ROI center.

        Add EGRET Diffuse Source

        Add a diffuse source derived from EGRET data. The path to the file of
        data for this model must be manually specified. A future version of
        the ModelEditor will automatically populate the file entry field based
        on the user's environment.

        Add GALPROP Diffuse Source

        Add a diffuse source derived from GALPROP data. The path to the file
        of data for this model must be manually specified. A future version of
        the ModelEditor will automatically populate the file entry field based
        on the user's environment.

        Add Extragalactic Diffuse Source

        Add a diffuse source derived from extragalactic data. The path to the
        file of data for this model must be manually specified. A future
        version of the ModelEditor will automatically populate the file entry
        field based on the user's environment.

        Sort Menu

        Sort Ascending

        Set sorts to be ascending.  This is the default action.  This selection
        will be highlighted red when selected.  Selecting this will automatically
        reverse the order of the sorted list if it was previously in descending
        mode.

        Sort Descending

        Set sorts to be descending.  This selection will be hightlighted red
        when selected.  Selecting this will automatically reverse the order
        of the sorted list if it was previously in ascending mode.

        Clear Sorting

        Removes any of the following selected sorted modes from internal memory
        so that changing the sort direction (ascending or descending) does not
        immediately change the list of sources.  It does not unsort the list
        as no state is maintained of the previous condition of the list.

        Sort by Name

        Sorts all sources based on the Source Name field.  Case is ignored
        for this sort (i.e. 'Source 1' and 'source 1' are considered to be the
        same.

        Sort by Position

        Sorts all sources based on the RA and DEC parameters in the spatial
        model.  The sources are sorted on RA first and then Declination.  If
        the sources does not have a spatial model with the RA and DEC parameters
        the source is sorted to the bottom of the list (in ascending mode.
        They would be first in descending mode).

        Sort by Distance from ROI center

        Sorts all sources based on their distance from the center of the ROI
        imported by reading the event file supplied when catalog sources were
        imported.  This sort really on applies when sources from the catalog
        are read in but if used on a model that didn't have a source catalog
        input, the RA and DEC of the ROI center is considered to be 0,0.  If
        the sources does not have a spatial model with the RA and DEC parameters
        the source is sorted to the bottom of the list.

        Sort by Source Type

        Sorts sources based on their Source Type (either PointSource or
        DiffuseSource).  Diffuse Sources are first in the list in ascending
        mode and Point sources are first in descending mode

        Sort by Spectral Type

        Sorts all sources based on the Spectrum Type field of the spectral
        model.

        Sort by Primary Index

        Sorts all sources based on their primary spectral index.  The name of
        this index varies based on the Spectral Type model and is one of either
        Index, Index1, or alpha.  If a model does not contain one of these
        parameters, it is sorted to the end of the list.

        Sort by Integral Flux

        Sorts sorces based on the 'Integral' parameters in their spectral model.
        This only applies to the PowerLaw2 and BrokenPowerLaw2 models.  Sources
        with all other models are sorted to the end of the list.

        DS9 Menu

        Connect

        Selecting this option establishes a connection with ds9.  If a ds9
        instance is already running, the ModelEditor will connect to this
        instance of the program.  If no ds9 image viewer is running, the
        ModelEditor will launch the ds9 program and then connect to the new
        instance.

        Load Image

        Launches an Open File dialog allowing you to select an image to be
        viewed in the ds9 window.  The selected file will be displayed in the
        current ds9 frame.  If no instance of ds9 is connected to the
        ModelEditor, it will prompt the user asking if they want to make a
        connection. It will then connect to the existing ds9 program or launch
        one as needed.

        Plot Sources

        This is a toggle switch turning on and off the plotting of the ModelEditor
        sources in the ds9 window.  When enabled, the option in the menu is
        highlighted in a red font.  Sources are marked by 1 degree radius white
        circles centered on the source.  The currently selected source is highlighted
        with a red circle.  If no ds9 instance is connected when this option is
        selected, the user is prompted to make the connection as with the Load Image
        option.

        Text Labels

        This is a toggle switch that turns on and off the labeling of the sources
        with the name assigned in the ModelEditor. When enabled, the option in the
        menu is highlighted in a red font. When active the name of the source is
        displayed above the circle surrounding the source.  Names are only displayed
        when source plotting is enabled.  If no ds9 instance is connected when this
        option is selected, the user is prompted to make the connection as with the
        Load Image option.

        Help menu

        Help

        Display this help document.

        About

        Display a dialog which provides summary information on the ModelEditor.

    Notes

    Models must contain at least 1 source.

PARAMETERS

    infile [filename]
        Existing model file to be edited. If no existing file is specified, a
        default model is created, and may be edited.

EXAMPLES

    The user has a set of Fermi data which she suspects contains several
    point sources against the diffuse gamma-ray background. She wants to
    develop a model that has a high likelihood of representing the data.

    She begins by launching the Model Editor:

    ...
    > ModelEditor
    ...

    When the main window appears, a single default point source has
    already been added to the source list for this model. She edits the RA
    and DEC fields in the Spatial Model parameter grid to coincide with
    the suspected location of one of the point sources in the field of
    data. For example, she suspects a point source at (RA,DEC)=(2,73)
    (which is an actual EGRET source 3EG J0010+7309, at
    (RA,DEC)=(2.56,73.17). She therefore enters '2' in the RA value field
    (row with 'name' of 'RA', column with heading of 'value'), and '73' in
    the DEC value field. She suspects that this source is somewhat softer
    than the default source, so she changes the Index value field in the
    Spectrum parameter editor from the default value of -2.1 to the value
    -1.9. Since this is intended as a starting guess, she leaves the
    'free' checkbox for Index checked, so that the likelihood program can
    adjust the index parameter to achieve the best fit to the data. She
    does the same for the Prefactor parameter, so that the best flux
    estimate can be obtained. She then changes the name of this source to
    "Gamma suspect 1".

    She now wants to add another source. She selects Add Source from the
    Source menu, and a new default point source is created and added to
    the list box on the left of the window. She selects that source in the
    list box, and the default parameters populate the editor. She again
    adjust the value of the Index parameter, this time to a steeper value
    (-2.2). She also updates the values of the RA and DEC fields to
    correspond to the suspected source location. She changes the name of
    this source to "Gamma suspect 2". She repeats this process for each
    suspected point source in the field, giving each a unique name.

    She then wants to account for the diffuse background emission, so she
    selects Add EGRET Diffuse Source from the Source menu.

    She then changes the name in the Title field to "Suspected Gamma
    Sources". Finally, she selects Save from the File menu. She navigates
    to her data directory, and saves the file with the name
    "suspect1.xml".

    She then decides to tweak her model a bit by using a different diffuse
    background. She selects EGRET Diffuse Source from the source list,
    then selects Remove Source from the Source menu. She then selects Add
    GALPROP Diffuse Source from the Source menu. She then saves the edited
    model file under a new name, by selecting Save As... from the File
    menu, and entering "suspect2.xml". She then selects Exit from the File
    menu to exit from the Model Editor.

    At this point, the files suspect1.xml and suspect2.xml are ready for
    submission to the likelihood estimator.