baringa-coral 2025.1
CORe Analytics Library for PLCS
Requires Python: >=3.11

# CORAL
The **COR**e **A**nalytical **L**ibrary is a set of Python libraries intended to be used across PLCS. It consists of:

* **coral** core functionality for working with time series and shape
* **coral-data** retrieving time series and other data from the various Baringa databases
* **coral-sim** stochastic simulations
* **coral-asset** price-taker asset modelling

## Getting Started
To include CORAL in your project, use [Poetry](https://baringa.atlassian.net/wiki/spaces/BEACH/pages/2310766593/Python+Poetry) for package management and make sure to use Python 3.11 or later.

There three different methods of adding a dependency to Coral

## Development

### NOX

[Nox]("https://nox.thea.codes/en/stable/") is used to run our tests and quality checks in our CI pipeline and can also be used locally.

Install nox globally (preferably using `uv tool install` or `pipx install`)

From the root of your repo you can run:

```
nox -l       # list all available sessions.
nox          # run all avaliable sessions
nox -s test  # run all test sessions
```


### JFrog
*Not currently set up - details to be provided later*

### Azure DevOps Git Repo
Add a dependency to the coral package in git by include the following line in your pyproject.toml file:

```
baringa_coral = { git = "https://baringa@dev.azure.com/baringa/plcs/_git/coral" }
```

it is also possible to link to a specific branch:

```
baringa_coral = { git = "https://baringa@dev.azure.com/baringa/plcs/_git/coral", branch = "experimental" }
```


### Local Directory
If you intent on developing on the Coral library itself while using it in another project, it is easiest to use git to obtain a local copy of the library and then use your local copy in editable mode:

```
baringa_coral = { path = "C:/local/path/to/coral", develop = true }
```

# Documentation and Examples
We are using Sphinx to create API Documentation for the code. The general documentation on CORAL is available in
[Confluence](https://baringa.atlassian.net/wiki/spaces/PA/pages/2556788744/CORAL+-+Overview). Documentation is work in progress. 

We use Sphinx for the API Documentation. The structure of the documentation is defined in .rst files in the 
*api_documentation* folder. The documentation of classes, modules and functions is derived from the docstrings of our
code. We use [Google](https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings) conventions for 
docstrings. 

You can create an HTML version of the documentation by running the `make html` command
inside the api_documentation folder. A _build folder will be created with html files.

You can also push the documentation to Confluence. The documentation for CORAL is published at: 
https://baringa.atlassian.net/wiki/spaces/PA/pages/2625470574/CORAL+API+Documentation. To publish the documentation
take these steps:
1. Create an API key for Atlassian (https://id.atlassian.com/manage-profile/security/api-tokens) and save it somewhere
2. Edit the conf.py file in the`api_documentation` folder and update it with your username (email address)
3. Run the command `make confluence` inside the api_documentation folder
4. When asked for your password, use the API key you've saved in step 1.

# Contribute
Library development is managed by PLCS/Analytical Solutions. For questions, feature requests or issues, contact either [Daniel](mailto:daniel.vanderzee@baringa.com) or [Caitlin](mailto:Caitlin.WordenHodge@baringa.com).

Feedback is much appreciated!