!-------------------------------------------------------------------------
!         NASA/GSFC, Data Assimilation Office, Code 910.3, GEOS/DAS      !
!-------------------------------------------------------------------------
!BOP
!
! !MODULE:  m_soqcs --- Implements Statistical On-line QC System
! 
! !INTERFACE:
!
      MODULE m_soqcs

! !USES:

      use m_odsmeta                         ! ODS metadata: qc flags, etc
      use m_ods                             ! ODS vector class (GEOS-4)
      use m_ods_structure                   ! ODS vector class (GEOS-2)
      use m_die                             ! error messages

!
! !PUBLIC MEMBER FUNCTIONS:
!
      PUBLIC soqcs             ! QC main interface

!
! !DESCRIPTION: This module is a simple wrapper around the GEOS-2
!               {\tt psas\_qc()} package. It also provides access to the
!  quality marks.
!
! !REVISION HISTORY: 
!
!  10oct1999  da Silva  Initial code.
!
!EOP
!-------------------------------------------------------------------------

      CONTAINS

!-------------------------------------------------------------------------
!         NASA/GSFC, Data Assimilation Office, Code 910.3, GEOS/DAS      !
!-------------------------------------------------------------------------
!BOP
!
! !IROUTINE:  SOQCS --- Performs Statistical On-line Quality Control
! 
! !INTERFACE:
!
      subroutine SOQCS ( y, nobs, nobs_good )

! !USES:

      Implicit NONE
    
!
! !PARAMETERS: 
!
      integer,          intent(in)    :: nobs ! number of observations

      type(obs_vect),   intent(inout) :: y    ! observation vector

! !RETURN VALUE:

      integer, intent(out)            :: nobs_good ! number of obs passing
                                                   !  QC; these are now at
                                                   !  the front of the list
!
! !DESCRIPTION: This routine implements the following quality checks on
! the observations:
!
! \begin{tabbing}
! xxx\=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx\=\kill
! \>  background check:     \> marks outliers as suspect or extreme\\
! \>  iterated buddy check: \> compares suspects with neighboring data\\
! \>  wind check:           \> eliminates unpaired wind components\\
! \>  profile check:        \> eliminates profiles containing bad data
! \end{tabbing}
!
! The main driver routine {\tt SOQCS} requires an ODS vector as input.
! Apart from the order of the data within the ODS structure, only the ODS
! quality control attributes {\tt qcexcl} and {\tt qchist} will be changed
! on output. Data that passed quality control will have {\tt qcexcl}$=0$ and
! will be located in the top section of the ODS structure.
! \\[1ex]
! On input, {\tt SOQCS} will reset any quality control marks that were
! previously set by this package. In addition, the result (i.e. the values
! of the quality control marks) is independent of the order of the input data.
! Consequently, applying {\tt SOQCS} more than once to the same set of
! data will not change the result.
! \\[1ex]
! Numerical values and descriptions of all quality control marks produced
! by {\tt SOQCS}, and by other GEOS DAS quality control procedures, are
! defined in the include file {\tt qcflag.h}.
! \\[1ex]
! {\bf Rules pertaining to quality control marks:}
!
! \bv
! 1. Generally, the only permitted values are:
!
!       qchist = 0, 1, ..., NH_P + NH_Q
!       qcexcl = 0, 1, ..., NX_P + NX_Q
!
!    qchist = 0, 1, ..., NH_P and qcexcl = 0, 1, ..., NX_P are reserved
!    for preprocessing; the remaining flag values may be generated by this
!    package or at a later stage in the data stream.
!
! 2. On input, any qcexcl>NX_P will be immediately reset to qcexcl=0,
!    and any qchist>NH_P will be immediately reset to qchist=0.
!
!    In combination with the rules below, this rule implies that flags will
!    be reset to their original values when this package was first called.
!
! 3. If 0<qcexcl<=NX_P on input, then both qcexcl and qchist will remain
!    unchanged on output.
!
!    This means that items already excluded by preprocessing will not be
!    considered at all by this package. On output these will be the last
!    n_total-n_tested items in the list.
!
! 4. If qcexcl=0 on input (or if reset to 0 by rule 2), then qcexcl may
!    change to a value in the range
!
!       qcexcl = NX_P + 1, ..., NX_P + NX_Q.
!
!    This means that on-line QC may produce one of several exclusion flags for
!    obs which have not been excluded a priori.
!
! 5. If 0<qchist<=NH_P on input, then qchist will remain unchanged on output.
!
!    This means that a nonzero history flag from preprocessing will not be
!    overwritten by this package. However the exclusion flag may be set by
!    this package in accordance with the previous rule.
!
! 6. If qchist=0 on input (or if reset to 0 by rule 2), then qchist may change
!    to a value in the range
!
!       qchist = NH_P + 1, ..., NH_P + NH_Q.
!
!    This means that on-line QC may produce one of several history flags for
!    obs which have do not have an a priori history flag.
! \ev
!
! Together these rules imply that this package produces history and exclusion
! flags which are both within preset intervals. Other sets of flags are
! reserved for either pre- or postprocessing, e.g. renewed QC based on
! retrospective analysis.
!
! !REVISION HISTORY: 
!
!  08oct1999  da Silva   Simple wrapper around GEOS-2 package psas_qc().
!  03mar2000  da Silva   Removed special handling of RH obs for compatibility
!                        with SQC v1.5.
!
!EOP
!-------------------------------------------------------------------------

      character(len=*), parameter :: myname = 'Passive_Check'

      logical, parameter :: verbose = .true. ! until we fix stdout issues


      type(ods_attributes_type) :: ods ! old GEOS-2 data type


!     Nobs=0 check
!     ------------
      if ( nobs .eq. 0 ) then
           call warn ( myname, 'no observations, nothing to do.' )
           return 
      end if

!     Convert ODS vector from GEOS-4 to GEOS-2 style. Only pointers
!     are reassigned here, so changes in ods will carry over to y
!     -------------------------------------------------------------
      call ODS_GEOS4to2 ( y, ods )

!     Performs the QC proper using GEOS-2 interface
!     ---------------------------------------------
      call PSAS_QC ( nobs, nobs_good, ods, verbose )

      end subroutine soqcs

      end module m_soqcs