.. SPDX-FileCopyrightText: 1992-2026 NWO-I/SRON Space Research Organisation Netherlands
..
.. SPDX-License-Identifier: CC-BY-4.0

.. _spexapi_plot:

Plot functions
==============

Plot
""""

Update plot:

.. code-block:: fortran

    call spex%plot(ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot(this, ier)
      class(sapi), intent(inout)  :: this
      integer,intent(out)         :: ier
      end subroutine

Plot ascdump
""""""""""""

Write plot data to QDP file:

.. code-block:: fortran

    call spex%plot_adump(qdpfile,overwrite)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_adump(this, qdpfile, overwrite)
      class(sapi), intent(inout)  :: this
      character*(*), intent(in)   :: qdpfile
      logical, intent(in)         :: overwrite
      end subroutine

Plot frame
""""""""""

New frame:

.. code-block:: fortran

    call spex%plot_frame_new()

Interface:

.. code-block:: fortran

      module subroutine spex_plot_frame_new(this)
      class(sapi), intent(inout) :: this
      end subroutine

Set current frame number to manipulate:

.. code-block:: fortran

    call spex%plot_frame_set(i,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_frame_set(this, i, ier)
      class(sapi), intent(inout)  :: this
      integer,intent(in)          :: i
      integer,intent(out)         :: ier
      end subroutine

Delete frame (range):

.. code-block:: fortran

    call spex%plot_frame_del(i1,i2,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_frame_del(this, i1, i2, ier)
      class(sapi), intent(inout)  :: this
      integer,intent(in)          :: i1
      integer,intent(in)          :: i2
      integer,intent(out)         :: ier
      end subroutine

Plot devices
""""""""""""

Set plot device:

.. code-block:: fortran

    call spex%plot_device(dev,file,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_device(this,dev,file,ier)
      class(sapi), intent(inout)  :: this
      character*(*), intent(in)   :: dev    ! Device name
      character*(*), optional     :: file   ! Filename (optional, for PS output)
      integer, intent(out)        :: ier
      end subroutine

Close plot device:

.. code-block:: fortran

    call spex%plot_device_close(in,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_device_close(this,in,ier)
      class(sapi), intent(inout)    :: this
      integer, intent(in)           :: in
      integer, intent(inout)        :: ier
      end subroutine

Plot properties
"""""""""""""""

Set font height:

.. code-block:: fortran

    call spex%plot_fh(fonth)


Interface:

.. code-block:: fortran

      module subroutine spex_plot_set_fh(this,fonth)
      class(sapi), intent(inout)  :: this
      real(dp), intent(in)        :: fonth  !! Font number (integer)
      end subroutine

Set font type:

.. code-block:: fortran

    call spex%plot_font(ifont)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_set_font(this,ifont)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: ifont  !! Font number (integer)
      end subroutine

Set linetype:

.. code-block:: fortran

    call spex%plot_lt(ltype)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_set_lt(this,ltype)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: ltype  !! Line type (integer)
      end subroutine

Set linewidth:

.. code-block:: fortran

    call spex%plot_lw(lwidth)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_set_lw(this,lwidth)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: lwidth  !! Line type (integer)
      end subroutine

Set plot orientation in hardcopy:

.. code-block:: fortran

    call spex%plot_hard(mode,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_hard(this, mode, ier)
      class(sapi), intent(inout)  :: this
      character*(*), intent(in)   :: mode    !! orientation (landscape/potrait)
      integer, intent(out)        :: ier     !! Error status
      end subroutine

Plot information:

.. code-block:: fortran

    call spex%plot_info(ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_info(this, ier)
      class(sapi), intent(inout)    :: this
      integer, intent(out)          :: ier
      end subroutine

Set axis to logarithmic/linear:

.. code-block:: fortran

    call spex%plot_log(axis,scale,inr1,inr2,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_log(this, axis, scale, inr1, inr2, ier)
      class(sapi), intent(inout)   :: this
      character(len=1), intent(in) :: axis    !! axis
      character(len=3), intent(in) :: scale   !! scaling type (lin/log)
      real(dp), intent(in) :: inr1            !! lower range of scaling
      real(dp), intent(in) :: inr2            !! upper range of scaling
      integer, intent(out) :: ier             !! Error status
      end subroutine

Plot rescale:

.. code-block:: fortran

    call spex%plot_rescale(raxis,inr1,inr2,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_rescale(this, raxis, inr1, inr2, ier)
      class(sapi), intent(inout)      :: this
      character*2,  intent(in)        :: raxis  !! axis (rx,ry,rz)
      real(dp), intent(in)            :: inr1   !! low end of range
      real(dp), intent(in)            :: inr2   !! high end of range
      integer, intent(out)            :: ier    !! Error status
      end subroutine

Plot set:

.. code-block:: fortran

    call spex%plot_set(all, in1, in2)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_set(this, all, in1, in2)
      class(sapi), intent(inout)  :: this
      logical, intent(in)         :: all
      integer, intent(in)         :: in1,in2
      end subroutine

Plot new string and delete it:

.. code-block:: fortran

    call spex%plot_string_new(x,y,text)
    call spex%plot_string_del(i1,i2)
    call spex%plot_string(prop,i1,i2,boxprop,ini,inr,inl,ina,ier)

Interfaces:

.. code-block:: fortran

      module subroutine spex_plot_string_new(this,x,y,text)
      class(sapi), intent(inout)  :: this
      real(dp), intent(in)        :: x    !! X coordinate for the string
      real(dp), intent(in)        :: y    !! Y coordinate for the string
      character*(*), intent(in)   :: text !! The string text
      end subroutine

      module subroutine spex_plot_string_del(this, i1, i2)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: i1  !! Lower string ID
      integer, intent(in)         :: i2  !! Upper string ID
      end subroutine

      module subroutine spex_plot_string(this, prop, i1, i2, boxprop, ini, inr, inl, ina, ier)
      class(sapi), intent(inout)  :: this
      character*(*), intent(in)   :: prop    !! Property to change
      integer, intent(in)         :: i1      !! Lower string number
      integer, intent(in)         :: i2      !! Upper string number
      character*(*), intent(in)   :: boxprop !! If property is 'box', select subproperty ('lt','lw','col')
      integer, intent(in)         :: ini     !! Integer input value
      real(dp), intent(in)        :: inr     !! Real input value
      logical, intent(in)         :: inl     !! Logical input value
      character*(*), intent(in)   :: ina     !! Text input value
      integer, intent(out)        :: ier
      end subroutine

Set plot type:

.. code-block:: fortran

    call spex%plot_type(ptype,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_type(this, ptype, ier)
      class(sapi), intent(inout)       :: this
      character*(*),  intent(in)       :: ptype     !! The plot type
      integer, intent(out)             :: ier       !! Error status
      end subroutine

Example:

.. code-block:: fortran

    call spex%plot_type('data',ier)


Plot unit:

.. code-block:: fortran

    call spex%plot_unit(uaxis,raxis,runit,inr,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_unit(this, uaxis, raxis, runit, inr, ier)
      class(sapi), intent(inout)  :: this
      character*(*), intent(in)   :: uaxis             !! Unit axis (ux;uy;uz)
      character*(*), intent(in)   :: raxis             !! ref axis
      character*(*), intent(in), optional :: runit     !! ref unit
      real, optional, intent(in)  :: inr               !! Unit energy
      integer, intent(out)        :: ier               !! Error status
      end subroutine

Plot set viewport:

.. code-block:: fortran

    call spex%plot_view(iview,back_col,range_low,range_high,status,ier)

Interface:

.. code-block:: fortran

      module subroutine spex_plot_set_view(this, iview, back_col, range_low, range_high, status, ier)
      class(sapi), intent(inout)    :: this
      character*(*), intent(in)     :: iview       !! View property to change ('x', 'y', 'back', 'transp','default')
      integer, intent(in)           :: back_col    !! Background color number
      real(dp), intent(in)          :: range_low   !! Low end of range (for 'x' and 'y')
      real(dp), intent(in)          :: range_high  !! High end of range (for 'x' and 'y')
      logical, intent(in)           :: status      !! Switch transparency or default on or off.
      integer, intent(out)          :: ier
      end subroutine

Plot ion
--------

Plot line labels for a particular ion.

.. code-block:: fortran

    call spex%plot_ion(iz,jz,z)

Where ``iz`` is the atomic number, ``jz`` is the ionisation stage, and ``z``
the redshift of the lines.

.. code-block:: fortran

    module subroutine spex_plot_ion(this,iz,jz,z)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: iz   !! Atomic number of the line
      integer, intent(in)         :: jz   !! Ionisation state
      real, intent(in)            :: z    !! Shift of the lines
      end subroutine

Example:

.. code-block:: fortran

    call spex%plot_ion(26,25,0.)  ! For Fe XXV at z=0

To delete (a range of) labels:

.. code-block:: fortran

    call spex%plot_ion_del(i1,i2)

Where ``i1`` and ``i2`` are the lower and upper range of the labels to delete.

.. code-block:: fortran

      module subroutine spex_plot_ion_del(this,i1,i2)
      class(sapi), intent(inout)  :: this
      integer, intent(in)         :: i1   !! Start number of the line id to delete
      integer, intent(in)         :: i2   !! End number of the line id to delete
      end subroutine

Example:

.. code-block:: fortran

    call spex%plot_ion_del(1,2)