-
-

9. Mesh Plotting

-
+
+

9. Mesh Plotting

+

As well as the interactive plotting functionality provided by GeoPlot, +Meshiphi also contains a built-in plotting class mesh_plotter that allows the user to produce static plots of a +given environmental mesh.

+
class meshiphi.mesh_plotting.mesh_plotter.MeshPlotter(mesh_json, figscale=10)

Object for plotting mesh json files using matplotlib and cartopy.

diff --git a/docs/source/index.rst b/docs/source/index.rst index 03289020..c1e183c8 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -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 `_ 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 `_ +extended plotting functionality, we recommend using the GeoPlot package, which was also developed at BAS. This is +available from the following GitHub repository: `GeoPlot `_ -For more information on the project, please visit the `PolarRoute website `_ +For more information on the project, please visit the `AMOP website `_ and follow our `GitHub repository `_. @@ -24,7 +24,7 @@ Contents: :numbered: ./sections/Installation - ./sections/ipython_notebooks + ./sections/Examples ./sections/Command_line_interface ./sections/Code_overview ./sections/Configuration/Configuration_overview diff --git a/docs/source/sections/Code_overview.rst b/docs/source/sections/Code_overview.rst index 075ba939..ad48b815 100644 --- a/docs/source/sections/Code_overview.rst +++ b/docs/source/sections/Code_overview.rst @@ -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 ` - 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 ` - 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 ` - 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 ` - 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. \ No newline at end of file +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. \ No newline at end of file diff --git a/docs/source/sections/Command_line_interface.rst b/docs/source/sections/Command_line_interface.rst index 79d90809..6274b798 100644 --- a/docs/source/sections/Command_line_interface.rst +++ b/docs/source/sections/Command_line_interface.rst @@ -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 `_, +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 ** 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 ** file required for .tif export is as follows: +an example of the format of the ** file required for .tif export is as follows: :: @@ -101,7 +102,8 @@ 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 @@ -109,7 +111,7 @@ 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 `_. 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. :: diff --git a/docs/source/sections/Configuration/Configuration_overview.rst b/docs/source/sections/Configuration/Configuration_overview.rst index 9f0d0fa5..12f9705f 100644 --- a/docs/source/sections/Configuration/Configuration_overview.rst +++ b/docs/source/sections/Configuration/Configuration_overview.rst @@ -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: \ No newline at end of file diff --git a/docs/source/sections/Configuration/Mesh_construction_config.rst b/docs/source/sections/Configuration/Mesh_construction_config.rst index 52e1772e..b9335ba0 100644 --- a/docs/source/sections/Configuration/Mesh_construction_config.rst +++ b/docs/source/sections/Configuration/Mesh_construction_config.rst @@ -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 - - - - diff --git a/docs/source/sections/Dataloaders/AddingDataloaders.rst b/docs/source/sections/Dataloaders/AddingDataloaders.rst index 39dc3cb5..568cd652 100644 --- a/docs/source/sections/Dataloaders/AddingDataloaders.rst +++ b/docs/source/sections/Dataloaders/AddingDataloaders.rst @@ -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`). diff --git a/docs/source/sections/Dataloaders/lut/implemented/Density.rst b/docs/source/sections/Dataloaders/lut/implemented/Density.rst index 104d7358..28de1191 100644 --- a/docs/source/sections/Dataloaders/lut/implemented/Density.rst +++ b/docs/source/sections/Dataloaders/lut/implemented/Density.rst @@ -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 diff --git a/docs/source/sections/Dataloaders/lut/implemented/LutCSV.rst b/docs/source/sections/Dataloaders/lut/implemented/LutCSV.rst index 1e69622c..6c2b8b12 100644 --- a/docs/source/sections/Dataloaders/lut/implemented/LutCSV.rst +++ b/docs/source/sections/Dataloaders/lut/implemented/LutCSV.rst @@ -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__ diff --git a/docs/source/sections/Dataloaders/lut/implemented/LutGeoJSON.rst b/docs/source/sections/Dataloaders/lut/implemented/LutGeoJSON.rst index 3c3616b0..1c0805f3 100644 --- a/docs/source/sections/Dataloaders/lut/implemented/LutGeoJSON.rst +++ b/docs/source/sections/Dataloaders/lut/implemented/LutGeoJSON.rst @@ -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: \ No newline at end of file diff --git a/docs/source/sections/Dataloaders/lut/implemented/Scotland_NCMPA.rst b/docs/source/sections/Dataloaders/lut/implemented/Scotland_NCMPA.rst index d55f3774..39677c5c 100644 --- a/docs/source/sections/Dataloaders/lut/implemented/Scotland_NCMPA.rst +++ b/docs/source/sections/Dataloaders/lut/implemented/Scotland_NCMPA.rst @@ -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 `_ diff --git a/docs/source/sections/Dataloaders/lut/implemented/Thickness.rst b/docs/source/sections/Dataloaders/lut/implemented/Thickness.rst index cad4b83f..8d0db254 100644 --- a/docs/source/sections/Dataloaders/lut/implemented/Thickness.rst +++ b/docs/source/sections/Dataloaders/lut/implemented/Thickness.rst @@ -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. diff --git a/docs/source/sections/Dataloaders/overview.rst b/docs/source/sections/Dataloaders/overview.rst index 1b8dd335..ec88fe71 100644 --- a/docs/source/sections/Dataloaders/overview.rst +++ b/docs/source/sections/Dataloaders/overview.rst @@ -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`. diff --git a/docs/source/sections/Dataloaders/scalar/implemented/AMSR.rst b/docs/source/sections/Dataloaders/scalar/implemented/AMSR.rst index be211cd6..a4dfb701 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/AMSR.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/AMSR.rst @@ -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 `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/BSOSEDepth.rst b/docs/source/sections/Dataloaders/scalar/implemented/BSOSEDepth.rst index e912d79a..6c03eef5 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/BSOSEDepth.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/BSOSEDepth.rst @@ -12,9 +12,11 @@ From their website: observations. As such, it provides a quantitatively useful climatology of the mean-state of the Southern Ocean. +Name in config: :code:`'bsose_depth'` + Data can be downloaded from `here `_ -Note: This dataloader may not work as is for new data downloaded, it has been internally collated into +Note: This dataloader may not work "as is" for new data downloaded, it has been internally collated into a more easily ingestable format. .. automodule:: meshiphi.dataloaders.scalar.bsose_depth diff --git a/docs/source/sections/Dataloaders/scalar/implemented/BSOSESeaIce.rst b/docs/source/sections/Dataloaders/scalar/implemented/BSOSESeaIce.rst index 7baba88c..63d56f22 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/BSOSESeaIce.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/BSOSESeaIce.rst @@ -9,7 +9,9 @@ SOSE project led by Mazloff at the Scripps Institution of Oceanography. From their website: The Southern Ocean State Estimate (SOSE) is a model-generated best fit to Southern Ocean observations. As such, it provides a quantitatively useful climatology of the mean-state - of the Southern Ocean. + of the Southern Ocean. + +Name in config: :code:`'bsose_sic'` Data can be downloaded from `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/BalticSeaIce.rst b/docs/source/sections/Dataloaders/scalar/implemented/BalticSeaIce.rst index b5c90bd9..2fea523a 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/BalticSeaIce.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/BalticSeaIce.rst @@ -9,6 +9,8 @@ From their webpage: The parameters are based on ice chart produced on daily basis during the Baltic Sea ice season and show the ice concentration in a 1 km grid. +Name in config: :code:`'baltic_sic'` + Data can be downloaded from `here `_ .. automodule:: meshiphi.dataloaders.scalar.baltic_sea_ice diff --git a/docs/source/sections/Dataloaders/scalar/implemented/BinaryGRF.rst b/docs/source/sections/Dataloaders/scalar/implemented/BinaryGRF.rst index 2ac5f044..7efa3d27 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/BinaryGRF.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/BinaryGRF.rst @@ -30,4 +30,6 @@ only True/False. It is useful for generating land masks. } } -See the :ref:`Scalar GRF page` for documentation on the dataloader \ No newline at end of file +Name in config: :code:`'binary_grf'` + +See the :ref:`Scalar GRF page` for documentation on the dataloader diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ECMWFSigWaveHeight.rst b/docs/source/sections/Dataloaders/scalar/implemented/ECMWFSigWaveHeight.rst index 5b1c81fb..4ee4a2c1 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ECMWFSigWaveHeight.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ECMWFSigWaveHeight.rst @@ -11,6 +11,8 @@ activities include delivering advanced training and assisting the WMO in implementing its programmes. (description taken from `here `_) +Name in config: :code:`'ecmwf_sig_wave_height'` + Data can be downloaded from `this link `_ This dataloader is for the grib2 files. diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5MaxWaveHeight.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5MaxWaveHeight.rst index 65a0f72e..09790240 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5MaxWaveHeight.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5MaxWaveHeight.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_max_wave_height'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5SigWaveHeight.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5SigWaveHeight.rst index 45ba50e4..6762fe88 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5SigWaveHeight.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5SigWaveHeight.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_sig_wave_height'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WaveDirection.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WaveDirection.rst index 21f7116a..ac559419 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WaveDirection.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WaveDirection.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wave_dir'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WavePeriod.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WavePeriod.rst index 002e0697..4176caab 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WavePeriod.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WavePeriod.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wave_period'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindDirection.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindDirection.rst index f036336b..ccbcdf6a 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindDirection.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindDirection.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wind_dir'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindMagnitude.rst b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindMagnitude.rst index 647359ef..0735f36c 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindMagnitude.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ERA5WindMagnitude.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wind_mag'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/GEBCO.rst b/docs/source/sections/Dataloaders/scalar/implemented/GEBCO.rst index 4e33be39..4e1d17d7 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/GEBCO.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/GEBCO.rst @@ -4,7 +4,9 @@ GEBCO Dataloader The General Bathymetric Chart of the Oceans (GEBCO) is a publicly available bathymetric chart of the Earth's oceans. It is a common resource used by -ocean scientists, amongst others. +ocean scientists, amongst others. + +Name in config: :code:`'gebco'` Data can be downloaded from `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/IceNet.rst b/docs/source/sections/Dataloaders/scalar/implemented/IceNet.rst index aaca3122..a2fea4fd 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/IceNet.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/IceNet.rst @@ -11,6 +11,8 @@ at the British Antarctic Survey. From the website: trained on climate simulations and observational data to forecast the next 6 months of monthly-averaged sea ice concentration maps. +Name in config: :code:`'icenet'` + Data for IceNet V1 is available from `here `_ Data for IceNet V2 is not publicly available. diff --git a/docs/source/sections/Dataloaders/scalar/implemented/MODIS.rst b/docs/source/sections/Dataloaders/scalar/implemented/MODIS.rst index 50b0857c..81168511 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/MODIS.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/MODIS.rst @@ -9,6 +9,8 @@ From their website: MODIS are viewing the entire Earth's surface every 1 to 2 days, acquiring data in 36 spectral bands, or groups of wavelengths. +Name in config: :code:`'modis'` + Information on where to download their data products can be found `here `_ diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ScalarCSV.rst b/docs/source/sections/Dataloaders/scalar/implemented/ScalarCSV.rst index 89d8720a..3c59d02e 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ScalarCSV.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ScalarCSV.rst @@ -7,6 +7,8 @@ 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. +Name in config: :code:`'scalar_csv'` + .. automodule:: meshiphi.dataloaders.scalar.scalar_csv :special-members: __init__ :members: \ No newline at end of file diff --git a/docs/source/sections/Dataloaders/scalar/implemented/ScalarGRF.rst b/docs/source/sections/Dataloaders/scalar/implemented/ScalarGRF.rst index 053c0f54..a2da6753 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/ScalarGRF.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/ScalarGRF.rst @@ -7,6 +7,8 @@ Scalar GRF Dataloader Produces a gaussian random field of scalar values, useful for producing artificial, yet somewhat realistic values for real-world variables. +Name in config: :code:`'scalar_grf'` + Can be used to generate :ref:`binary masks`. For vector fields, see the :ref:`Vector GRF page`. diff --git a/docs/source/sections/Dataloaders/scalar/implemented/visual_iced.rst b/docs/source/sections/Dataloaders/scalar/implemented/visual_iced.rst index 7f910ed3..8328bd12 100644 --- a/docs/source/sections/Dataloaders/scalar/implemented/visual_iced.rst +++ b/docs/source/sections/Dataloaders/scalar/implemented/visual_iced.rst @@ -15,6 +15,8 @@ Values between 0 and 100 are generated by the aggregation of the 0s and 1s withi The visual_iced dataloader only supports loading in single files, as the visual_iced datasets are not temporally continuous within a given boundary. +Name in config: :code:`'visual_iced'` + .. automodule:: meshiphi.dataloaders.scalar.visual_iced :special-members: __init__ :members: diff --git a/docs/source/sections/Dataloaders/vector/implemented/BalticCurrent.rst b/docs/source/sections/Dataloaders/vector/implemented/BalticCurrent.rst index b36484bb..59f3363d 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/BalticCurrent.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/BalticCurrent.rst @@ -12,6 +12,8 @@ From their webpage: and monthly means, are salinity, temperature, horizontal current components, mixed layer depth, bottom salinity and bottom temperature. +Name in config: :code:`'baltic_currents'` + Data can be downloaded from `here `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/DUACS.rst b/docs/source/sections/Dataloaders/vector/implemented/DUACS.rst index c71b2f9f..96f714e1 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/DUACS.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/DUACS.rst @@ -12,7 +12,9 @@ From their website: available. Part of the processing is fitted to the Global Ocean. The product gives additional variables (i.e. Absolute Dynamic Topography and geostrophic currents). -Near real-time data can be downloaded from `here `_. +Name in config: :code:`'duacs_currents'` + +Near real-time data can be downloaded from `here `_. Reanalysis data can be downloaded from `here. `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/ERA5WaveDirection.rst b/docs/source/sections/Dataloaders/vector/implemented/ERA5WaveDirection.rst index a82d31f0..2e773bed 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/ERA5WaveDirection.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/ERA5WaveDirection.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wave_direction'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/ERA5Wind.rst b/docs/source/sections/Dataloaders/vector/implemented/ERA5Wind.rst index 9cbc175b..e5e5c72e 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/ERA5Wind.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/ERA5Wind.rst @@ -13,6 +13,8 @@ From their website: surface up to a height of 80km. ERA5 includes information about uncertainties for all variables at reduced spatial and temporal resolutions. +Name in config: :code:`'era5_wind'` + Instructions for how to download their data products are available `here `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/NorthSeaCurrent.rst b/docs/source/sections/Dataloaders/vector/implemented/NorthSeaCurrent.rst index c3eb4db8..73ac01b7 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/NorthSeaCurrent.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/NorthSeaCurrent.rst @@ -6,6 +6,8 @@ North Atlantic Ocean currents are provided by the Proudman Oceanographic Laborat Coastal-Ocean Modelling System (POLCOMS). Their dataset was generated by the UK National Oceanography Centre, Liverpool. +Name in config: :code:`'northsea_currents'` + More information on where to download the data is available `here `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/ORAS5Current.rst b/docs/source/sections/Dataloaders/vector/implemented/ORAS5Current.rst index ddc7ba1f..df246f58 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/ORAS5Current.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/ORAS5Current.rst @@ -13,6 +13,8 @@ From their website: OCEAN5 ocean analysis-reanalysis system. This system comprises 5 ensemble members from which one member is published in this catalogue entry. +Name in config: :code:`'oras5_currents'` + Data can be downloaded from `here `_ .. automodule:: meshiphi.dataloaders.vector.oras5_current diff --git a/docs/source/sections/Dataloaders/vector/implemented/SOSE.rst b/docs/source/sections/Dataloaders/vector/implemented/SOSE.rst index 5f456e06..5eeab27e 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/SOSE.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/SOSE.rst @@ -8,7 +8,9 @@ ocean current vectors of the southern ocean. It is a project led by Mazloff at t From their website: The Southern Ocean State Estimate (SOSE) is a model-generated best fit to Southern Ocean observations. As such, it provides a quantitatively useful climatology of the mean-state - of the Southern Ocean. + of the Southern Ocean. + +Name in config: :code:`'sose'` Data can be downloaded from `here `_ diff --git a/docs/source/sections/Dataloaders/vector/implemented/VectorCSV.rst b/docs/source/sections/Dataloaders/vector/implemented/VectorCSV.rst index 71ce308e..f4ff33ba 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/VectorCSV.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/VectorCSV.rst @@ -7,6 +7,8 @@ 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. +Name in config: :code:`'vector_csv'` + .. automodule:: meshiphi.dataloaders.vector.vector_csv :special-members: __init__ :members: \ No newline at end of file diff --git a/docs/source/sections/Dataloaders/vector/implemented/VectorGRF.rst b/docs/source/sections/Dataloaders/vector/implemented/VectorGRF.rst index fb16a9bb..65471d69 100644 --- a/docs/source/sections/Dataloaders/vector/implemented/VectorGRF.rst +++ b/docs/source/sections/Dataloaders/vector/implemented/VectorGRF.rst @@ -9,6 +9,8 @@ artificial, yet somewhat realistic values for real-world variables. Values are broken down into `x` and `y` components, and saved in two columns in the final dataframe. +Name in config: :code:`'vector_grf'` + Can be used to generate :ref:`binary masks`. For scalar fields, see the :ref:`Vector GRF page`. diff --git a/docs/html/_sources/sections/ipython_notebooks.rst.txt b/docs/source/sections/Examples.rst similarity index 59% rename from docs/html/_sources/sections/ipython_notebooks.rst.txt rename to docs/source/sections/Examples.rst index 3f251052..e7925b96 100644 --- a/docs/html/_sources/sections/ipython_notebooks.rst.txt +++ b/docs/source/sections/Examples.rst @@ -4,18 +4,18 @@ Examples Digital environment files (meshes) can be created using the MeshiPhi package, either through the command line interface (CLI) or through the python terminal. This section will provide examples of how to create a digital -environment file using the python terminal. +environment file using Python. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Creating the digital environment. +Creating the Digital Environment. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -A configuration file is needed to initialise the **`Mesh`** object which forms the digital environment. This configuration file -is of the same format used in the :ref:`create_mesh` CLI entry-point, and may either be loaded from a *json* file or constructed -within the python terminal. +A configuration file is needed to initialise the **Mesh** object which forms the digital environment. This +configuration file is of the same format used in the :ref:`create_mesh` CLI entry-point, and may either be loaded from a +*json* file or constructed within a python interpreter. -Loading configuration from *json* file: +Loading configuration information from a *json* file: :: import json @@ -23,10 +23,10 @@ Loading configuration from *json* file: config = json.load(f) -The digital environment **`Mesh`** object can then be initialised. This mesh object will be constructed using parameters in it +The digital environment **Mesh** object can then be initialised. This mesh object will be constructed using parameters in it configuration file. This mesh object can be manipulated further, such as increasing its resolution through further splitting, adding additional data sources or altering is configuration parameters using functions listed in -the :ref:`Methods - Mesh Construction` section of the documentation. The digital environment **`Mesh`** object can then be cast to +the :ref:`Methods - Mesh Construction` section of the documentation. The digital environment **Mesh** object can then be cast to a json object and saved to a file. :: @@ -36,14 +36,15 @@ a json object and saved to a file. mesh = cg.to_json() -The **`Mesh`** object can be visualised using the **`GeoPlot`** package, also developed by BAS. This package is not included in the distribution -of MeshiPhi, but can be installed using the following command: +The **Mesh** object can be visualised using the `GeoPlot `_ package, also developed +by BAS. This package is not included in the distribution of MeshiPhi, but can be installed using the following command: :: pip install bas_geoplot -**`GeoPlot`** can be used to visualise the **`Mesh`** object using the following code in an iPython notebook: +**GeoPlot** can be used to visualise the **Mesh** object using the following code in an iPython notebook or +any python interpreter: :: @@ -55,16 +56,16 @@ of MeshiPhi, but can be installed using the following command: mp.Maps(mesh, 'MeshGrid', predefined='cx') mp.Maps(mesh, 'SIC', predefined='SIC') mp.Maps(mesh, 'Elevation', predefined='Elev', show=False) - mp.Vectors(mesh,'Currents - Mesh', show=False, predefined='Currents') + mp.Vectors(mesh,'Currents', show=False, predefined='Currents') mp.Vectors(mesh, 'Winds', predefined='Winds', show=False) mp.show() -The prior should produce a plot which shows the digital environment, including sea ice concentration, elevation, currents and winds. +The prior should produce a plot which shows the digital environment, including sea ice concentration, elevation, currents and wind. .. _splitting_figure: .. figure:: ./Figures/grf_example_mesh.png :align: center :width: 700 - *plot showing expected output of running bas_geoplot though a ipython notebook* \ No newline at end of file + *Plot showing the expected output of running bas_geoplot on the GRF example mesh provided* \ No newline at end of file diff --git a/docs/source/sections/Installation.rst b/docs/source/sections/Installation.rst index d261d6a2..baf5a9ad 100644 --- a/docs/source/sections/Installation.rst +++ b/docs/source/sections/Installation.rst @@ -2,21 +2,21 @@ Installation ************ -In this section we outline the necessary steps for installing the MeshiPhi software package. MeshiPhi requires a pre-existing installation of Python 3.8 or higher. +In this section we outline the necessary steps for installing the MeshiPhi software package. MeshiPhi requires a +pre-existing installation of Python 3.8 or higher. Installing MeshiPhi ##################### -The MeshiPhi software can be installed on Windows/Linux/MacOS by running one of the two following commands. +MeshiPhi can be installed from one of the following two sources: - -Pip: +from PyPI: :: pip install MeshiPhi -Github: +from Github: :: git clone https://github.com/antarctica/MeshiPhi.git @@ -27,8 +27,8 @@ Github: Installing GDAL (Optional) ########################## -The MeshiPhi software has GDAL as an optional requirement. It is only used when exporting TIFF images, -so if this is not useful to you, we would recommend steering clear. It is not trivial and is a common source of problems. +MeshiPhi has GDAL as an optional requirement. It is only used when exporting TIFF images, so if this is not useful to +you, we would recommend steering clear. It is not trivial and is a common source of problems. With that said, below are instructions for various operating systems. Windows diff --git a/docs/source/sections/Outputs.rst b/docs/source/sections/Outputs.rst index a1ccccd9..69461649 100644 --- a/docs/source/sections/Outputs.rst +++ b/docs/source/sections/Outputs.rst @@ -8,10 +8,7 @@ Outputs - Data Types The Mesh.json file ###################### -The first stage in the route planning pipeline is constructing a discrete -mesh of the environment in which the route planner can operate. Once this -mesh is constructed, it can then be exported as a json object and passed -down-stream to the vehicle specifics and route planner. An example +Once a mesh has been constructed using MeshiPhi, it can then be exported as a json object and saved to a file. An example of mesh construction and json object generation are as follows: :: @@ -64,7 +61,7 @@ where the parts of the json object can be understood as follows: cellboxes ========= -Each CellBox object within *cellboxes* in the outputted json object is of +Each CellBox object within **cellboxes** in the outputted json object is of the following form: :: @@ -99,14 +96,14 @@ Where the values within the CellBox represent the following: neighbour_graph =============== -For each CellBox in the *cellboxes* section of the outputted json object, there will be a -corresponding entry in the *neighbour_graph*. +For each CellBox in the **cellboxes** section of the json object, there will be a +corresponding entry in the **neighbour_graph**. .. note:: Once the vehicle accessibility conditions have been applied to the json object, this may no longer be true as inaccessible CellBoxes will be removed from *neighbour_graph* but will remain in *cellboxes* -Each entry in the *neighbour_graph* is of the following form: +Each entry in the **neighbour_graph** is of the following form: :: diff --git a/docs/source/sections/Plotting/mesh_plotting.rst b/docs/source/sections/Plotting/mesh_plotting.rst index f3c72d22..977350d7 100644 --- a/docs/source/sections/Plotting/mesh_plotting.rst +++ b/docs/source/sections/Plotting/mesh_plotting.rst @@ -2,6 +2,10 @@ Mesh Plotting ############################ +As well as the interactive plotting functionality provided by `GeoPlot `_, +Meshiphi also contains a built-in plotting class :code:`mesh_plotter` that allows the user to produce static plots of a +given environmental mesh. + .. automodule:: meshiphi.mesh_plotting.mesh_plotter :special-members: __init__ :members: \ No newline at end of file