Metadata-Version: 2.1
Name: obplatform
Version: 0.1.4
Summary: APIs to access ASHRAE OB Database
Author: Wei Mu
Author-email: wmu100@syr.edu
Requires-Python: >=3.7.1,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Provides-Extra: pandas
Requires-Dist: pandas (>=1.3.4,<2.0.0); extra == "pandas"
Requires-Dist: requests (>=2.26.0,<3.0.0)
Requires-Dist: tqdm (>=4.62.3,<5.0.0)
Project-URL: Bug Tracker, https://github.com/umonaca/obplatform/issues
Project-URL: homepage, https://ashraeobdatabase.com
Project-URL: repository, https://github.com/umonaca/obplatform
Description-Content-Type: text/markdown

# OBPlatform

A package to interact and download behavior data from [ASHRAE Global Occupant Behavior Database](https://ashraeobdatabase.com). Currently available on PyPI. More features coming in the furture.

[![pypi](https://img.shields.io/pypi/v/obplatform.svg)](https://pypi.python.org/pypi/obplatform) [![CI](https://github.com/umonaca/obplatform/actions/workflows/test.yml/badge.svg?event=push)](https://github.com/umonaca/obplatform/actions?query=event%3Apush+branch%3Amaster) [![codecov](https://codecov.io/gh/umonaca/obplatform/branch/master/graph/badge.svg?token=SCFFFX2IKX)](https://codecov.io/gh/umonaca/obplatform) ![license](https://img.shields.io/github/license/umonaca/obplatform) ![PyPI - Python Version](https://img.shields.io/pypi/pyversions/obplatform) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) [![Read the Docs](https://img.shields.io/readthedocs/obplatform)](https://obplatform.readthedocs.io/en/latest/index.html)

## Features

- List all behavior types available in the database.
- Download data archive (ZIP file) based on behavior type and study id inputs (with progress bar).
- Query studies based on (behaviors, countries, cities, (building type + room type)) (WIP).
- Query available behavior types based on study ids (WIP)

## Installation

### poetry

```
poetry install
```

### pip

```
pip install obplatform
```

### conda

We are going to submit the package to `conda-forge`. It requires manual review process from Anaconda.

## Example

```python
import logging
import zipfile

import pandas as pd
from obplatform import Connector, logger

connector = Connector()

# List all behaviors available in the database
print(connector.list_behaviors())

# Print progress information
# Comment out the following line to hide progress information
logger.setLevel(logging.INFO)

# Download Appliance Usage + Occupant Presence behaviors from study 22, 11, and 2.
connector.download_export(
    "data.zip",
    ["Appliance_Usage", "Occupancy"],
    ["22", "11", "2"],
    show_progress_bar=True,  # False to disable progrees bar
)

behavior_type = "Appliance_Usage"
study_id = "22"

zf = zipfile.ZipFile("data.zip")
df = pd.read_csv(zf.open(f"{behavior_type}_Study{study_id}.csv"))
print(df.head())
```

## Usage

### Available behavior types

Please only use the following names as input. e.g. Please use `Lighting_Status` (listed below) instead of  `Lighting Adjustment`(displayed on the website).

```
'Appliance_Usage', 'Fan_Status', 'Door_Status', 'HVAC_Measurement', 'Lighting_Status', 'Occupant_Number', 'Occupancy', 'Other_HeatWave', 'Other_Role of habits in consumption', 'Other_IAQ in Affordable Housing', 'Shading_Status', 'Window_Status'
```

In the next version, the package will auto detect either type of input and convert to the correct query parameter.

### Note: big data

Study 2 is a special case. It has very large source files (> 2 GB) so we compressed all data in study 2 as a single `.tar.gz`file. In the example above, `data.zip` contains a `tar.gz`file along with several separate csv files from other studies. When writing libraries to read from csv file from the downloaded zip, Study 2 should be treated as a special case.

## Changelog

- 2021-11-18:  Release 0.1.3
- 2021-11-19:  Release 0.1.4, fixed a minor issue with Python 3.10.0

## TODO

- Add function to query available studies based on (behaviors, countries, cities, (building type + room type)) 
- Add function to query available behavior types based on study ids
- Auto detect and convert behavior type inputs to correct query parameters for web API
- Fix naming inconsistencies on the server side (Occupancy Presence on the website, Occupancy_Measurement in file name, Occupancy in API key field)

## API Reference

https://obplatform.readthedocs.io/en/latest/index.html


