Skip to content

API Reference

Visualization

sdm.simple_bbox

sdm.simple_bbox(bbox, projection='PlateCarree')

Plot a bounding box on a global map using Cartopy.

This function displays a world map with coastlines and borders, and overlays a red bounding box. Optionally, it can render the Earth as a globe using Orthographic projection centered on the bounding box.

Parameters

bbox : list or tuple of float Bounding box in [min_lon, min_lat, max_lon, max_lat] format.

str, optional

Map projection to use. Options include: - 'PlateCarree' (default) - 'Robinson' - 'Mollweide' - 'Mercator' - 'EqualEarth' - 'InterruptedGoodeHomolosine' - 'globe' (for Orthographic projection centered on the bbox)

Returns

None Displays the plot using matplotlib.

Example

plot_global_bbox([-25, 10, -10, 30], projection='globe')

Source code in src/sdm/viz.py 
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
def simple_bbox(bbox, projection='PlateCarree'):
    """
    Plot a bounding box on a global map using Cartopy.

    This function displays a world map with coastlines and borders, and overlays
    a red bounding box. Optionally, it can render the Earth as a globe using
    Orthographic projection centered on the bounding box.

    Parameters
    ----------
    bbox : list or tuple of float
        Bounding box in [min_lon, min_lat, max_lon, max_lat] format.

    projection : str, optional
        Map projection to use. Options include:
            - 'PlateCarree' (default)
            - 'Robinson'
            - 'Mollweide'
            - 'Mercator'
            - 'EqualEarth'
            - 'InterruptedGoodeHomolosine'
            - 'globe' (for Orthographic projection centered on the bbox)

    Returns
    -------
    None
        Displays the plot using matplotlib.

    Example
    -------
    >>> plot_global_bbox([-25, 10, -10, 30], projection='globe')
    """
    if not (isinstance(bbox, (list, tuple)) and len(bbox) == 4):
        raise ValueError("bbox must be a list or tuple of four floats: [min_lon, min_lat, max_lon, max_lat]")

    min_lon, min_lat, max_lon, max_lat = bbox

    # Projection handling
    projection_dict = {
        'PlateCarree': ccrs.PlateCarree(),
        'Robinson': ccrs.Robinson(),
        'Mollweide': ccrs.Mollweide(),
        'Mercator': ccrs.Mercator(),
        'EqualEarth': ccrs.EqualEarth(),
        'InterruptedGoodeHomolosine': ccrs.InterruptedGoodeHomolosine(),
    }

    if projection == 'globe':
        center_lon = (min_lon + max_lon) / 2
        center_lat = (min_lat + max_lat) / 2
        proj = ccrs.Orthographic(central_longitude=center_lon, central_latitude=center_lat)
    elif projection in projection_dict:
        proj = projection_dict[projection]
    else:
        raise ValueError(f"Unsupported projection '{projection}'. Choose from {list(projection_dict.keys()) + ['globe']}.")

    # Plot setup
    fig, ax = plt.subplots(figsize=(12, 6), subplot_kw={"projection": proj})
    if projection == 'globe':
        ax.set_global()
    else:
        ax.set_global()

    ax.coastlines()
    ax.add_feature(cfeature.LAND, facecolor="lightgray")
    ax.add_feature(cfeature.BORDERS, linestyle=":")
    if projection != 'globe':
        ax.gridlines(draw_labels=True, crs=ccrs.PlateCarree())

    # Bounding box
    gdf = gpd.GeoDataFrame(
        geometry=[box(min_lon, min_lat, max_lon, max_lat)],
        crs="EPSG:4326"
    )
    gdf.boundary.plot(ax=ax, edgecolor="red", linewidth=2, transform=ccrs.PlateCarree())

    title = "Study Area"
    ax.set_title(title, fontsize=14)
    plt.show()

Data Access

sdm.load_trawl_data

sdm.load_trawl_data()

Load example trawl abundance data from NE trawl survey.

This dataset contains species abundance observations collected from tows along with metadata like date, location, depth, and swept area.

Returns

pd.DataFrame A DataFrame with columns: - TOWDATETIME_EST (str): Tow start datetime in EST - LAT, LON (float): Latitude and longitude of the tow - MEAN_DEPTH (float): Mean depth in meters - SWEPT_AREA_km (float): Swept area in square kilometers - One column per species (e.g., acadian redfish, alewife, ..., yellowtail flounder) with counts or presence/absence data.

Example

df = load_trawl_data() df[['LAT', 'LON', 'acadian redfish']].head()

Source code in src/sdm/access_data.py 
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
def load_trawl_data():
    """
    Load example trawl abundance data from NE trawl survey.

    This dataset contains species abundance observations collected from tows
    along with metadata like date, location, depth, and swept area.

    Returns
    -------
    pd.DataFrame
        A DataFrame with columns:
        - `TOWDATETIME_EST` (str): Tow start datetime in EST
        - `LAT`, `LON` (float): Latitude and longitude of the tow
        - `MEAN_DEPTH` (float): Mean depth in meters
        - `SWEPT_AREA_km` (float): Swept area in square kilometers
        - One column per species (e.g., `acadian redfish`, `alewife`, ..., `yellowtail flounder`)
          with counts or presence/absence data.

    Example
    -------
    df = load_trawl_data()
    df[['LAT', 'LON', 'acadian redfish']].head()
    """
    with pkg_resources.files(data).joinpath("trawl.csv").open("r") as f:
        return pd.read_csv(f)