afc                   package:afc                   R Documentation

_C_a_l_c_u_l_a_t_e _G_e_n_e_r_a_l_i_z_e_d _D_i_s_c_r_i_m_i_n_a_t_i_o_n _S_c_o_r_e _2_A_F_C

_D_e_s_c_r_i_p_t_i_o_n:

     This is the master routine for the calculation the Generalized
     Discrimination Score (aka Two-Alternatives Forced Choice Score -
     2AFC) as described in the Paper of Mason and Weigel (2009). This
     routine requires, as input, datasets of forecasts and
     corresponding observations, as well as a specification of the
     verification context. The routine checks whether the input data
     are consistent with the verification context, then calls the
     appropriate function to calculate the 2AFC, and finally returns
     the 2AFC skill value.

_U_s_a_g_e:

     afc(obsv, fcst, obsv.type, fcst.type, m = 0, m2 = 0)

_A_r_g_u_m_e_n_t_s:

    obsv: Vector of observations. The required format depends on the
          specific verification context. More details below. 

    fcst: Vector or two-dimensional array of forecasts. The required
          format depends on the specific verification context. More
          details below. 

obsv.type: Character specifying the type of the observations. Possible
          values: "d" (dichotomous), "m" (polychotomous with ordinal
          categories), "n" (polychotomous with nominal categories), "c"
          (continuous). 

fcst.type: Character specifying the type of the forecasts. Possible
          values: "d" (dichotomous), "m" (polychotomous with ordinal
          categories), "n" (polychotomous with nominal categories), "p"
          (probabilistic), "c" (continuous) and "e" (ensemble). 

       m: Number of observation or forecast categories (only required
          if obsv.type or fcst.type equals "m" or "n")

      m2: Number of forecast categories (only required if both
          obsv.type and fcst.type equal "m"). The number of observation
          categories is then specified by the argument _m_ above.

_D_e_t_a_i_l_s:

     Depending on the specific verification context (i.e. the choice
     for _obsv.type_ and _fcst.type_), this routine calls the
     appropriate function(s) to calculate the 2AFC score. The following
     combinations of _obsv.type_ and _fcst.type_ are possible: (1)
     "d-d"; (2) "d-m"; (3) "d-p"; (4) "d-c"; (5) "d-e"; (6) "m-m"; (7)
     "m-p"; (8) "m-c"; (9) "m-e"; (10) "n-n"; (11) "n-p"; (12) "c-c";
     (13) "c-e". The required format of the input data _obsv_ and
     _fcst_ depends on the verification context:

     (1) "d-d": 
      _obsv_: vector with dichotomous observations (values in {0,1})
      _fcst_: vector of same length as _obsv_ with dichotomous
     forecasts (values in {0,1}) 

     (2) "d-m": 
      _obsv_: vector with dichotomous observations (values in {0,1})
      _fcst_: vector of same length as _obsv_ with polychotomous
     forecasts (values in {1,..,m}) 

     (3) "d-p": 
      _obsv_: vector with dichotomous observations (values in {0,1})
      _fcst_: vector of same length as _obsv_ with forecast
     probabilities for the event to happen 

     (4) "d-c": 
      _obsv_: vector with dichotomous observations (values in {0,1})
      _fcst_: vector of same length as _obsv_ with real-valued
     forecasts 


     (5) "d-e": 
      _obsv_: vector with dichotomous observations (values in {0,1})
      _fcst_: two-dimensional array with ensemble forecasts;
     dim(fcst)[1] = length(obsv); dim(fcst)[2] = ensemble size.


     (6) "m-m": 
      _obsv_: vector with polychotomous observations (values in
     {1,..,m})
      _fcst_: vector of same length as _obsv_ with polychotomous
     forecasts (values in {1,..,m2}) 

     (7) "m-p": 
      _obsv_: vector with polychotomous observations (values in
     {1,..,m})
      _fcst_: two-dimensional array with forecast probabilities for the
     m categories; dim(fcst)[1] = length(obsv); dim(fcst)[2] = m 

     (8) "m-c": 
      _obsv_: vector with polychotomous observations (values in
     {1,..,m})
      _fcst_: vector of same length as _obsv_ with real-valued
     forecasts 

     (9) "m-e": 
      _obsv_: vector with polychotomous observations (values in
     {1,..,m})
      _fcst_: two-dimensional array with ensemble forecasts;
     dim(fcst)[1] = length(obsv); dim(fcst)[2] = ensemble size.


     (10) "n-n": 
      _obsv_: vector with polychotomous observations (values in
     {1,..,m})
      _fcst_: vector of same length as _obsv_ with polychotomous
     forecasts (values in {1,..,m}) 

     (11) "n-p": 
      Same as "m-p".

     (12) "c-c": 
      _obsv_: vector with real-valued observations 
      _fcst_: vector of same length as _obsv_ with real-valued
     forecasts 


     (13) "c-e": 
      _obsv_: vector with real-valued observations 
      _fcst_: two-dimensional array with ensemble forecasts;
     dim(fcst)[1] = length(obsv); dim(fcst)[2] = ensemble size.

_V_a_l_u_e:

  p.afc : Value of Generalized Discrimination Score (2AFC) 

_A_u_t_h_o_r(_s):

     Andreas Weigel, Federal Office of Meteorology and Climatology,
     MeteoSwiss, Zurich, Switzerland

_R_e_f_e_r_e_n_c_e_s:

     S.J. Mason and A.P. Weigel, 2009. A generic verification framework
     for administrative purposes. Mon. Wea. Rev., 137, 331-349

_S_e_e _A_l_s_o:

     'afc.dd'  'afc.dm'  'afc.dp'  'afc.dc'  'afc.de'   'afc.mm' 
     'afc.mp'  'afc.mc' 'afc.me'  'afc.nn'  'afc.np' 'afc.cc'  'afc.ce'

_E_x_a_m_p_l_e_s:

       #
       #In all following examples, forecasts of the Nino-3.4 index are evaluated
       #
       #----------------------
       #Example 1: Dichotomous observations, dichotomous forecasts
       # ---------------------
       #Load set of dichotomous observations and dichotomous forecasts
       data(cnrm.nino34.dd)
       obsv = cnrm.nino34.dd$obsv
       fcst = cnrm.nino34.dd$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="d", fcst.type="d")

       # ---------------------
       #Example 2: Dichotomous observations, (ordinal) polychotomous forecasts
       # ---------------------
       #Load set of dichotomous observations and polychotomous forecasts (4 categories)
       data(cnrm.nino34.dm)
       obsv = cnrm.nino34.dm$obsv
       fcst = cnrm.nino34.dm$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="d", fcst.type="m", m=4)

       # ---------------------
       #Example 3: Dichotomous observations, probabilistic forecasts
       # ---------------------
       #Load set of dichotomous observations and probabilistic forecasts
       data(cnrm.nino34.dp)
       obsv = cnrm.nino34.dp$obsv
       fcst = cnrm.nino34.dp$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="d", fcst.type="p")

       # ---------------------
       #Example 4: Dichotomous observations, continuous forecasts
       # ---------------------
       #Load set of dichotomous observations and continuous forecasts
       data(cnrm.nino34.dc)
       obsv = cnrm.nino34.dc$obsv
       fcst = cnrm.nino34.dc$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="d", fcst.type="c")

       # ---------------------
       #Example 5: Dichotomous observations, ensemble forecasts
       # ---------------------
       #Load set of dichotomous observations and 9-member ensemble forecasts
       data(cnrm.nino34.de)
       obsv = cnrm.nino34.de$obsv
       fcst = cnrm.nino34.de$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="d", fcst.type="e")

       # ---------------------
       #Example 6: Polychotomous (ordinal) observations, polychotomous (ordinal) forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and polychotomous forecasts (4 categories)
       data(cnrm.nino34.mm)
       obsv = cnrm.nino34.mm$obsv
       fcst = cnrm.nino34.mm$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="m", fcst.type="m", m=4, m2=4)

       # ---------------------
       #Example 7: Polychotomous (ordinal) observations, probabilistic forecasts forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and probabilistic forecasts
       data(cnrm.nino34.mp)
       obsv = cnrm.nino34.mp$obsv
       fcst = cnrm.nino34.mp$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="m", fcst.type="p", m=4)

       # ---------------------
       #Example 8: Polychotomous (ordinal) observations, continuous forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and continuous forecasts
       data(cnrm.nino34.mc)
       obsv = cnrm.nino34.mc$obsv
       fcst = cnrm.nino34.mc$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="m", fcst.type="c", m=4)

       # ---------------------
       #Example 9: Polychotomous (ordinal) observations, ensemble forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and 9-member ensemble forecasts
       data(cnrm.nino34.me)
       obsv = cnrm.nino34.me$obsv
       fcst = cnrm.nino34.me$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="m", fcst.type="e", m=4)

       # ---------------------
       #Example 10: Polychotomous (nominal) observations, polychotomous (nominal) forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and polychotomous forecasts (4 categories)
       data(cnrm.nino34.mm)
       obsv = cnrm.nino34.mm$obsv
       fcst = cnrm.nino34.mm$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="n", fcst.type="n", m=4)

       # ---------------------
       #Example 11: Polychotomous (nominal) observations, probabilistic forecasts
       # ---------------------
       #Load set of polychotomous observations (4 categories) and probabilistic forecasts
       data(cnrm.nino34.mp)
       obsv = cnrm.nino34.mp$obsv
       fcst = cnrm.nino34.mp$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="n", fcst.type="p", m=4)

       # ---------------------
       #Example 12: Continuous observations, continuous forecasts
       # ---------------------
       #Load set of continuous observations and continuous forecasts
       data(cnrm.nino34.cc)
       obsv = cnrm.nino34.cc$obsv
       fcst = cnrm.nino34.cc$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="c", fcst.type="c")

       # ---------------------
       #Example 13: Continuous observations, ensemble forecasts
       # ---------------------
       #Load set of continuous observations and 9-member ensemble forecasts
       data(cnrm.nino34.ce)
       obsv = cnrm.nino34.ce$obsv
       fcst = cnrm.nino34.ce$fcst
       #Calculate skill score
       afc(obsv, fcst, obsv.type="c", fcst.type="e")

