Metadata-Version: 2.4
Name: climakitae
Version: 1.6.0
Summary: Climate data analysis toolkit
Author-email: Cal-Adapt Analytics Engine Team <analytics@cal-adapt.org>
License: BSD-3-Clause
Project-URL: Homepage, https://github.com/cal-adapt/climakitae
Project-URL: Documentation, https://cal-adapt.github.io/climakitae/dev/
Project-URL: Repository, https://github.com/cal-adapt/climakitae
Project-URL: Issues, https://github.com/cal-adapt/climakitae/issues
Project-URL: Cal-Adapt, https://analytics.cal-adapt.org
Keywords: climate,data,analysis,california,cal-adapt
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiobotocore<=2.22.0
Requires-Dist: boto3<=1.37.3
Requires-Dist: dask
Requires-Dist: dask-gateway
Requires-Dist: dask-geopandas
Requires-Dist: fsspec
Requires-Dist: geopandas
Requires-Dist: geopy
Requires-Dist: intake
Requires-Dist: intake-esm<=2023.11.10
Requires-Dist: pydantic<2.13,>=2.0
Requires-Dist: ipython
Requires-Dist: intake-geopandas
Requires-Dist: intake-xarray
Requires-Dist: matplotlib
Requires-Dist: numcodecs<=0.14.1
Requires-Dist: numpy
Requires-Dist: pandas<3.0
Requires-Dist: param
Requires-Dist: psutil
Requires-Dist: pyproj
Requires-Dist: pytz
Requires-Dist: rioxarray
Requires-Dist: s3fs
Requires-Dist: scipy
Requires-Dist: setuptools<81
Requires-Dist: shapely
Requires-Dist: statsmodels
Requires-Dist: timezonefinder
Requires-Dist: tqdm
Requires-Dist: xarray
Requires-Dist: xclim>0.56.0
Requires-Dist: xsdba
Requires-Dist: xmip
Requires-Dist: fastparquet==2025.12.0
Requires-Dist: icechunk>=1.1.15
Requires-Dist: iprogress>=0.4
Requires-Dist: ipywidgets>=8.1.8
Provides-Extra: docs
Requires-Dist: mkdocs>=1.6; extra == "docs"
Requires-Dist: mkdocs-material>=9.6; extra == "docs"
Requires-Dist: pymdown-extensions>=10.15; extra == "docs"
Requires-Dist: mike>=2.0; extra == "docs"
Requires-Dist: mkdocstrings-python>=1.0; extra == "docs"
Requires-Dist: Sphinx; extra == "docs"
Requires-Dist: sphinx-book-theme; extra == "docs"
Requires-Dist: sphinx-design; extra == "docs"
Requires-Dist: nbsphinx; extra == "docs"
Provides-Extra: dev
Requires-Dist: black; extra == "dev"
Requires-Dist: cftime; extra == "dev"
Requires-Dist: isort>=7.0.0; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-xdist; extra == "dev"
Dynamic: license-file

# Climakitae

[![codecov](https://codecov.io/gh/cal-adapt/climakitae/branch/main/graph/badge.svg)](https://codecov.io/gh/cal-adapt/climakitae)
[![CI](https://github.com/cal-adapt/climakitae/workflows/ci-main/badge.svg)](https://github.com/cal-adapt/climakitae/actions/workflows/ci-main.yml)
[![docs](https://github.com/cal-adapt/climakitae/workflows/docs-mkdocs/badge.svg)](https://github.com/cal-adapt/climakitae/actions/workflows/docs-mkdocs.yml)
[![PyPI version](https://badge.fury.io/py/climakitae.svg)](https://badge.fury.io/py/climakitae)
[![Python](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://opensource.org/licenses/BSD-3-Clause)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![DOI:10.5281/zenodo.18111935](https://zenodo.org/badge/DOI/10.5281/zenodo.18111935.svg)](https://doi.org/10.5281/zenodo.18111935)


**A powerful Python toolkit for climate data analysis and retrieval from the Cal-Adapt Analytics Engine (AE).**

Climakitae provides intuitive tools for accessing, analyzing, and visualizing California's Fifth Climate Change Assessment Dataset (downscaled CMIP6 data) and other state supported datasets, enabling researchers and practitioners to perform comprehensive climate impact assessments for California.

> [!WARNING]
> This package is under active development. APIs may change between versions.

## Key Features

- 🌡️ **Comprehensive Climate Data Access**: Retrieve climate variables from hosted climate model, weather station, renewable energy, and Sup3rCC datasets
- 📊 **Downscaled Climate Models**: Access dynamical (WRF) and statistical (LOCA2) downscaling methods  
- 🗺️ **Spatial Analysis Tools**: Built-in support for geographic subsetting and spatial aggregation
- 📈 **Climate Indices**: Calculate heat indices, warming levels, and extreme event metrics
- 🔧 **Flexible Data Export**: Export to NetCDF, CSV, and Zarr

## About Cal-Adapt

Climakitae is developed as part of the [Cal-Adapt Analytics Engine](https://analytics.cal-adapt.org), a platform for California climate data and tools. Cal-Adapt provides access to cutting-edge climate science to support adaptation planning and decision-making.

## Getting Started

### Installation

Climakitae requires **Python 3.12 or 3.13**. We recommend [`uv`](https://docs.astral.sh/uv/) on Linux/macOS and [`conda`](https://www.anaconda.com/docs/getting-started/miniconda/install) on Windows or when native geospatial dependencies cause trouble.

Quick install of the latest release:

```bash
# with uv
uv pip install climakitae

# with conda
conda create -n climakitae python=3.13 -y
conda activate climakitae
pip install climakitae
```

For editable installs, developer dependencies, and platform-specific tips, see the **[Installation Guide on the wiki](https://github.com/cal-adapt/climakitae/wiki)**.

### Basic Usage

```python
from climakitae import ClimateData

# Retrieve monthly max temperature for Los Angeles in 2015
data = (
    ClimateData()
    .catalog("cadcat")
    .activity_id("WRF")
    .institution_id("UCLA")
    .table_id("mon")
    .grid_label("d03")
    .variable_id("t2max")
    .processes({
        "time_slice": ("2015-01-01", "2015-12-31"),
        "clip": "Los Angeles",
    })
    .get()
)

# Data is returned as a lazy xarray Dataset
print(data)
```

> The legacy `climakitae.core.data_interface` APIs are deprecated and scheduled for removal in `2.0.0`, targeting late Q1 2027. Existing calls may emit `DeprecationWarning`; new work should use `ClimateData` from `climakitae.new_core`.

`source_id()` accepts one model name as a string or several names as a list or
tuple. For example, to request these LOCA2 models together:

```python
models = (
    ClimateData()
    .catalog("cadcat")
    .activity_id("LOCA2")
    .institution_id("UCSD")
    .source_id(["CESM2-LENS", "CNRM-ESM2-1"])
    .experiment_id(["historical", "ssp370"])
    .table_id("day")
    .grid_label("d03")
    .variable_id("tasmax")
    .get()
)
```

Pass a single string to select one source, or a list or tuple of source IDs to
select multiple sources in one query.

## Documentation

| Resource | Description |
|----------|-------------|
| [**Installation Guide**](https://github.com/cal-adapt/climakitae/wiki) | Casual, power-user, and developer installs |
| [**AE Navigation Guide**](https://github.com/cal-adapt/cae-notebooks/blob/main/AE_navigation_guide.ipynb) | Interactive notebook tutorial |
| [**API Reference**](https://cal-adapt.github.io/climakitae/dev/) | Complete API documentation |
| [**AE Notebooks**](https://github.com/cal-adapt/cae-notebooks) | Sample notebooks and scripts |
| [**Contributing**](https://github.com/cal-adapt/climakitae/blob/main/docs-mkdocs/contributing.md) | Development guidelines |

## Contributing

We welcome contributions! Please see our [contributing guidelines](https://github.com/cal-adapt/climakitae/blob/main/docs-mkdocs/contributing.md) for details on:

- 🐛 Reporting bugs
- 💡 Requesting features
- 🔧 Submitting code changes
- 📖 Improving documentation

For setting up a development environment (editable install, tests, formatters), see the [Installation Guide on the wiki](https://github.com/cal-adapt/climakitae/wiki).

When opening a pull request, please tag at least two project maintainers for review.

## License

This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.

## Related Projects

- [**climakitaegui**](https://github.com/cal-adapt/climakitaegui) - Interactive GUI tools for climakitae
- [**cae-notebooks**](https://github.com/cal-adapt/cae-notebooks) - Example notebooks and tutorials

## Support

- 📧 **Email**: [analytics@cal-adapt.org](mailto:analytics@cal-adapt.org)
- 🐛 **Issues**: [GitHub Issues](https://github.com/cal-adapt/climakitae/issues)
- 💬 **Discussions**: [GitHub Discussions](https://github.com/cal-adapt/climakitae/discussions)

---

## Contributors

[![Contributors](https://contrib.rocks/image?repo=cal-adapt/climakitae)](https://github.com/cal-adapt/climakitae/graphs/contributors)


---

## General External Boundary Datasets Disclaimer
Climakitae includes multiple external boundary datasets from government and institutional sources to provide geographic context and geospatial clipping for climate analysis. These datasets are reference information and have limitations. 
### Data Sources & Currency
Boundary data in climakitae comes from various official sources and reflects information available at the time of integration. Source agencies update their boundaries periodically, so this data may not capture the most recent changes or all contemporary territorial claims and interests.For more information about each boundary dataset, please reference the README file in our AWS bucket. 
### Representation & Authority
Equal representation of all communities, and equal capacity for advocacy and participation in decision-making, requires more than the availability of geographic boundary data. Boundaries shown in climakitae are one source of information and do not fully capture the complexity of governance, jurisdictional authority, or community interests. 
### Reference Layer Only
External boundary data should be used as a reference layer for geographic analysis and context. 
### Data Verification
Climakitae does not independently verify external boundary information. For critical applications, authoritative sources, official documentation, and representatives of relevant organizations and communities are the primary references. 
### Feedback
If you have feedback or notice an issue with the boundary data, please email us at support@cal-adaport.org or report an issue on climakitae’s Github repository. 


## Tribal Boundaries Disclaimer
Climakitae tribal boundary data comes from the U.S. Department of Interior Bureau of Indian Affairs (BIA) GeoSpatial Data Repository (https://biamaps.geoplatform.gov/server/rest/services/BOGS/RTV_VIEWER/MapServer).  Equal representation of all tribal perspectives, and equal capacity for advocacy in decision-making, requires more than the availability of this data.
