.. _description:

DESCRIPTION
############

This optional section is an opportunity to provide notes about the model. The script is given a (short) **name** and a (longer) **title**. The **author** of the model can be named and the **abstract** is used to describe the model. You can define **keywords** to aid future searches.

.. _description_example:

Example DESCRIPTION
======================

.. code-block:: pyml

    DESCRIPTION:
        # Unique name used to distinguish script
        name: builtin_fit_example

        # A longer text string that could serve as a title
        title: First order absorption model with peripheral compartment

        # Author of the model
        author: J.R. Hartley

        # Abstract paragraph describing model
        abstract: |
            A two compartment PK model with bolus dose and
            first order absorption.

        # Keywords list used to categorise models.
        keywords: ['fitting', 'pk', 'advan4', 'dep_two_cmp', 'first order']

.. _description_main_fields:
        
Main DESCRIPTION Fields
=========================
   
.. _description_name_spec:

name
----    
 
The optional **name** entry is used as an identifier for the script. It is also used to form the name of **child** scripts. For example when specifying the name:-

If you do |not| specify a name the field defaults to:-

.. code-block:: pyml

    name: none

the **child** :ref:`sim_script` will be named 'none_sim.pyml' and the child :ref:`fitsum_script` will be named 'none_fitsum.pyml' |etc|. For this reason it's a good idea to keep the **name** short and only use alpha numeric characters and underscores.

For more info see :ref:`files_generated_by_fit_script`.

    
.. _description_title_spec:

title
-----

The **title** field is optional, but otherwise appears in the summary output and on graphical plots.

.. _description_author_spec:

author
------

The **author** field is optional but allows you to store the name of the person who created the script.

.. _description_abstract_spec:

abstract
--------

The **abstract** field is optional, but allows a longer description of the purpose of the script.

This field is :term:`verbatim`, so it is suffixed with a '|' symbol. See:-

.. code-block:: pyml
    
    abstract: |
        A two compartment PK model with bolus dose and
        first order absorption.

The abstract is included in the summary output. It can contain any text you like. Note it is indented relative to the 'abstract' field name, like all :term:`verbatim` sections.

.. _description_keywords_spec:

keywords
--------

The **keywords** field is optional and contains a list of strings, for example:-

.. code-block:: pyml

    keywords: ['fitting', 'pk', 'dep_two_cmp', 'first order','advan4']

Here the |python| notation for a :term:`list` is used, |ie| an opening square bracket '[' followed by comma separated strings and a closing square bracket ']'.  
    
Note: it is intended that the keywords will eventually form part of a publicly available index of |popy| script files.
    