Metadata-Version: 2.4
Name: gcamreader
Version: 1.5.0
Summary: Tools for importing GCAM output data
Author: Robert Link
Author-email: "Chris R. Vernon" <chris.vernon@pnnl.gov>, Pralit Patel <pralit.patel@pnnl.gov>
Maintainer-email: "Chris R. Vernon" <chris.vernon@pnnl.gov>, Pralit Patel <pralit.patel@pnnl.gov>
License: BSD-2-Clause
Project-URL: Homepage, https://github.com/JGCRI/gcamreader
Project-URL: Documentation, https://jgcri.github.io/gcamreader/
Project-URL: Source, https://github.com/JGCRI/gcamreader
Project-URL: Issues, https://github.com/JGCRI/gcamreader/issues
Keywords: gcam,energy,land,water,climate,xml,basex
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31
Requires-Dist: pandas>=2.0
Requires-Dist: lxml>=5.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: ruff>=0.6; extra == "dev"
Requires-Dist: black>=24.0; extra == "dev"
Requires-Dist: build>=1.2; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0; extra == "docs"
Requires-Dist: furo>=2024.1.29; extra == "docs"
Requires-Dist: myst-parser>=3.0; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints>=2.0; extra == "docs"
Dynamic: license-file

<p align="center">
  <img src="docs/_static/gcamreader-logo-white.png" alt="gcamreader logo" width="400" />
</p>

[![build](https://github.com/JGCRI/gcamreader/actions/workflows/build.yml/badge.svg)](https://github.com/JGCRI/gcamreader/actions/workflows/build.yml)
[![docs](https://github.com/JGCRI/gcamreader/actions/workflows/docs.yml/badge.svg)](https://github.com/JGCRI/gcamreader/actions/workflows/docs.yml)
[![lint](https://github.com/JGCRI/gcamreader/actions/workflows/lint.yml/badge.svg)](https://github.com/JGCRI/gcamreader/actions/workflows/lint.yml)
[![DOI](https://zenodo.org/badge/100425913.svg)](https://zenodo.org/badge/latestdoi/100425913)

# gcamreader: a Python package for extracting content from GCAM databases

`gcamreader` provides functions for reading data from the output databases
produced by [GCAM](https://github.com/JGCRI/gcam-core).

## Purpose

`gcamreader` was created to:

- Use XML queries to extract data into a pandas DataFrame from a GCAM XML
  database.
- Integrate GCAM with other Python packages.

## Requirements

- Python 3.11 or newer.
- A Java runtime (JRE). `gcamreader` runs queries against local databases using
  a bundled copy of the GCAM ModelInterface, which requires Java. Remote queries
  use the BaseX REST API and also rely on a server running ModelInterface.

## Installation

### Set up a virtual environment

It is recommended to install `gcamreader` into an isolated virtual environment
to avoid conflicts with other packages on your system.

Using the built-in `venv` module:

```bash
# Create a virtual environment in a directory named ".venv".
python -m venv .venv

# Activate it (macOS / Linux).
source .venv/bin/activate

# Activate it (Windows PowerShell).
.venv\Scripts\Activate.ps1
```

Alternatively, with `conda`:

```bash
conda create -n gcamreader python=3.11
conda activate gcamreader
```

Once the environment is activated, install `gcamreader` using one of the
methods below. To leave the environment when you are finished, run `deactivate`
(`venv`) or `conda deactivate` (`conda`).

Install the latest release from PyPI:

```bash
pip install gcamreader
```

Install the development version from source:

```bash
git clone https://github.com/JGCRI/gcamreader.git
cd gcamreader
pip install -e .
```

To work on the package, install the development and documentation extras:

```bash
pip install -e ".[dev,docs]"
```

## Quickstart

### Query a local database

```python
import gcamreader

# Connect to a local GCAM database (the parent directory and database name).
conn = gcamreader.LocalDBConn("path/to/output", "database_basexdb")

# List the scenarios contained in the database.
scenarios = conn.listScenariosInDB()

# Parse a GCAM queries XML file and run the first query.
queries = gcamreader.parse_batch_query("Main_queries.xml")
df = conn.runQuery(queries[0])
```

### Run many queries at once

```python
import gcamreader

results = gcamreader.importdata(
    "path/to/output/database_basexdb",
    "Main_queries.xml",
)

# results is a dict keyed by query title, with DataFrame values.
for title, frame in results.items():
    print(title, None if frame is None else frame.shape)
```

### Query a remote database

```python
import gcamreader

conn = gcamreader.RemoteDBConn(
    dbfile="database_basexdb",
    username="user",
    password="secret",
    address="localhost",
    port=8984,
)
df = conn.runQuery(gcamreader.parse_batch_query("Main_queries.xml")[0])
```

## Command line interface

`gcamreader` installs a `gcamreader` command for running the queries in a
queries file and saving each result to a CSV file.

```bash
# Show the version.
gcamreader --version

# Query a local database and write CSV outputs to a directory.
gcamreader local \
    --database_path path/to/output/database_basexdb \
    --query_path Main_queries.xml \
    --output_path results/ \
    --force

# Query a remote BaseX server.
gcamreader remote \
    --username user \
    --database_name database_basexdb \
    --query_path Main_queries.xml \
    --output_path results/ \
    --hostname localhost \
    --port 8984
```

Use `gcamreader --help`, `gcamreader local --help`, or
`gcamreader remote --help` for the full list of options.

## Documentation

Full documentation, including the API reference, is available at
[https://jgcri.github.io/gcamreader/](https://jgcri.github.io/gcamreader/).

## Contributing

Contributions are welcome. Please run the test suite and the linters before
opening a pull request:

```bash
pytest
ruff check .
black --check .
```

## Citation

If you use `gcamreader` in your work, please cite it using the DOI badge above.

## License

`gcamreader` is released under the BSD 2-Clause License. See the
[LICENSE](LICENSE) file for details.
