.. _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, similar to a Nonmem advan4trans4 model.

        # 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: builtin_fit_example

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

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

.. code-block:: pyml

    name: example

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, similar to a Nonmem advan4trans4 model.

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', 'advan4', 'dep_two_cmp', 'first order']

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's intended that the keywords will eventually form part of a publicly available index of |popy| script files.
    