pipeline.src.flows.controls
===========================

.. py:module:: pipeline.src.flows.controls


Functions
---------

.. autoapisummary::

   pipeline.src.flows.controls.extract_controls
   pipeline.src.flows.controls.extract_catch_controls
   pipeline.src.flows.controls.extract_ports
   pipeline.src.flows.controls.extract_fao_areas
   pipeline.src.flows.controls.transform_catch_controls
   pipeline.src.flows.controls.transform_controls
   pipeline.src.flows.controls.compute_controls_fao_areas
   pipeline.src.flows.controls.compute_controls_facade
   pipeline.src.flows.controls.merge_controls_data
   pipeline.src.flows.controls.make_missions_actions_and_missions_control_units
   pipeline.src.flows.controls.load_missions_and_missions_control_units
   pipeline.src.flows.controls.load_mission_actions
   pipeline.src.flows.controls.controls_flow


Module Contents
---------------

.. py:function:: extract_controls(number_of_months: int) -> pandas.DataFrame

   Extracts controls data from FMC database for the specified number of months, going
   back at most to January 1st 2013.

   :param number_of_months: number of months of controls data to extract, going
                            backwards from the present. If the computed start date of the extraction is
                            before January 1st 2013, the data will be extracted from January 1st 2013 to
                            the present.
   :type number_of_months: int

   :returns: DataFrame with controls data.
   :rtype: pd.DataFrame


.. py:function:: extract_catch_controls() -> pandas.DataFrame

.. py:function:: extract_ports() -> pandas.DataFrame

   Extracts ports as a `DataFrame`.

   :returns: DataFrame of ports.
   :rtype: pd.DataFrame


.. py:function:: extract_fao_areas() -> geopandas.GeoDataFrame

   Extracts FAO areas as a `GeoDataFrame`.

   :returns: GeoDataFrame of FAO areas.
   :rtype: gpd.GeoDataFrame


.. py:function:: transform_catch_controls(catch_controls: pandas.DataFrame) -> pandas.DataFrame

.. py:function:: transform_controls(controls: pandas.DataFrame)

.. py:function:: compute_controls_fao_areas(controls: pandas.DataFrame, fao_areas: geopandas.GeoDataFrame, ports: pandas.DataFrame) -> pandas.DataFrame

   Compute the FAO area(s) of controls.

   For controls with a location (latitude and longitude), the FAO area of the location
   of the control is returned.

   For controls with a port (locode), the FAO area(s) of the port are taken.

   NB : controls that have no fao_area (because they lack location or port information
   or because their location / ports does not belong to an FAO area) will not be
   included in the result.

   :param controls: controls with at least `id`, `latitude`, `longitude`
                    and `port_locode` columns
   :type controls: pd.DataFrame
   :param fao_areas: FAO areas with `f_code` column (and geometry)
   :type fao_areas: gpd.GeoDataFrame
   :param ports: ports with `locode` and `fao_areas` columns
   :type ports: pd.DataFrame

   :returns: controls with FAO areas added
   :rtype: pd.DataFrame


.. py:function:: compute_controls_facade(controls: pandas.DataFrame, facade_areas: geopandas.GeoDataFrame, ports: pandas.DataFrame) -> pandas.DataFrame

   Compute the facade of controls.

   For controls with a location (latitude and longitude), the facade of the
   location of the control is returned.

   For controls with a port (locode), the facade of the port is taken.

   NB : controls that have no facade (because they lack location or port information
   or because their location / ports does not belong to a facade area) will not be
   included in the result.

   :param controls: controls with at least `id`, `latitude`, `longitude`
                    and `port_locode` columns
   :type controls: pd.DataFrame
   :param facade_areas: facades with `facade` column (and
                        geometry)
   :type facade_areas: gpd.GeoDataFrame
   :param ports: ports with `locode` and `facade` columns
   :type ports: pd.DataFrame

   :returns: DataFrame with columns `id` and `facade`
   :rtype: pd.DataFrame


.. py:function:: merge_controls_data(controls: pandas.DataFrame, catch_controls: pandas.DataFrame, controls_fao_areas: pandas.DataFrame, controls_facade: pandas.DataFrame) -> pandas.DataFrame

.. py:function:: make_missions_actions_and_missions_control_units(controls: pandas.DataFrame) -> Tuple[pandas.DataFrame, pandas.DataFrame, pandas.DataFrame]

.. py:function:: load_missions_and_missions_control_units(missions: pandas.DataFrame, missions_control_units: pandas.DataFrame, loading_mode: str)

.. py:function:: load_mission_actions(mission_actions: pandas.DataFrame, loading_mode: str)

.. py:function:: controls_flow(loading_mode: str, number_of_months: int, extract_controls_fn: Callable = extract_controls, extract_catch_controls_fn: Callable = extract_catch_controls, load_missions_and_missions_control_units_fn: Callable = load_missions_and_missions_control_units)

   Controls flow - extracts and processes control data from FMC database

   :param loading_mode: Either "replace" or "upsert" mode for loading data
   :param number_of_months: Number of months of data to extract