docs: add basemap documentation and update index

docs/source/Basemap.rst

@@ -0,0 +1,82 @@
+Basemap Plot with Chartly
+=========================
+
+Chartly supports geographic visualisation through basemap plotting
+using the ``add_basemap(...)`` method. Users can display projected
+contour data on a world map while keeping the plotting interface
+simple and consistent with the rest of the package.
+
+Example
+-------
+
+The example below generates contour data, projects it onto a basemap,
+and visualises the result using Chartly's high-level interface.
+
+The following customization options can be passed through the ``customs``
+dictionary when creating a basemap plot:
+
+- ``proj`` (str): Map projection type (e.g., "eck4")
+- ``lon_0`` (int): Central longitude used during the basemap projection step
+- ``draw_countries`` (bool): Draw country borders
+- ``draw_parallels`` (bool): Draw latitude lines
+- ``draw_meridians`` (bool): Draw longitude lines
+- ``mask`` (array-like of bool): Boolean mask used to control hatched regions; required when ``hatch`` is enabled and ``hatch_customs.get("type") == "mask"``.
+- ``contour`` (bool): Enable contour plotting
+- ``hatch`` (bool): Enable hatching; when ``hatch_customs["type"] == "mask"``, hatched regions are determined by ``mask``.
+- ``hatch_customs`` (dict): Customization options for hatching (for example, ``{"type": "mask"}``).
+
+.. code-block:: python
+
+    import chartly
+    import numpy as np
+
+    super_axes_labels = {
+        "super_title": "Simple Usage Of Basemap Example",
+        "share_axes": False,
+    }
+
+    plot = chartly.Chart(super_axes_labels)
+
+    # Define grid size (latitude x longitude)
+    nlats, nlons = 73, 145
+
+    # Create latitude and longitude grids
+    delta = 2.0 * np.pi / (nlons - 1)
+    lats = 0.5 * np.pi - delta * np.indices((nlats, nlons))[0, :, :]
+    lons = delta * np.indices((nlats, nlons))[1, :, :]
+
+    # Generate sample data over the grid
+    wave = 0.75 * (np.sin(2.0 * lats) ** 8 * np.cos(4.0 * lons))
+    mean = 0.5 * np.cos(2.0 * lats) * ((np.sin(2.0 * lats)) ** 2 + 2.0)
+
+    # Combine into final dataset for plotting
+    z = wave + mean
+
+    plot.add_basemap(
+        lon=lons * 180.0 / np.pi,
+        lat=lats * 180.0 / np.pi,
+        values=z,
+        customs={
+            "proj": "eck4",
+            "lon_0": 0,
+            "draw_countries": True,
+            "draw_parallels": True,
+            "draw_meridians": True,
+            "mask": z < 0,
+            "contour": True,
+            "hatch": True,
+            "hatch_customs": {"type": "mask"},
+        },
+    )
+
+    plot.render()
+
+This example uses the Eckert IV projection and overlays contour data
+onto a global map. Masking and hatching are applied to highlight
+specific regions of the dataset, improving the visual distinction of
+key areas.
+
+.. image:: _static/basemap_plot_example.png
+    :alt: Basemap Plot Example
+    :align: center
+    :height: 500px

docs/source/index.rst

@@ -9,22 +9,26 @@ Chartly
 Overview
 --------
 
-**Chartly** is a simple plotting tool designed to help users create scientific plots with ease. Whether you want to test a distribution for normality or to plot contours onto a map of the globe, chartly can help you achieve your scientific plot with minimal effort. Chartly also allows users to plot multiple overlays and subplots onto the same figure.
-
-
-.. toctree::
-   :maxdepth: 2
-   :caption: Contents:
+**Chartly** is a simple plotting tool designed to help users create
+scientific plots with ease. Whether you want to test a distribution for
+normality or plot contours using a map of the globe, Chartly enables you
+to generate visualisations with minimal effort. Chartly also allows users
+to create multiple overlays and subplots on the same figure.
 
 Requirements
 ------------
 
 The chartly package requires the following packages:
 
-- `matplotlib` >= 3.9.1
-- `numpy` >= 1.26.4
+- `matplotlib` >= 3.8.4
+- `numpy` >= 2.2.6
 - `scipy` >= 1.14.0
-- `seaborn` >= 0.11.0
+- `seaborn` >= 0.13.2
+
+For geographic visualisation using basemaps, the following additional
+dependency is required:
+
+- `basemap` >= 2.0.0
 
 Installation
 ------------
@@ -38,7 +42,7 @@ To install the chartly package, run the following command:
 Usage
 -----
 
-The Chartly package currently has eight (8) available scientific plots that can be created, namely:
+The Chartly package currently supports the following scientific plots:
 
 - Line Plot
 - Histogram
@@ -48,113 +52,145 @@ The Chartly package currently has eight (8) available scientific plots that can
 - Normal Cumulative Distribution Function Plot
 - Density Plot
 - Box Plot
+- Basemap Plot
 
-Chartly allows users to build plots by first creating a main figure and then adding subplots to the figure. To initialize a main figure, users can create a `Chart` instance. Users can also label and customize the main figure by passing an optional dictionary. The dictionary should contain the following keys:
+Chartly allows users to build plots by first creating a main figure and
+then adding subplots to the figure. To initialize a main figure, users
+can create a ``Chart`` instance and optionally pass a dictionary to
+customize the figure. The dictionary supports the following keys:
 
-- `super_title` (str): The title of the main figure.
-- `super_xlabel` (str): The x-axis label of the main figure.
-- `super_ylabel` (str): The y-axis label of the main figure.
-- `share_axes` (bool): Whether to share the y-axes across all subplots. Default is True.
+- ``super_title`` (str): Title of the main figure
+- ``super_xlabel`` (str): X-axis label
+- ``super_ylabel`` (str): Y-axis label
+- ``share_axes`` (bool): Share axes across subplots (default: True)
 
 .. code-block:: python
 
    import chartly
    import numpy as np
 
    # 1. Define the main figure labels
-   super_axes_labels = {"super_title": "Usage Of Chartly Example", "super_xlabel": "X", "super_ylabel": "Y", "share_axes": False}
-
-   # 2. Initialize a main figure by creating a chart instance
+   super_axes_labels = {
+       "super_title": "Usage Of Chartly Example",
+       "super_xlabel": "X",
+       "super_ylabel": "Y",
+       "share_axes": False,
+   }
+
+   # 2. Initialize the chart
    plot = chartly.Chart(super_axes_labels)
 
-
-To create a plot, users can directly add a subplot with ``add_subplot(...)``.
-Additional plots can be added to the same subplot with ``add_overlay(...)``.
-This keeps the public interface simpler by avoiding manual payload
-dictionaries.
-
+To create a plot, users can directly add a subplot with
+``add_subplot(...)``. Additional plots can be added to the same subplot
+with ``add_overlay(...)``.
 
 .. code-block:: python
 
-   # 3. Define Some Data
+   # 3. Define some data
    data = np.random.randn(100)
 
-   # 4. Add a subplot directly
+   # 4. Add a subplot
    plot.add_subplot("histogram", data)
 
-
-To overlay a new plot onto the current subplot, users can call
-``add_overlay(...)`` and pass the plot type and data directly.
+To overlay a new plot onto the current subplot, use ``add_overlay(...)``.
 
 .. code-block:: python
 
    # 5. Overlay another plot
    plot.add_overlay("density", data)
 
-
 To add multiple subplots at once, users can call ``add_subplots(...)``.
 
 .. code-block:: python
 
-   # 6. Add multiple subplots at once
+   # 6. Add multiple subplots
    plot.add_subplots(
-      ["boxplot", "normal_cdf"],
-      data
+       ["boxplot", "normal_cdf"],
+       data,
    )
 
+To create a basemap plot, users can call ``add_basemap(...)`` and pass
+longitude, latitude, and value grids.
 
-Users can also customize the axes of each subplot. 
+.. code-block:: python
+
+   # 7. Define basemap data
+   nlats, nlons = 73, 145
+   delta = 2.0 * np.pi / (nlons - 1)
+   lats = 0.5 * np.pi - delta * np.indices((nlats, nlons))[0, :, :]
+   lons = delta * np.indices((nlats, nlons))[1, :, :]
+   wave = 0.75 * (np.sin(2.0 * lats) ** 8 * np.cos(4.0 * lons))
+   mean = 0.5 * np.cos(2.0 * lats) * ((np.sin(2.0 * lats)) ** 2 + 2.0)
+   z = wave + mean
+
+   # 8. Add a basemap plot
+   plot.add_basemap(
+      lon=lons * 180.0 / np.pi,
+      lat=lats * 180.0 / np.pi,
+      values=z,
+      customs={
+         "proj": "eck4",
+         "lon_0": 0,
+         "draw_countries": True,
+         "draw_parallels": True,
+         "draw_meridians": True,
+         "mask": z < 0,
+         "contour": True,
+         "hatch": True,
+         "hatch_customs": {"type": "mask"},
+      },
+   )
 
-- Users can change the scale of the x and y axes from linear to log. They can also change the base of the log scale. If the base is changed, ensure that the subplots are not sharing axes.
+Users can also customize subplot axes.
 
+- Axes can be scaled (e.g., linear → log)
+- The base of the log scale can be changed
+- Ensure axes are not shared when modifying scales
 
 .. code-block:: python
 
-   # 7. Define a random exponential function
+   # 9. Define a custom function
    exp_func = lambda x: np.e ** (-500 * x + 2)
 
    x = np.linspace(0, 1, num=100)
    y = list(map(exp_func, x))
-   
-   # 8. Add customized subplot
+
+   # 10. Add customized subplot
    plot.add_subplot(
-      "line_plot",
-      y,
-      axes_labels={"scale": "semilogy", "base": 10, "linelabel": "Semilogy Line"},
+       "line_plot",
+       y,
+       axes_labels={"scale": "semilogy", "base": 10, "linelabel": "Semilogy Line"},
    )
 
-
-Finally, the figure can be rendered by calling ``render()``.
+Finally, render the figure using ``render()``.
 
 .. code-block:: python
 
-   # 9. Render the main figure
+   # 11. Render the figure
    plot.render()
 
-To save the figure that was rendered, users can call the `save` method. The default file format is `eps` and the default file name is `chartly_plot`. To change the file format and name, update the plot's properties.
-
+To save the figure, use the ``save()`` method.
 
 .. code-block:: python
 
-   # 10. Save the figure with a different file format and name
+   # 12. Save the figure
    plot.format = "jpg"
    plot.fname = "my_plot"
    plot.save()
 
-.. image:: https://chartly.s3.amazonaws.com/static/img/my_plot.jpg
+.. image:: _static/simple_usage_example.png
     :alt: SimpleUsageOfChartlyExample
     :align: center
     :height: 500px
 
-.. toctree::
-   :maxdepth: 2
-
-   Plot
 
 .. toctree::
    :maxdepth: 2
+   :caption: Contents:
 
+   Plot
    Multiplots
+   Basemap
 
 
 Indices and tables