Merge pull request #36 from antarctica/dataloader_docs_update

Dataloader docs update

docs/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: 30f730049513b06b62ef00a8243579cc
+config: 9721d97e1e55ef6dd749bf7a0aab04aa
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/html/_sources/index.rst.txt

@@ -2,15 +2,15 @@ Welcome to the MeshiPhi Manual Pages
 ======================================
 
 MeshiPhi is a tool for the discretisation of environmental data with a non uniform resolution based on the variance of
-the data. This software package has been developed by the **British Antarctic Survey** (BAS), initially as part of a
-route planning tool for the BAS research vessel RRS Sir David Attenborough, though it can be applied to any geospatial data.
-The software is written in Python and is open source. 
+the data. This software package has been developed by the **British Antarctic Survey** (BAS). It was initially designed
+as part of a `route planning tool <https://github.com/antarctica/PolarRoute>`_ for the BAS research vessel RRS Sir David
+Attenborough, although it can be applied to any geospatial data. The software is written in Python and is open source.
 
 The package contains limited plotting functionality, which is described in the :ref:`Mesh Plotting` section. For 
-extended plotting functionality, we recommend using the GeoPlot package, which is also developed by BAS. This is available at 
-the following GitHub repository: `GeoPlot <https://github.com/antarctica/GeoPlot>`_
+extended plotting functionality, we recommend using the GeoPlot package, which was also developed at BAS. This is
+available from the following GitHub repository: `GeoPlot <https://github.com/antarctica/GeoPlot>`_
 
-For more information on the project, please visit the `PolarRoute website <https://www.bas.ac.uk/project/autonomous-marine-operations-planning/>`_
+For more information on the project, please visit the `AMOP website <https://www.bas.ac.uk/project/autonomous-marine-operations-planning/>`_
 and follow our `GitHub repository <https://github.com/antarctica/meshiphi>`_.
 
 
@@ -24,7 +24,7 @@ Contents:
    :numbered:
 
    ./sections/Installation
-   ./sections/ipython_notebooks
+   ./sections/Examples
    ./sections/Command_line_interface
    ./sections/Code_overview
    ./sections/Configuration/Configuration_overview

docs/html/_sources/sections/Code_overview.rst.txt

@@ -5,14 +5,23 @@ Background
 
 Code Structure
 ##############
-The outline of this manual is to provide the user with all the tools that they need to run the software for a set of examples. We also hope that the background information supplied for each section allows the user to understand the methods used throughout this toolkit.
+The aim of this manual is to provide the user with all the tools that they need to run the software for a set of
+examples. We also hope that the background information supplied for each section allows the user to understand the
+methods used throughout this package.
 
 The separate stages of the codebase can be broken down into:
 
-1. :ref:`Dataloaders <dataloaders-overview>` - Reading in different datasets of differing types. Throughout this section we will outline the form that the input datasets should take and useful tips for pre-processing your data.
-2. :ref:`Mesh Construction <mesh_construction_overview>` - Generating a Digital Twin of the environmental conditions. In this section we outline the different Python classes that are used to construct a discretised representation across the user defined datasets, giving a coding background to the dynamic splitting of the mesh to finer resolution in regions of datasets that are spatially varying.
+1. :ref:`Dataloaders <dataloaders-overview>` - Reading in different datasets of differing types. Throughout this section
+we will outline the form that the input datasets should take and useful tips for pre-processing your data.
 
-Each stage of this pipeline makes use of a configuration file, found in the :ref:`Configuration Overview` section of the documentation
-and produces an output file, the form of which can be found in the :ref:`outputs` section of this document.
+2. :ref:`Mesh Construction <mesh_construction_overview>` - Generating a non-uniform mesh representation of the
+environmental conditions. In this section we outline the different Python classes that are used to construct a
+discretised representation of the user-defined datasets, giving a coding background to the dynamic splitting of the mesh
+to finer resolution in regions of spatially varying data.
 
-In addition to the main section of the codebase we have also developed a series of plotting classes that allows the user to generate interactive maps and static figures for the Mesh Features. These can be found in the `Plotting` section later in the manual.
+Each stage of this process makes use of a configuration file, found in the :ref:`Configuration Overview` section of the
+documentation and produces an output file, the form of which can be found in the :ref:`outputs` section.
+
+In addition to the core functionality of the package we have also developed a set of plotting classes that allow the user
+to generate both interactive maps and static figures of the Mesh outputs. These can be found in the :ref:`Mesh Plotting`
+section later in the manual.

docs/html/_sources/sections/Command_line_interface.rst.txt

@@ -2,16 +2,17 @@
 Command Line Interface
 ###############################
 
-The MeshiPhi package provides CLI entry points, used to build a digital environment from a hetrogeneous collection of source data. 
-This digital environment file (mesh) may then be exported to a variety of file formats for use in other systems, such as GIS software. 
-The produced mesh file also interfaces directly with PolarRoute, BAS's route planning software to provide optinal routes through mesh.
+The MeshiPhi package provides CLI entry points, used to build a digital environment from a heterogeneous collection of
+source data. This digital environment file (mesh) can then be exported to a variety of file formats for use in other
+systems, such as GIS software. The produced mesh file also interfaces directly with `PolarRoute <https://github.com/antarctica/PolarRoute>`_,
+BAS's route planning software, to provide optimal routes for a vehicle travelling through the mesh.
 
 ^^^^^^^^^^^
 create_mesh
 ^^^^^^^^^^^
 
-The *create_mesh* entry point builds a digital environment file from a collection of source data, which can then be used
-by the vessel performance modeller and route planner. 
+The *create_mesh* entry point builds a digital environment file from a collection of source data, which can then be saved
+to a file for visualisation or use in other software.
 
 ::
 
@@ -24,7 +25,7 @@ positional arguments:
     config : A configuration file detailing how to build the digital environment. JSON parsable
 
 The format of the required *<config.json>* file can be found in the :ref:`configuration - mesh construction` section of the documentation.
-There are also example configuration files available in the directory :code:`examples/environment_config/grf_example.config.json`
+There are also example configuration files available in the directory :code:`examples/environment_config/grf_example.config.json` on GitHub.
 
 optional arguments:
 
@@ -71,7 +72,7 @@ optional arguments:
     -o : output location
     -format_conf: configuration file for output format (required for TIF export, optional for GEOJSON)
 
-the format of the *<format_conf.json>* file required for .tif export is as follows:
+an example of the format of the *<format_conf.json>* file required for .tif export is as follows:
 
 ::
 
@@ -101,15 +102,16 @@ where the variables are as follows:
 The color_conf.txt contains 4 columns per line: the data_name value and the 
 corresponding red, green, blue value between 0 and 255.
 
-When using the *-format_conf* option for GEOJSON output the only variable required is the **data_name**. This specifies which of the data layers you want to export as a single GEOJSON file.
+When using the *-format_conf* option for GEOJSON output the only variable required is the **data_name**. This specifies
+which of the data layers you want to export as a single GEOJSON file.
 
 ^^^^^^^^^^^^
 rebuild_mesh
 ^^^^^^^^^^^^
 
 Once a mesh has been built using the :ref:`create_mesh` command the *rebuild_mesh* command allows a user to rebuild it based on the
 original configs stored within the mesh file. This is primarily useful for debugging or to update old meshes produced with an older version
-of the package. Running this command will also reapply any vessel performance simulations, if these were run on the original mesh.
+of the package.
 
 ::
 
@@ -128,8 +130,8 @@ plot_mesh (GeoPlot)
 ^^^^^^^^^^^^^^^^^^^^^
 Meshes produced at any stage in the route planning process can be visualised using the GeoPlot 
 library found at the relevant `GitHub page <https://github.com/antarctica/GeoPlot>`_. Meshes and routes can also be
-plotted in other GIS software such as QGIS by exporting the mesh to a common format such as .geojson or .tif using
-the :ref:`export_mesh` command.
+plotted in other GIS software such as QGIS or ArcGIS by exporting the mesh to a common format such as .geojson or .tif
+using the :ref:`export_mesh` command.
 
 ::
 

docs/html/_sources/sections/Configuration/Configuration_overview.rst.txt

@@ -2,14 +2,11 @@
 Configuration Overview
 ######################################
 
-In this section we will outline the standard structure for a configuration file used in 
-all portions of the PolarRoute software package.
+In this section we outline the standard structure for the configuration file used as the starting point for generating
+an environmental mesh using the MeshiPhi software package. These configuration files are written in JSON, can be passed
+to MeshiPhi as command-line arguments or through a Python interpreter.
 
-Each stage of the route-planning process is configured by a separate configuration file. 
-The configuration files are written in JSON, and are passed to each stage of the 
-route-planning process as command-line arguments or through a Python script.
-
-Example configuration files are provided in the `config` directory.
+Example configuration files are provided in the :code:`examples/environment_config/` directory on GitHub.
 
 Descriptions of the configuration options for the Mesh Construction can be found in 
 the :ref:`Configuration - Mesh Construction` section of the documentation.
@@ -24,11 +21,9 @@ the :ref:`Configuration - Mesh Construction` section of the documentation.
 Config Validation
 ^^^^^^^^^^^^^^^^^
 
-At each major stage of the code (mesh construction, vessel performance modelling, 
-and route planning), the configs supplied are validated using a template JSON Schema.
-These schema check that the correct keywords and datatypes are provided in the config 
-JSON's, as well as the waypoints CSV file. They also perform rudimentary checks on the
-values to ensure that they make sense (e.g. startTime is before endTime).
+The configs supplied by the user are validated using a template JSON Schema. This schema checks that the correct
+keywords and datatypes are provided in the config JSON file. They also perform rudimentary checks on the values within
+the config to ensure that they make sense (e.g. start_time is before end_time).
 
 .. automodule:: meshiphi.config_validation.config_validator
    :members:

docs/html/_sources/sections/Configuration/Mesh_construction_config.rst.txt

@@ -2,13 +2,11 @@
 Configuration - Mesh Construction
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Below is a full configuration file for building an environmental mesh using 
-data generated from gaussian random fields. This configuration file generates 
-the feilds 'SIC', 'elevation', 'thickness', 'density', 'uC,vC' (currents) and 
-'u10,v10' (winds). The full configuration file is available in the file location 
-:code:`examples/environment_config/grf_example.config.json`. Other example 
-configuration files are also available at this location, including configuration files 
-which build meshes using real data-sets.
+Below is a full configuration file for building an environmental mesh using synthetic data generated from Gaussian
+Random Fields (GRFs). This configuration file generates the fields 'SIC', 'elevation', 'thickness', 'density', 'uC, vC'
+(currents) and 'u10, v10' (winds). The full configuration file is available in the file location
+:code:`examples/environment_config/grf_example.config.json` on GitHub. Other example configuration files are also
+available at this location, including configuration files which build meshes using real datasets.
 
 
 .. code-block:: json
@@ -214,16 +212,20 @@ which build meshes using real data-sets.
         }
     }
 
-The configuration file used for mesh construction contains information required to build the discretised environment in which the route planner
-operates. Information here dictates the region in which the mesh is constructed, the data contained within
-the mesh and how the mesh is split to a non-uniform resolution. The configuration file used to generate a mesh is stored in a section titled 'Mesh_info'
+The configuration file used for mesh construction contains information required to build a discretised model of the environment.
+Information here dictates the region in which the mesh is constructed, the data contained within the mesh and how the
+mesh is split to a non-uniform resolution. The configuration file used to generate a mesh is stored in the output mesh json
+in a section titled 'mesh_info'.
 
-The 'Mesh_info' section of the configuration file contains three primary sections:
+The mesh configuration file contains three primary sections:
 
 ################
 Region
 ################
-The region section gives detailed information for the construction of the Discrete Mesh. The main definitions are the bounding region and temporal portion of interest (`longMin`, `latMin`, `longMax`, `latMax`, `startTime`, `endTime`), but also the starting shape of the spatial grid cell boxes (`cellWidth`, `cellHeight`) is defined before splitting is applied. Further detail on each parameter is given below:
+The region section gives detailed information for the construction of the Discrete Mesh. The main definitions are the
+bounding region and temporal portion of interest (:code:`long_min`, :code:`lat_min`, :code:`long_max`, :code:`lat_max`, :code:`start_time`, :code:`end_time`), but
+also the starting shape of the spatial grid cell boxes (:code:`cell_width`, :code:`cell_height`) is defined before splitting is
+applied. Further detail on each parameter is given below:
 
 ::
 
@@ -240,10 +242,10 @@ The region section gives detailed information for the construction of the Discre
     
 where the variables are as follows:
 
-* **long_min**      *(float, degrees)*      : Minimum Longitude Edge Mesh
-* **long_max**      *(float, degrees)*      : Maximum Longitude Edge Mesh
-* **lat_min**       *(float, degrees)*      : Minimum Latitude Edge Mesh  
-* **lat_max**       *(float, degrees)*      : Maximum Latitude Edge Mesh  
+* **long_min**      *(float, degrees)*      : Minimum Longitude Edge of the Mesh
+* **long_max**      *(float, degrees)*      : Maximum Longitude Edge of the Mesh
+* **lat_min**       *(float, degrees)*      : Minimum Latitude Edge of the Mesh
+* **lat_max**       *(float, degrees)*      : Maximum Latitude Edge of the Mesh
 * **start_time**    *(string, 'YYYY-mm-dd')*   : Start Datetime of Time averaging 
 * **end_time**      *(string, 'YYYY-mm-dd')*   : End Datetime of Time averaging   
 * **cell_width**    *(float, degrees)*      : Initial Cell Box Width prior to splitting 
@@ -261,8 +263,8 @@ where the variables are as follows:
 Data Sources
 ############
 
-The 'Data Sources' section of the configuration file dictates which information will be added to the
-mesh when constructed. Each item in the list of data sources represents a single data set to be added
+The 'data_sources' section of the configuration file defines which information will be added to the
+mesh when constructed. Each item in the list of data sources represents a single dataset to be added
 to the mesh.
 
 ::
@@ -392,7 +394,3 @@ where the variables are as follows:
 
 * **split_depth** *(float)* : The number of times the MeshBuilder will sub-divide each initial cellbox (subject to satisfying the splitting conditions of each data source)
 * **minimum_datapoints** *(float)* : The minimum number of datapoints a cellbox must contain for each value type to be able to split
-
-
-
-

docs/html/_sources/sections/Dataloaders/AddingDataloaders.rst.txt

@@ -6,7 +6,7 @@ Adding New Dataloaders
 Adding to the repository
 ------------------------
 
-Each dataloader is to be implemented as a separate object for the Environmental mesh to interface with. 
+Each dataloader is to be implemented as a separate object for the environmental mesh to interface with.
 The general workflow for creating a new dataloader is as follows:
 
 #. Choose an appropriate dataloader type (see :ref:`Dataloader Types`).

docs/html/_sources/sections/Dataloaders/lut/implemented/Density.rst.txt

@@ -6,6 +6,8 @@ Density values were taken from the paper 'Thickness distribution of Antarctic se
 (Worby, A.P. et al.). This paper took a density model from the paper 'Structure, principal 
 properties and strength of Antarctic sea ice' (Buynitskiy, V.K.). 
 
+Name in config: :code:`'density'`
+
 Data is generated using the values from this paper, and so no data file is available for download.
 
 .. automodule:: meshiphi.dataloaders.lut.density

docs/html/_sources/sections/Dataloaders/lut/implemented/LutCSV.rst.txt

@@ -7,7 +7,9 @@ it into a data source for mesh construction. It was primarily used in testing
 for loading dummy data to test performance. As such, there is no data source 
 for this dataloader. The CSV must have two columns: 'geometry' and 'data_name'.
 'geometry' must have that title, and is a shapely wkt string. data_name can have 
-any name, and is just the value that is associated with the polygon. 
+any name, and is just the value that is associated with the polygon.
+
+Name in config: :code:`'lut_csv'`
 
 .. automodule:: meshiphi.dataloaders.lut.lut_csv
    :special-members: __init__

docs/html/_sources/sections/Dataloaders/lut/implemented/LutGeoJSON.rst.txt

@@ -8,6 +8,8 @@ for loading dummy data to test performance. When using this dataloader, a value
 should be provided in the mesh config file that specifies the value and data_name 
 that the polygons save. The keyword in the config params is 'value'.
 
+Name in config: :code:`'lut_geojson'`
+
 .. automodule:: meshiphi.dataloaders.lut.lut_geojson
    :special-members: __init__
    :members:

docs/html/_sources/sections/Dataloaders/lut/implemented/Scotland_NCMPA.rst.txt

@@ -2,7 +2,9 @@
 Scotland NCMPA Dataloader
 *************************
 
-GeoJSON files are provided by the Scottish government for Nature Conservation Marine Protected Areas. 
+GeoJSON files are provided by the Scottish government for Nature Conservation Marine Protected Areas.
+
+Name in config: :code:`'scotland_ncmpa'`
 
 Data can be downloaded from `here <https://www.data.gov.uk/dataset/67572936-18dc-4180-af74-39b088b6fb19/nature-conservation-marine-protected-areas-mpa>`_
 

docs/html/_sources/sections/Dataloaders/lut/implemented/Thickness.rst.txt

@@ -3,7 +3,9 @@ Thickness Dataloader
 ********************
 
 Thickness values were taken from the paper 'Thickness distribution of Antarctic sea ice'
-(Worby, A.P. et al.). 
+(Worby, A.P. et al.).
+
+Name in config: :code:`'thickness'`
 
 Data is generated using the values from this paper, and so no
 data file is available for download.

docs/html/_sources/sections/Dataloaders/overview.rst.txt

@@ -73,7 +73,7 @@ To look at specific abstract dataloaders, use the following links:
 - :ref:`abstract-vector-dataloader`
 - :ref:`abstract-lut-dataloader`
 
-These are the templates to be used when implementing new dataloaders into PolarRoute. 
+These are the templates to be used when implementing new dataloaders into MeshiPhi.
 They have been split into three separate categories: Scalar, Vector, and LUT, detailed in `Dataloader Types`_.
 The abstract classes generalise the methods used by each dataloader type to produce outputs
 that the Environmental Mesh can retrieve via the  :ref:`dataloader interface<dataloader-interface>`. 

docs/html/_sources/sections/Dataloaders/scalar/implemented/AMSR.rst.txt

@@ -12,6 +12,8 @@ with :code:`pandas` calculating mean values differently depending on how the
 data is loaded. This caused issues with the regression tests passing. 
 This issue will be rectified soon by updating the regression tests.
 
+Name in config: :code:`'amsr'`
+
 Data can be downloaded from `here <https://seaice.uni-bremen.de/data-archive/>`_