Metadata-Version: 2.4
Name: harmonized-landsat-sentinel
Version: 2.3.1
Summary: Harmonized Landsat Sentinel (HLS) search and download utility
Author-email: "Gregory H. Halverson" <gregory.h.halverson@jpl.nasa.gov>
Project-URL: Homepage, https://github.com/STARS-Data-Fusion/harmonized-landsat-sentinel
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4
Requires-Dist: colored-logging
Requires-Dist: earthaccess
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Requires-Dist: pytest
Requires-Dist: python-dateutil
Requires-Dist: rasterio
Requires-Dist: rasters>=1.18.0
Requires-Dist: requests
Requires-Dist: sentinel-tiles
Requires-Dist: shapely
Dynamic: license-file

# Harmonized Landsat Sentinel (HLS) Python Search and Download Utility

[![CI](https://github.com/STARS-Data-Fusion/harmonized-landsat-sentinel/actions/workflows/ci.yml/badge.svg)](https://github.com/STARS-Data-Fusion/harmonized-landsat-sentinel/actions/workflows/ci.yml)

[Gregory H. Halverson](https://github.com/gregory-halverson-jpl) (they/them)<br>
[gregory.h.halverson@jpl.nasa.gov](mailto:gregory.h.halverson@jpl.nasa.gov)<br>
NASA Jet Propulsion Laboratory 329G

Margaret C. Johnson (she/her)<br>
[maggie.johnson@jpl.nasa.gov](mailto:maggie.johnson@jpl.nasa.gov)<br>
NASA Jet Propulsion Laboratory 

[Evan Davis](https://github.com/evandjpl) (he/him)<br>
[evan.w.davis@jpl.nasa.gov](mailto:evan.w.davis@jpl.nasa.gov)<br>
NASA Jet Propulsion Laboratory 397K

## Installation

This package is available on PyPi: [https://pypi.org/project/harmonized-landsat-sentinel](https://pypi.org/project/harmonized-landsat-sentinel)

```
pip install harmonized-landsat-sentinel
```

## Skip all-NaN outputs

When cloud masks and nodata filtering produce rasters with no valid pixels, you can skip writing those files:

```python
from harmonized_landsat_sentinel import generate_HLS_timeseries

generate_HLS_timeseries(
   start_date_UTC="2022-08-01",
   end_date_UTC="2022-08-02",
   geometry=grid,
   output_directory="~/data/Kings_Canyon_HLS",
   source="both",
   skip_all_nan=True,
)
```

CLI:

```
hls --start 2022-08-01 --end 2022-08-02 --skip-all-nan
```

## How to Cite This Package

If you use this software in a publication, please cite the specific release/version you used.

Suggested software citation:

- Halverson, G. H., Johnson, M. C., & Davis, E. (2026). *harmonized-landsat-sentinel* (Version 2.3.0) [Computer software]. GitHub. https://github.com/STARS-Data-Fusion/harmonized-landsat-sentinel

LaTeX (BibTeX) entry:

```bibtex
@software{halverson2026hls,
   author  = {Halverson, Gregory H. and Johnson, Margaret C. and Davis, Evan},
   title   = {{harmonized-landsat-sentinel}},
   year    = {2026},
   version = {2.3.0},
   url     = {https://github.com/STARS-Data-Fusion/harmonized-landsat-sentinel},
   note    = {Computer software}
}
```

For machine-readable citation metadata, see `CITATION.cff` in this repository.

## References

If you use this package to access or analyze the Harmonized Landsat Sentinel (HLS) dataset, please cite the following datasets and research articles:

### Data Citations

- **HLS v2.0 (L30 and S30)**:  
  NASA Goddard Space Flight Center; U.S. Geological Survey. (2022). Harmonized Landsat Sentinel-2 (HLS) Product, Version 2.0 [Dataset]. NASA LP DAAC. https://doi.org/10.5067/HLS/HLS.020

### Peer-Reviewed Articles

1. **Roy, D. P., Li, J., Zhang, H. K., & Yan, L. (2016)**. *The Harmonized Landsat and Sentinel-2 (HLS) Product: An Analytical Framework for Characterizing Land Cover Using Satellite Remote Sensing*. Remote Sensing of Environment, 176, 152-171. https://doi.org/10.1016/j.rse.2015.12.024  
   This foundational article presents the analytical framework for harmonizing Landsat and Sentinel-2 data, discussing challenges in land cover characterization and product development.

2. **Claverie, M., Ju, J., Masek, J. G., Dungan, J. L., Vermote, E. F., Roger, J. C., Skakun, S., & Justice, C. O. (2018)**. *Harmonized Landsat-8 Sentinel-2 Products for Land Monitoring*. Remote Sensing of Environment, 219, 145-161. https://doi.org/10.1016/j.rse.2018.09.002  
   This article describes the harmonization process, atmospheric correction, and band alignment used in generating the HLS products.

3. **Feng, M., Vermote, E. F., & Masek, J. G. (2020)**. *Harmonized Landsat Sentinel-2 Data for Monitoring Global Agriculture*. Remote Sensing, 12(22), 3684. https://doi.org/10.3390/rs12223684  
   This paper highlights applications of HLS in agricultural monitoring, with validation studies that underscore its importance for tracking global agricultural patterns.
