[CLEANUP] Release prep 0.3.1 (#141)

* Prepare package for v0.3.1 release

* linting

* mark downloading tests as slow

* copilot review changes

* copilot review changes

Author: eleanorfrajka

CHANGELOG.md

@@ -0,0 +1,91 @@
+# Changelog
+
+All notable changes to AMOCatlas will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Fixed
+- Fixed `__version__` import in `__init__.py` for proper package version access
+- Enhanced test coverage for `fbc.py` and `noac47n.py` modules
+
+### Added
+- Comprehensive test cases for FBC (Faroe Bank Channel) data reader
+- Comprehensive test cases for NOAC 47°N array data reader
+- CHANGELOG.md file for tracking project changes
+
+## [0.3.0] - YYYY-MM-DD
+
+### Added
+- New reader for Le Bras AMOC at 35°N (#139)
+- New Sanchez-Franks 2021 Reader (#137) 
+- New NAC reader (#134)
+- Report generation functionality (#140)
+
+### Updated
+- Updated FBC transport with new location and extended timeseries (#133)
+- Updated metadata for Zheng2024 (#136)
+- Updated Zheng2024 plot to 2D (#135)
+
+### Fixed
+- Fixed convert lowercase URL into uppercase when case sensitive (#132)
+- Fixed standardized sigma coords on RAPID to be <1000 (#126)
+
+## [0.2.0] - YYYY-MM-DD
+
+### Added
+- New intuitive API (`amocatlas.read` namespace)
+- Automatic data standardization
+- Enhanced metadata management system
+- Comprehensive documentation and reports
+
+### Changed
+- Legacy API (`load_dataset`, `load_sample_dataset`) marked as deprecated
+- Improved package architecture with modular data sources
+
+## [0.1.1] - YYYY-MM-DD
+
+### Fixed
+- Bug fixes and minor improvements
+
+## [0.1.0] - YYYY-MM-DD
+
+### Added
+- Initial stable release
+- Basic data loading functionality for major AMOC arrays
+- Core plotting and analysis tools
+
+## [0.0.4] - YYYY-MM-DD
+
+### Added
+- Early development version
+- Basic reader implementations
+
+---
+
+### Legend
+
+- **Added** for new features
+- **Changed** for changes in existing functionality
+- **Deprecated** for soon-to-be removed features
+- **Removed** for now removed features
+- **Fixed** for any bug fixes
+- **Security** for vulnerability fixes
+
+### Release Process
+
+1. Create a new version section above "Unreleased"
+2. Move items from "Unreleased" to the new version section
+3. Add release date in YYYY-MM-DD format
+4. Create git tag with format `v{version}` (e.g., `v0.3.1`)
+5. GitHub Actions will automatically publish to PyPI
+
+### Contributing
+
+When adding changes, please:
+1. Add new entries under the "Unreleased" section
+2. Use the appropriate category (Added, Changed, Fixed, etc.)
+3. Include PR numbers in parentheses when applicable
+4. Keep descriptions clear and user-focused

README.md

@@ -96,14 +96,21 @@ from amocatlas import read
 ds = read.osnap()                          # Single standardized dataset
 all_files = read.osnap(all_files=True)     # Get all files for array
 
-# Or use the legacy API
-from amocatlas import readers
-datasets = readers.load_dataset("osnap")  # Returns list of raw datasets
 ```
 
 A `*.log` file will be written to `logs/` by default.
 
-Data will be cached in `~/.amocatlas_data/` unless you specify a custom location.
+Data will be cached in `~/.amocatlas_data/` unless you specify a custom location with `data_dir="/path/to/custom/data"`.
+
+**Setting Default Data Directory:**
+```python
+import amocatlas
+amocatlas.set_data_dir("~/my_data")    # Custom location
+amocatlas.set_data_dir("project")      # Use project/data (source checkout only)
+print(amocatlas.get_data_dir())        # Show current setting
+```
+
+**Note:** The `"project"` option only works when running from a source checkout (editable install with `pip install -e .`). For regular pip installations, use an explicit path like `"~/my_data"` instead.
 
 ### API Features (v0.2.0+)
 
@@ -128,11 +135,6 @@ all_rapid = read.rapid(all_files=True) # Get all files for an array
 raw_data = read.rapid(raw=True)        # Original format for special cases
 ```
 
-**Legacy API (still supported):**
-```python
-from amocatlas import readers
-datasets = readers.load_dataset("rapid")  # Returns raw data as before
-```
 
 ## Documentation
 

amocatlas/__init__.py

@@ -40,8 +40,11 @@
     data_sources,  # New data sources package
 )
 
+# Import key utilities at top level for convenience
+from .utilities import set_data_dir, get_data_dir
+
 # Version information
-# from ._version import __version__
+from ._version import __version__
 
 __all__ = [
     "readers",
@@ -56,5 +59,7 @@
     "compliance_checker",
     "reader_utils",
     "data_sources",
+    "set_data_dir",
+    "get_data_dir",
     "__version__",
 ]

amocatlas/data_sources/lebras35n.py

@@ -2,7 +2,7 @@
 
 This module provides functions to read and process AMOC transport data at 35°N from deep moorings, floats and satellite altimetry.
 
-Dataset one includes the AMOC transport in depth and in density space, the integrated across-basin streamfunction in depth space and the Ekman transport time series derived from CCMP. 
+Dataset one includes the AMOC transport in depth and in density space, the integrated across-basin streamfunction in depth space and the Ekman transport time series derived from CCMP.
 Dataset two includes the geostrophic velocities through the section, the potential density anomaly referenced to 2000m, the depth of the sea floor along the section and the area of each grid point.
 
 Key functions:

amocatlas/data_sources/nac.py

@@ -1,6 +1,6 @@
 """North Atlantic Current (NAC) data reader for AMOCatlas.
 
-This module provides functions to read and process the North Atlantic current time series from satellite and float observations. 
+This module provides functions to read and process the North Atlantic current time series from satellite and float observations.
 The NAC is a key component of the Atlantic Meridional Overturning Circulation, transporting warm, saline water from the tropics to the high northern latitudes.
 
 The dataset includes NAC transport estimates from satellite and float observations and an NAC estimation from satellite altimetry alone.

amocatlas/data_sources/rapid26n.py

@@ -154,7 +154,9 @@ def read_rapid(
         if file == "meridional_transports.nc":
             if "sigma0" in ds.coords:
                 original_values = ds["sigma0"].values
-                if original_values.max() > 100:  # Check if values are in absolute density range (>1000) rather than anomaly range
+                if (
+                    original_values.max() > 100
+                ):  # Check if values are in absolute density range (>1000) rather than anomaly range
                     log_info(
                         f"Fixing sigma0 coordinates in {file}: subtracting 1000 to get density anomaly"
                     )
@@ -166,7 +168,9 @@ def read_rapid(
 
             if "sigma2" in ds.coords:
                 original_values = ds["sigma2"].values
-                if original_values.max() > 100:  # Check if values are in absolute density range (>1000) rather than anomaly range
+                if (
+                    original_values.max() > 100
+                ):  # Check if values are in absolute density range (>1000) rather than anomaly range
                     log_info(
                         f"Fixing sigma2 coordinates in {file}: subtracting 1000 to get density anomaly"
                     )

amocatlas/data_sources/sf2021.py

@@ -1,7 +1,7 @@
 """Sanchez-Franks Satellite proxy for the AMOC at 26N data reader for AMOCatlas.
 
 This module provides functions to read and process satellite proxy transport data for 26N
-from Sanchez-Franks et al. (2021). This dataset provides a satellite reconstruction of the AMOC transport 
+from Sanchez-Franks et al. (2021). This dataset provides a satellite reconstruction of the AMOC transport
 at 26N based on satellite altimetry. It also includes the upper-mid-ocean and gulf stream components.
 The components are derived through a dynamically based method.
 """
@@ -46,54 +46,61 @@
     "long_name": "Time elapsed since 1970-01-01T00:00:00Z",
     "standard_name": "time",
     "calendar": "gregorian",
-    "vocabulary": "http://vocab.nerc.ac.uk/collection/OG1/current/TIME/"
+    "vocabulary": "http://vocab.nerc.ac.uk/collection/OG1/current/TIME/",
 }
 
 
-def _normalize_sf2021_time_coordinate(ds: xr.Dataset, source_file: str = None) -> xr.Dataset:
+def _normalize_sf2021_time_coordinate(
+    ds: xr.Dataset, source_file: str = None
+) -> xr.Dataset:
     """Convert SF2021 TIME coordinate from days since 0000-01-01 to datetime64[ns].
-    
+
     Parameters
     ----------
     ds : xr.Dataset
         Dataset with sat_time or TIME coordinate as float (days since 0000-01-01)
     source_file : str, optional
         Source filename (currently unused, kept for API compatibility)
-    
+
     Returns
     -------
     xr.Dataset
         Dataset with time coordinate converted to datetime64[ns]
+
     """
     # Find time variable (check raw name first, then final name)
     time_var = next((var for var in ["sat_time", "TIME"] if var in ds.coords), None)
-    
+
     if not time_var or ds[time_var].dtype.kind not in ["f", "i"]:
-        log_debug(f"Skipping TIME normalization - {time_var or 'TIME'} not found or not numeric")
+        log_debug(
+            f"Skipping TIME normalization - {time_var or 'TIME'} not found or not numeric"
+        )
         return ds
-    
+
     try:
         # Convert days since 0000-01-01 to datetime64[ns] without using year 0 in ns resolution.
         # Decompose into integer days and fractional nanoseconds relative to 1970-01-01.
         time_values = np.asarray(ds[time_var].values, dtype=np.float64)
         epoch_days = 719528.0  # Days between 0000-01-01 and 1970-01-01 in proleptic Gregorian calendar.
         relative_days = time_values - epoch_days
         whole_days = np.floor(relative_days).astype(np.int64)
-        fractional_ns = np.rint((relative_days - whole_days) * 86400 * 1e9).astype(np.int64)
+        fractional_ns = np.rint((relative_days - whole_days) * 86400 * 1e9).astype(
+            np.int64
+        )
 
         time_datetime = (
             np.datetime64("1970-01-01", "ns")
             + whole_days.astype("timedelta64[D]")
             + fractional_ns.astype("timedelta64[ns]")
         ).astype("datetime64[ns]")
-        
+
         # Use assign_coords to properly set dimension coordinate
         ds = ds.assign_coords({time_var: time_datetime})
         ds[time_var].attrs = _TIME_METADATA
         log_debug(f"Converted SF2021 {time_var} from days to datetime64[ns]")
     except (ValueError, TypeError, OverflowError) as e:
         log_warning(f"Failed to convert SF2021 TIME coordinate: {e}")
-    
+
     return ds
 
 
@@ -188,7 +195,7 @@ def read_sf2021(
             # Use ReaderUtils for consistent dataset loading
 
             ds = ReaderUtils.safe_load_dataset(file_path)
-            
+
             # Attach metadata
             # Attach metadata with optional tracking
 
@@ -219,7 +226,7 @@ def read_sf2021(
                     DATASOURCE_ID,
                     track_added_attrs=False,
                 )
-            
+
             # Normalize SF2021 TIME coordinate AFTER metadata attachment
             ds = _normalize_sf2021_time_coordinate(ds, source_file=file)
         else:

amocatlas/defaults.py

@@ -239,8 +239,8 @@
     "wh41n",  # Woods Hole 41°N array
     "noac47n",  # NOAC 47°N array (North Atlantic Ocean Current)
     "nac",  # North Atlantic Current
-    "sf2021", # Sanchez-Franks 2021 satellite reconstruction of AMOC transport at 26°N
-    "lebras35n", # Lebras 2023 AMOC transport at 35°N
+    "sf2021",  # Sanchez-Franks 2021 satellite reconstruction of AMOC transport at 26°N
+    "lebras35n",  # Lebras 2023 AMOC transport at 35°N
 ]
 
 # Mapping from array names to their full descriptions

amocatlas/plotters.py

@@ -633,7 +633,7 @@ def plot_amoc_timeseries(
     ax.spines["right"].set_visible(False)
     ax.set_title(title)
     ax.set_xlabel("Time")
-    ax.set_ylabel(ylabel if ylabel else "Transport [Sv]")
+    ax.set_ylabel(ylabel if ylabel else "Transport (Sv)")
     ax.legend(loc="best")
     ax.grid(True, linestyle="--", alpha=0.5)
 
@@ -681,7 +681,7 @@ def plot_monthly_anomalies(
         axes[i].plot(time, data, color=color, label=label)
         axes[i].axhline(0, color="black", linestyle="--", linewidth=0.5)
         axes[i].set_title(label)
-        axes[i].set_ylabel("Transport [Sv]")
+        axes[i].set_ylabel("Transport (Sv)")
         axes[i].legend()
         axes[i].grid(True, linestyle="--", alpha=0.5)
 
@@ -745,7 +745,7 @@ def _add_amocatlas_timestamp(fig: object) -> None:
 
 
 def plot_moc_timeseries_pygmt(
-    df: pd.DataFrame, column: str = "moc", label: str = "MOC [Sv]"
+    df: pd.DataFrame, column: str = "moc", label: str = "MOC (Sv)"
 ) -> "pygmt.Figure":
     """Plot MOC time series using PyGMT with publication-quality styling.
 
@@ -755,7 +755,7 @@ def plot_moc_timeseries_pygmt(
         DataFrame with 'time_num' (decimal years) and data columns.
     column : str, default "moc"
         Name of the column to plot.
-    label : str, default "MOC [Sv]"
+    label : str, default "MOC (Sv)"
         Y-axis label for the plot.
 
     Returns
@@ -885,7 +885,7 @@ def plot_osnap_components_pygmt(data: Union[DataFrame, Dict]) -> "pygmt.Figure":
 
     # Basemap
     fig.basemap(
-        region=region, projection="X15c/7c", frame=["xaf", "yafg5f2+lMOC [Sv]", "WS"]
+        region=region, projection="X15c/7c", frame=["xaf", "yafg5f2+lMOC (Sv)", "WS"]
     )
 
     # --- Shaded error for EAST ---
@@ -977,7 +977,7 @@ def plot_rapid_components_pygmt(df: pd.DataFrame) -> "pygmt.Figure":
     fig.basemap(
         region=region,
         projection="X25c/15c",
-        frame=["xaf", "yafg5f2+lTransport [Sv]", "WS+tRAPID MOC Components"],
+        frame=["xaf", "yafg5f2+lTransport (Sv)", "WS+tRAPID MOC Components"],
     )
 
     # Plot each component with custom colors
@@ -1067,10 +1067,10 @@ def plot_all_moc_pygmt(
 
     # Prepare data and labels
     dfs = [
-        (osnap_df, "MOC [Sv]", (5, 25), 5, "OSNAP", green1, "W"),
-        (rapid_df, "MOC [Sv]", (5, 30), 6, "RAPID 26°N", red1, "E"),
-        (move_df, "MOC [Sv]", (5, 30), 6, "MOVE 16°N", magenta1, "W"),
-        (samba_df, "Anomaly [Sv]", (-10, 15), 6, "SAMBA 34.5°S", blue1, "ES"),
+        (osnap_df, "MOC (Sv)", (5, 25), 5, "OSNAP", green1, "W"),
+        (rapid_df, "MOC (Sv)", (5, 30), 6, "RAPID 26°N", red1, "E"),
+        (move_df, "MOC (Sv)", (5, 30), 6, "MOVE 16°N", magenta1, "W"),
+        (samba_df, "Anomaly (Sv)", (-10, 15), 6, "SAMBA 34.5°S", blue1, "ES"),
     ]
 
     # Find global x range
@@ -1210,7 +1210,7 @@ def plot_bryden2005_pygmt() -> "pygmt.Figure":
     fig.basemap(
         region=[1955, 2006, 13, 24],
         projection="X8c/6c",
-        frame=["WS", "yaf+lMOC [Sv]", "xccustom_xticks.txt"],
+        frame=["WS", "yaf+lMOC (Sv)", "xccustom_xticks.txt"],
     )
 
     # Plot red line
@@ -1278,10 +1278,10 @@ def plot_all_moc_overlaid_pygmt(
 
     # Prepare data and labels - overlay mode (shiftflag=False)
     dfs = [
-        (osnap_df, "MOC [Sv]", (10, 20), 6, "OSNAP", green1, "W"),
-        (rapid_df, "MOC [Sv]", (10, 20), 6, "RAPID 26°N", red1, "W"),
-        (move_df, "MOC [Sv]", (10, 20), 6, "MOVE 16°N", magenta1, "W"),
-        (samba_df, "Anomaly [Sv]", (-5, 5), 6, "SAMBA 34.5°S", blue1, "ES"),
+        (osnap_df, "MOC (Sv)", (10, 20), 6, "OSNAP", green1, "W"),
+        (rapid_df, "MOC (Sv)", (10, 20), 6, "RAPID 26°N", red1, "W"),
+        (move_df, "MOC (Sv)", (10, 20), 6, "MOVE 16°N", magenta1, "W"),
+        (samba_df, "Anomaly (Sv)", (-5, 5), 6, "SAMBA 34.5°S", blue1, "ES"),
     ]
 
     # Find global x range