=======================
Using the NONMEM plugin
=======================
This page will cover different topics relevant to users who are using Pharmpy for a NONMEM model.

----------------------------------------
Names of parameters and random variables
----------------------------------------
When Pharmpy parses a model, it recognizes and stores etas, thetas etc. as parameters and random variables. You can
configure which names Pharmpy uses when parsing the model file, i.e. what they are called when you want to access them
using transformation functions etc. You can also configure how etas are written once you have added new etas. The
naming system can be divided into three parts: how the names are parsed from NONMEM code, how new names are added to
the model object, and how new names are written into NONMEM code.

Reading in a model
------------------
When Pharmpy parses the NONMEM model file, depending on your Pharmpy configuration file (see :ref:`config_page`)
it will use different names for the internal representation of parameters. The following naming schemes are supported:

* Standard NONMEM names ('basic')
* Comments next to $THETA, $OMEGA, and $SIGMA records ('comment')
* Any abbreviated names from $ABBR ('abbr')

You can set which naming schemes you want to use, and prioritize between them. For each parameter and random variable,
Pharmpy will check which names are available and choose the one that is highest in priority. For example, assume you
have the following configuration:

.. code-block::

   parameter_names=abbr,comment,basic

Where names from abbreviated records are prioritized first, comments next, and finally the basic NONMEM names.
Given the following model:

.. code-block::

   $PROBLEM SIMPLE MODEL
   $DATA pheno.dta IGNORE=@
   $INPUT ID TIME AMT WGT APGR DV
   $SUBROUTINE ADVAN1 TRANS2

   $ABBR REPLACE THETA(CL)=THETA(1)
   $ABBR REPLACE ETA(CL)=ETA(1)

   $PK
   CL=THETA(CL)*EXP(ETA(CL))
   V=THETA(2)*EXP(ETA(2))
   S1=V

   $ERROR
   Y=F+F*EPS(1)

   $THETA (0,0.00469307) ; TVCL
   $THETA (0,1.00916) ; TVV
   $OMEGA 0.0309626  ; IVCL
   $OMEGA 0.031128
   $SIGMA 0.1

For the first theta, `TVCL`, `THETA_CL`, and `THETA(1)` are possible names. Since the setting for abbreviated names is
prioritized the highest, `THETA_CL` will be used. Note that `THETA(CL)` is parsed as `THETA_CL`. For the
second omega record, there is no abbreviated name and no comment, so it will simply be called `OMEGA(2,2)`.

New parameters and random variables
-----------------------------------
When performing different transformations or manipulations of the model, the names of the parameters and random
variables do not have to follow the previously mentioned name schemes. Let’s say we have a model with no etas, and
the model is transformed accordingly:

.. code-block::

   add_iiv(model, 'CL', 'exp')
   model.update_source()

If you add an eta to the parameter clearance (`CL`), the new eta name will default to `ETA_CL` and the omega name
`IIV_CL`. When performing subsequent transformations, `ETA_CL` and `IIV_CL` are the names you will refer to even if
the NONMEM name for them would be `ETA(1)` and `OMEGA(1,1)` respectively. Now we want to remove that eta:

.. code-block::

   remove_iiv(model, ['ETA_CL'])

We still have to refer to the eta as `ETA_CL`. If you update the NONMEM code, `ETA_CL` will be replaced
with `ETA(1)` in the code (this does however not affect the Pharmpy name).

Writing a model
---------------
When calling `update_source()` or `write_model()`, the NONMEM code will be updated based on your changes. As a default,
all parameters will have NONMEM names in the code and their Pharmpy name (if different from NONMEM name)
as comments. For example, if you’ve added a new parameter `MAT` (in a model with no thetas), the resulting theta
`POP_MAT` will look like this in the NONMEM code:

.. code-block::

   $PK
   MAT = THETA(1)
   …
   $THETA (0,0.1) ; POP_MAT

Note that the internal Pharmpy name still is `POP_MAT` despite it being called `THETA(1)` in the code.

The configuration can be set to write eta names as $ABBR records via the setting:

.. code-block::

   write_etas_in_abbr=True

This setting can be set to `True` or `False` (default). Using the example of adding an eta to clearance (`CL`), the updated
code will be:

.. code-block::

   $ABBR REPLACE ETA(CL)=ETA(1)
   $PK
   CL=TVCL*EXP(ETA(CL))
   …
   $OMEGA 0.09 ; IIV_CL
