Usage

Query a local database

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

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

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])

Filtering scenarios and regions

Both gcamreader.LocalDBConn.runQuery() and gcamreader.RemoteDBConn.runQuery() accept scenarios and regions arguments to filter the results. When regions is omitted, the region filter parsed from the query XML is used.

df = conn.runQuery(
    queries[0],
    scenarios=["Reference"],
    regions=["USA", "China"],
)