Improve KPI Module #54 (#88)

* KPI module calculates for all days without deleting old data #28
* Compute KPI per bus id hourly #35
* Compute occupation factor using mean and median traveled distance.  #53
* KPI tables have a weekday and weekend day type #71
* Fixes #70 
* Update documentation
* Create kpi tables within create_db
* Add KPI by services
* Add new tables for basic kpi with no gps
* Rename kpi tables

docs/source/configuracion.rst

@@ -122,6 +122,9 @@ Parámetros de posicionamiento GPS
 
 Este parámetro se utiliza para cuando existe una tabla separada con GPS que contenga el posicionamiento de los vehículos o internos. En ese caso, se gelocalizará cada transacción en base a la tabla GPS, uniendo por `id_linea` e `interno` (haciendo a este campo obligatorio) y minimizando el tiempo de la transacción con respecto a la transacción gps del interno de esa linea. Para eso el campo ``fecha`` debe estar completo con dia, hora y minutos. Esto hace obligatoria la existencia de un csv con la información de posicionamiento de los gps. Su nombre y atributos se especifican de modo similar a lo hecho en transacciones.
 
+
+En ocasiones en la tabla de GPS puede haber información sobre los servicios prestados por cada vehículo. Para más detalles sobre esta configuración y cómo lo trabaja UrbanTrips ver el apartado **Servicios**.
+
 .. code:: 
 
    geolocalizar_trx: True
@@ -136,7 +139,12 @@ Este parámetro se utiliza para cuando existe una tabla separada con GPS que con
       fecha_gps: date_time
       latitud_gps: latitude
       longitud_gps: longitude
+      servicios_gps: TYPE
+      velocity_gps: VELOCITY
 
+   trust_service_type_gps: False
+   valor_inicio_servicio: 7
+   valor_fin_servicio: 9
 
 
 Parámetro de lineas, ramales y paradas

docs/source/index.rst

@@ -26,6 +26,7 @@ Cotenido
    factores_expansion
    lineas_ramales
    resultados
+   kpi
    servicios   
 
 

docs/source/kpi.rst

@@ -0,0 +1,36 @@
+KPI
+==============
+
+En este apartado se describen los diferentes tipos de KPI que UrbanTrips puede producir en función de los inputs con los que cada ciudad cuente. Se comienza por el caso donde solamente existen datos de demanda. En segundo lugar se abordan los KPI que puede producir cuando existen datos en de la oferta, como puede ser la tabla de GPS como así también información de servicios ofertados. 
+
+En base a demanda
+-----------------
+
+Cuando no existen datos de oferta, expresada fundamentalmente en la tabla GPS de posicionamiento de vehículos, UrbanTrips puede calcular algunos elementos de oferta y demanda en base a la tabla de transacciones en base al concepto de *pasajero equivalente*. Tomando la tabla de etapas se calcula por hora y dia para el interno de cada linea el total de pasajeros que iniciaron una etapa a esa hora en ese interno, la distancia media viajada (*DMT*) y la velocidad comercial promedio a la que circula ese interno en esa hora (siempre tomando solamente las coordenadas del interno cuando recoge pasajeros). 
+
+Tomando estos datos se construye para cada pasajero un *pasajero equivalente* poniendo en relación cuántas posiciones disponibles en ese interno utilizó y por cuánto tiempo. Es decir, si un pasajero recorre 5 km en un interno que circula a 10 kmh, equivaldrá a 0.5 posiciones o pasajeros equivalentes. Para calcular un factor de ocupación se considera que cada interno oferta 60 ubicaciones y se compara el total de pasajeros equivalentes en esa hora en ese interno contra ese stock fijo. Luego se procede a agregar tdos estos estadísticos para diferentes niveles de agregación (interno y linea) así como también para un día de la semana tipo o dia de fin de semana tipo (siempre que hayan días procesados que pertenezcan a uno de esos tipos).  
+
+Los resultados quedan almacenados en las siguientes tablas  (para más detalles vea el apartado :doc:`resultados`).  
+
+* ``basic_kpi_by_vehicle_hr``: arroja la batería de estadísticos por vehículo para cada linea, día y hora.
+* ``basic_kpi_by_line_hr``: arroja la batería de estadísticos promediando para cada linea, día y hora (incluyendo día de semana y de fín de semana típico).
+* ``basic_kpi_by_line_day``: arroja la batería de estadísticos promediando para cada linea y día (incluyendo día de semana y de fín de semana típico).
+
+
+En base a GPS
+-------------
+
+Cuando existe una tabla de GPS se puedem elaborar estadísicos más elaborados y precisos. En primer lugar se procura obtener un factor de ocupación comparando los Espacio Kilómetro Demandados (EKD) como proporción de los Espacio Kilómetro Ofertados (EKO). Para los primeros (EKD)  se toma la cantidad de pasajeros transportados multiplicados por una DMT que puede ser utilizando la distancia media o la mediana, para evitar la influencia de medidas extremas que puedan incidir en el indicador. Para los segundos (EKO) se toma el total de kilómetros recorridos en base a la información disponible en la tabla GPS y se los multiplca por las 60 ubicaciones que se considera posee cada interno. 
+
+En segundo lugar, se obtiene un Índice Pasajero Kilómetro (IPK) poniendo en relación el total de pasajeros transportados sobre el total de kilómetros recorridos por la línea. Para obtener estos indicadores principales se obtiene otros insumos que quedan en la base de datos, como el total de pasajeros, el total de kilómetros recorridos, la distancias medias y medianas viajadas, los vehículos totales, los pasajeros por vehículo por día, y los kilómetros por vehículo por día. Esto se calcula agregado para cada linea y día procesado, así como también para un día de la semana tipo o dia de fin de semana tipo.
+
+Los resultados quedan almacenados en la tabla ``kpi_by_day_line`` (para más detalles vea el apartado :doc:`resultados`).  
+
+En base a servicios
+-------------------
+
+UrbanTrips permite obtener datos a nivel de servicios para cada vehículo de cada línea (para más información pueden leer el aparatdo de :doc:`servicios`). Una vez que esta clafisicación de los datos de GPS en servicios ha tenido lugar, pueden obtenerse diferentes KPI al nivel de cada servicio identificado. Los resultados quedan almacenados en la tabla ``kpi_by_day_line_service`` (para más detalles vea el apartado :doc:`resultados`)  
+
+
+
+

docs/source/resultados.rst

@@ -468,7 +468,7 @@ Estas tablas contienen estadísticos calculados por UrbanTrips. Algunos estádis
 
 
 
-.. list-table:: indicadores_operativos_linea
+.. list-table:: kpi_by_day_line
    :widths: 25 25 50
    :header-rows: 1
 
@@ -505,15 +505,165 @@ Estas tablas contienen estadísticos calculados por UrbanTrips. Algunos estádis
    * - *ipk*
      - float
      - Índice Pasajero Kilómetro.
-   * - *fo*
+   * - *fo_mean*
      - float
-     - Factor de ocupación tomando 60 ubicaciónes por vehículo.
+     - Factor de ocupación tomando 60 ubicaciónes por vehículo tomando la DMT promedio.
+   * - *fo_median*
+     - float
+     - Factor de ocupación tomando 60 ubicaciónes por vehículo tomando la DMT mediana.
 
 
 
 
+.. list-table:: kpi_by_day_line_service
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Campo
+     - Tipo de dato
+     - Descripción
+   * - *id_linea*
+     - int
+     - id identificando la linea
+   * - *dia*
+     - text
+     - Fecha del día para el cual fue computado el estadístico
+   * - *interno*
+     - int
+     - numero de interno o vehículo utilizado en la transacción.
+   * - *service_id*
+     - int
+     - numero de service dentro del vehiculo o interno para esa linea y dia.
+   * - *hora_inicio*
+     - float
+     - hora de inicio del servicio.
+   * - *hora_fin*
+     - float
+     - hora de cierre del servicio.
+   * - *tot_km*
+     - float
+     - Total de kilómetros ofertados por el servicio.
+   * - *tot_pax*
+     - float
+     - Total de pasajeros transportados por el servicio.
+   * - *dmt_mean*
+     - float
+     - Distancia media recorrida por pasajero del servicio.
+   * - *dmt_median*
+     - float
+     - Distancia mediana recorrida por pasajero del servicio.
+   * - *ipk*
+     - float
+     - Índice Pasajero Kilómetro.
+   * - *fo_mean*
+     - float
+     - Factor de ocupación tomando 60 ubicaciónes por vehículo tomando la DMT promedio.
+   * - *fo_median*
+     - float
+     - Factor de ocupación tomando 60 ubicaciónes por vehículo tomando la DMT mediana.            
 
 
+
+.. list-table:: basic_kpi_by_vehicle_hr
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Campo
+     - Tipo de dato
+     - Descripción
+   * - *dia*
+     - text
+     - Fecha del día para el cual fue computado el estadístico
+   * - *id_linea*
+     - int
+     - id identificando la linea
+   * - *interno*
+     - int
+     - numero de interno o vehículo utilizado en la transacción.
+   * - *hora*
+     - float
+     - hora en la que se encuentra circulando el vehiculo.
+   * - *tot_pax*
+     - float
+     - Total de pasajeros transportados por el vehiculo para esa hora.
+   * - *eq_pax*
+     - float
+     - Total de pasajeros equivalentes transportados por ese vehículo durante esa hora.
+   * - *dmt*
+     - float
+     - Distancia media recorrida por pasajero del vehiculo para esa hora.
+   * - *of*
+     - float
+     - Factor de ocupación calculado como la relación entre la DMT y la velocidad comercial.
+   * - *speed_kmh*
+     - float
+     - Velocidad comercial promedio de ese vehiculo a esa hora.
+
+
+
+.. list-table:: basic_kpi_by_line_hr
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Campo
+     - Tipo de dato
+     - Descripción
+   * - *dia*
+     - text
+     - Fecha del día para el cual fue computado el estadístico
+   * - *id_linea*
+     - int
+     - id identificando la linea
+   * - *hora*
+     - float
+     - hora del día.
+   * - *veh*
+     - float
+     - Total de vehículos únicos circulando a esa hora para esa linea y día.
+   * - *pax*
+     - float
+     - Total de pasajeros que iniciaron una etapa en esa linea a esa hora y día.
+   * - *dmt*
+     - float
+     - Distancia media recorrida por pasajero del vehiculo para esa hora y día.
+   * - *of*
+     - float
+     - Factor de ocupación promedio calculado como la relación entre la DMT y la velocidad comercial.
+   * - *speed_kmh*
+     - float
+     - Velocidad comercial promedio de esa línea a esa hora para ese día.
+
+
+.. list-table:: basic_kpi_by_line_day
+   :widths: 25 25 50
+   :header-rows: 1
+
+   * - Campo
+     - Tipo de dato
+     - Descripción
+   * - *dia*
+     - text
+     - Fecha del día para el cual fue computado el estadístico
+   * - *id_linea*
+     - int
+     - id identificando la linea
+   * - *veh*
+     - float
+     - Total de vehículos únicos circulando para esa linea y día.
+   * - *pax*
+     - float
+     - Total de pasajeros que utilizaron esa linea ese día.
+   * - *dmt*
+     - float
+     - Distancia media recorrida por pasajero en esa línea ese día.
+   * - *of*
+     - float
+     - Factor de ocupación promedio calculado como la relación entre la DMT y la velocidad comercial.
+   * - *speed_kmh*
+     - float
+     - Velocidad comercial promedio de esa línea para ese día.
+
+
 Modelo de datos de base ``insumos``
 -----------------------------------
 

docs/source/servicios.rst

@@ -12,14 +12,28 @@ Como los servicios son una unidad de información vital para obtener ciertos ind
     	nombres_variables_gps=nombres_variables_gps,
     	formato_fecha=formato_fecha)
 
-Dicha tabla debe tener un atributo donde se especifique el inicio de un servivcio. Tambien puede especificarse el final del mismo. Esto debera cargarse en el archivo de configuracion del especificando el [ATTR] y los valores correspondientes del siguiente modo:
+Dicha tabla debe tener un atributo donde se especifique el inicio de un servicio. Tambien puede especificarse el final del mismo. Esto debera cargarse en el archivo de configuracion. Por un lado especificando la columna que almacena los datos de servicio, en el mismo lugar que se especifican las otras columnas de la tabla gps en ``servicios_gps``. Por otro lado los valores que en esa columna indican una apertura y cierre de servicios en los parámetros ``valor_inicio_servicio`` y ``valor_fin_servicio``:
+
 
 .. code:: yaml
 
-    servicios_gps: [ATTR]
+    nombres_variables_gps:
+        id_gps: DTSN
+        id_linea_gps: [ATTR]
+        id_ramal_gps: [ATTR]
+        interno_gps: [ATTR]
+        fecha_gps: [ATTR]
+        latitud_gps: [ATTR]
+        longitud_gps:  [ATTR]
+        servicios_gps: [ATTR]
+        velocity_gps: [ATTR]
+
+    trust_service_type_gps: False
     valor_inicio_servicio: [VAL]
     valor_fin_servicio: [VAL]
 
+
+
 A su vez en el archivo de configuración se debe setear el parámetro correspondiente. Si ese atributo es confiable o si UrbanTrips debe, dentro de cada servicio tal como es declarado por el conductor, clasificar nuevos servicios.  
 
 .. code:: yaml
@@ -100,4 +114,18 @@ Para resolverlo, dichas paradas pueden agregarse en un único nodo mediante el c
   :alt: Clasificacion servicios ramal
 
 
+Resultados
+----------
+
+Los resultados de la clasificación de servicios quedan en una serie de tablas dentro de la db de los datos (para más información puede consultar :doc:`resultados`). Estas tablas pueden ofrecer información para diagnósticar la clasificación.
+
+
+*  ``services``: agrupa los servicios ofertados por las diferentes lineas, sin clasificarlos por ramal. Cada servicio tiene un id tal cual fue identificado por el conductor del vehículo y otro tal como fue identificado por UrbanTrips. Para cada servicio se agregan algunos datos como la hora de inicio y de fin, la cantidad de puntos gps, el porcentaje de puntos donde el vehículo estuvo detenido, etc.
+*  ``services_gps_points``:  vincula cada punto gps de la tabla ``gps`` con la tabla ``services``. A su vez indican el ``node_id`` más cercano y el ramal al que pertenece.
+*  ``services_stats``: para cada línea y día arroja una batería de estadísticos comparando los servicios tal cual venían declarados en la información original con los servicios tal cual fueron inferidos por UrbanTrips (la cantidad de servicios nuevos y cuántos de ellos resultan válidos, cúantos de estos son servicios con muy pocos puntos gps o con demasiado tiempo quietos, la distancia recorrida acumulada  originalmente y aquella que se obtiene de utilizar sólo los servicios válidos y la proporción de servicios original sin subdividir en otros por parte de UrbanTrips).  
+*  ``services_by_line_hour``: una tabla que resume por linea, dia y hora la cantidad de servicios ofertados.
+
+
+
 
+

urbantrips/datamodel/transactions.py

@@ -252,9 +252,10 @@ def renombrar_columnas_tablas(df, nombres_variables, postfijo):
         # get the name in the original df holding service type data
         service_id_col_name = nombres_variables.pop('servicios_gps')
 
-        start_service_value = nombres_variables.pop('valor_inicio_servicio')
-        finish_service_value = nombres_variables.pop(
-            'valor_fin_servicio')
+        # get the values for services start and finish
+        gps_config = leer_configs_generales()
+        start_service_value = gps_config['valor_inicio_servicio']
+        finish_service_value = gps_config['valor_fin_servicio']
 
         # create a replace values dict
         service_id_values = {