# Chlorophyll-a Variation Trends in Marginal Seas

This repository contains the analysis and plotting code used for the manuscript
**"Chlorophyll-a Variation Trends in Marginal Seas: Assessing the Impact of Global
Heating and Anthropogenic Activities Using Time Series Satellite Data (1998–2020)"**.

## Repository Version (Commit ID)

The code version used for the manuscript revision is tracked by the following Git
commit identifier:

```
f7151f0e93458e0038aacb0a56c4537a4071f94d
```

Repository: https://github.com/giseryn/Chlorophyll-a-Variation-Trends-in-Marginal-Seas

To reproduce the exact analysis environment, clone the repository and check out this
commit:

```bash
git clone https://github.com/giseryn/Chlorophyll-a-Variation-Trends-in-Marginal-Seas.git
cd Chlorophyll-a-Variation-Trends-in-Marginal-Seas
git checkout f7151f0e93458e0038aacb0a56c4537a4071f94d
```

## Study Overview

This workflow analyzes long-term chlorophyll-a (Chl-a) trends in five marginal seas
using monthly satellite remote sensing data from 1998 to 2020. The study integrates
multiple environmental drivers—sea surface temperature (SST), photosynthetically
active radiation (PAR), and surface wind speed (SWS)—to assess the relative
influence of global heating and anthropogenic activities on Chl-a variability.

### Study Regions

| Region code | Marginal sea | Approximate bounding box (W, S, E, N) |
| --- | --- | --- |
| `amazon` | Amazon River plume | -61, -6, -37, 16 |
| `bohai` | Bohai Sea | 117, 37, 123, 41 |
| `donghai` | East China Sea | 117, 23, 131, 33 |
| `mexico` | Gulf of Mexico | -98.86, 17.09, -81.28, 31.16 |
| `USEastCoast` | U.S. East Coast | -81.6, 27.5, -57.66, 43.3 |

Additional regions (e.g., Iberian margin) can be configured by editing the bounding
boxes in `04_create_research_areas.py` and the area lists in downstream scripts.

## Data Sources

| Variable | Product | Sensor / platform | Period |
| --- | --- | --- | --- |
| Chl-a | OC-CCI / NASA OceanColor | SeaWiFS, MODIS-Aqua | 1998–2020 |
| PAR | NASA OceanColor | SeaWiFS, MODIS-Aqua | 1998–2020 |
| SST | NOAA OISST / GHRSST | AVHRR, microwave blends | 1998–2020 |
| SWS | CCMP | Cross-calibrated multi-platform winds | 1998–2020 |

Source files should be downloaded from the providers cited in the manuscript. NASA
OceanColor data require a valid [Earthdata Login](https://urs.earthdata.nasa.gov/)
account or `.netrc` credentials (see header comments in `01_download.py`).

## Workflow Overview

The numbered scripts implement the end-to-end processing pipeline:

```
01_download.py          → Download satellite products from NASA OceanColor
02_extract_tar.py       → Extract compressed .tar archives
03_convert_nc_to_tif.py → Convert NetCDF to GeoTIFF rasters
04_create_research_areas.py → Crop rasters to study-region bounding boxes
05_crop_research_data.py    → Fill gaps, resample, mask, and harmonize sensors
06_anaysis_part.py          → Trend, stability, correlation, and PCA analyses
08_get_chl_line_data.py     → Prepare time-series data for line plots
main.py / mk.py / paint_sst&chl.py → Manuscript figure generation
```

## Main Scripts

| Script | Purpose |
| --- | --- |
| `01_download.py` | Downloads source satellite data from NASA OceanColor services. |
| `02_extract_tar.py` | Extracts compressed `.tar` archives into local data folders. |
| `03_convert_nc_to_tif.py` | Converts NetCDF variables (Chl-a, PAR, SST, CCMP) to GeoTIFF. |
| `04_create_research_areas.py` | Creates vector grids, masks, and crops rasters by region. |
| `05_crop_research_data.py` | Fills no-data gaps, resamples, applies masks, and merges SeaWiFS/MODIS via monthly regression. |
| `06_anaysis_part.py` | Computes regional statistics, Sen's slope trends, Mann-Kendall tests, correlation, and PCA. |
| `08_get_chl_line_data.py` | Exports seasonal and monthly environmental-factor time series. |
| `main.py` | Plotting utilities for correlation matrices, Mann-Kendall figures, and composite maps. |
| `mk.py` | Standalone Mann-Kendall change-point detection and plotting. |
| `paint_sst&chl.py` | SST and Chl-a map visualization with Cartopy. |
| `paint.r` | R script for supplementary figure rendering. |

## Directory Structure (Expected)

```
.
├── 01_download_nasa_data/     # Raw downloaded tar archives
├── 02_chl_nc_data/            # Extracted Chl-a NetCDF files
├── 02_par_nc_data/            # Extracted PAR NetCDF files
├── 03_chl_tif/                # Chl-a GeoTIFF rasters
├── 03_par_tif/                # PAR GeoTIFF rasters
├── 04_<region>/               # Region-cropped rasters and mask shapefiles
├── 04_basic_file/             # Reference raster and ocean mask shapefile
├── 05_<region>_data/          # Preprocessed Chl-a, PAR, SST, CCMP by region
├── 08_<region>_result_file/   # Exported time-series CSV files
└── result/                    # Final figure outputs
```

## Requirements

Install the following Python packages (versions used during development are listed
for reference):

| Package | Purpose |
| --- | --- |
| `numpy`, `pandas`, `scipy` | Numerical and statistical analysis |
| `gdal`, `rasterio`, `geopandas`, `shapely` | Geospatial raster/vector processing |
| `netCDF4`, `xarray` | NetCDF data I/O |
| `scikit-learn`, `factor_analyzer` | Regression and PCA |
| `pymannkendall` | Mann-Kendall trend tests |
| `matplotlib`, `seaborn`, `cartopy`, `PIL` | Visualization and mapping |
| `tqdm`, `numba` | Progress bars and accelerated loops |
| `requests` | NASA OceanColor HTTP downloads |

GDAL must be installed at the system level before installing the Python bindings.

## Quick Start

1. Clone the repository and check out the commit ID listed above.
2. Configure NASA Earthdata credentials (`.netrc` or app key in `01_download.py`).
3. Update hard-coded input/output paths in each script to match your local storage.
4. Run the pipeline in numerical order:

```bash
python 01_download.py
python 02_extract_tar.py
python 03_convert_nc_to_tif.py
python 04_create_research_areas.py
python 05_crop_research_data.py
python 06_anaysis_part.py
python 08_get_chl_line_data.py
```

5. Generate figures using `main.py`, `mk.py`, or `paint_sst&chl.py` as needed.

## Outputs

The pipeline produces:

- Cropped and bias-corrected monthly GeoTIFF rasters per study region
- Regional mean time series (seasonal and annual) in CSV format
- Sen's slope and Mann-Kendall trend statistics
- Pearson correlation matrices and PCA loadings
- Publication-ready maps and line plots

## Reproducibility Notes

- Use the commit hash in the **Repository Version** section to identify the exact
  code version used for the submitted analyses.
- All inline code comments are written in English.
- Input and output paths are configured inside each script; adjust them before
  running on a new machine.
- Large satellite datasets are not included in this repository due to size
  constraints; they must be downloaded separately.

## License

See [LICENSE](LICENSE) for terms of use.

## Citation

If you use this code, please cite the associated manuscript (details to be added
upon publication).
