Metadata-Version: 2.1
Name: scihence
Version: 0.0.0
Summary: Henry's tools in Python.
Home-page: https://gitlab.com/HennersBro98/scihence
Author: Henry Broomfield
License: (C) Henry Broomfield
        
Requires-Python: >=3.11.0,<3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib <4,>=3.5.0
Requires-Dist: mlflow <3,>=2.1.1
Requires-Dist: numpy <2,>=1.23.0
Requires-Dist: pandas <3,>=2.0.0
Requires-Dist: Pillow <11,>=10.0.0
Requires-Dist: plotly <8,>=5.0.0
Requires-Dist: seaborn <1,>=0.12.0
Requires-Dist: xgboost <2,>=1.7.0
Provides-Extra: build
Requires-Dist: build ; extra == 'build'
Requires-Dist: tox ; extra == 'build'
Provides-Extra: check
Requires-Dist: pre-commit ; extra == 'check'
Requires-Dist: tox ; extra == 'check'
Provides-Extra: dev
Requires-Dist: build ; extra == 'dev'
Requires-Dist: tox ; extra == 'dev'
Requires-Dist: pre-commit ; extra == 'dev'
Requires-Dist: furo ; extra == 'dev'
Requires-Dist: sphinx ; extra == 'dev'
Requires-Dist: ruff ; extra == 'dev'
Requires-Dist: twine ; extra == 'dev'
Requires-Dist: junit2html ; extra == 'dev'
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-cov ; extra == 'dev'
Provides-Extra: docs
Requires-Dist: furo ; extra == 'docs'
Requires-Dist: pre-commit ; extra == 'docs'
Requires-Dist: sphinx ; extra == 'docs'
Requires-Dist: tox ; extra == 'docs'
Provides-Extra: lint
Requires-Dist: ruff ; extra == 'lint'
Requires-Dist: tox ; extra == 'lint'
Provides-Extra: pub
Requires-Dist: twine ; extra == 'pub'
Provides-Extra: test
Requires-Dist: junit2html ; extra == 'test'
Requires-Dist: pytest ; extra == 'test'
Requires-Dist: pytest-cov ; extra == 'test'
Requires-Dist: tox ; extra == 'test'

# Scihence

Henry's tools for doing science.

## Table of Contents

- [Scihence](#scihence)
  - [Table of Contents](#table-of-contents)
  - [Usage](#usage)
    - [Pipelines](#pipelines)
  - [Development](#development)
    - [Workflow](#workflow)
    - [Setup](#setup)
  - [Unit and integration tests](#unit-and-integration-tests)
    - [Documentation](#documentation)
    - [Acceptance testing](#acceptance-testing)
    - [Versions](#versions)
      - [Non-release versions](#non-release-versions)
  - [TODO](#todo)

## Usage

Installation:
```zsh
pip install scihence
```

Importing:
```zsh
import scihence
```

> Note: PyTorch is not automatically installed since it can be cumbersome depending on which CUDA dependencies are required. You can find out how to install the specific version for you on [PyTorch's website](https://pytorch.org/get-started/locally/).

### Pipelines

To explore the outputs of a pipeline:
- In a terminal window, fill in the `PATH/TO/DIR_WHERE_PIPELINE_EXECUTED`, and run:
    ```zsh
    cd PATH/TO/DIR_WHERE_PIPELINE_EXECUTED && mlflow ui
    ```
- Navigate to your specified experiment (`Default` if not set), and explore the results.

## Development

### Workflow

```mermaid
graph TD;
   master(Master branch):::masterclass-->dev
   dev(Dev branch):::devclass-->feature
   feature(Feature branch):::featclass-->changes
   changes(Make changes):::featclass-->document
   document(Document):::featclass-->test
   test(Test):::featclass-->passing
   passing{Passing?}:::featclass
   passing--No-->changes
   passing--Yes-->push
   push(Push):::featclass-->pr
   pr(Pull request):::featclass
   pr--Contributer-->approved
   pr--CI/CD-->approved
   pr--Reviewer-->approved
   approved{Approved?}:::featclass
   approved--No-->changes
   approved--Yes-->merge
   merge(Dev branch):::devclass-->release
   dev-->merge
   release{Release?}:::devclass
   release--No-->feature
   release--Yes-->pr2
   pr2(Pull request):::devclass
   pr2--CI/CD-->approved2
   pr2--Reviewer-->approved2
   approved2{Approved?}:::devclass
   approved2--Yes-->master2
   approved2--No-->dev
   master2(Master branch):::masterclass
   master-->master2

   classDef masterclass fill:#000035, stroke:#000035, color:#c0c0c0;
   classDef devclass fill:#552777, stroke:#552777, color:#aaddff;
   classDef featclass fill:#aaddff, stroke:#aaddff, color:#000035;

   linkStyle 22 fill:none, stroke:#000035,stroke-width:2px;
   linkStyle 0,14,15,18,19 fill:none, stroke:#552777,stroke-width:2px;
   linkStyle 1,2,3,4,5,8,9,10,11 fill:none, stroke:#aaddff,stroke-width:2px;
   linkStyle 7,13,17,20 fill:none, stroke:#c0c0c0,stroke-width:2px;
   linkStyle 6,12,16,21 fill:none, stroke:#ff0000,stroke-width:2px;
```

### Setup

1. Ensure `pyenv` is installed on your device.
1. Substituting the Python version, run the following code in the terminal at the root of the repository directory:

    ```zsh
    make env v=3.a.b && source .venv/bin/activate
    ```

## Unit and integration tests

To run unit and integration tests, run the following code in the terminal at the root of the repository directory:

```zsh
pytest --junit-xml=docs/source/test-report/local/junit/report.xml
coverage html -d docs/source/test-report/local/coverage
python -m tests.build_junit_report \
    docs/source/test-report/local/junit/report.xml \
    docs/source/test-report/local/junit/report.html
```

### Documentation

The live version of the documentation can be found [here](https://hennersbro98.gitlab.io/scihence).

To build documentation, in your environment run the following code in the terminal at the root of the repository directory:

```zsh
make docs
```

You can view the built documentation using:

```zsh
open docs/build/html/index.html
```

> Note: Documentation building searches for and includes test run artifacts that are produced using scripts similar to the one in [Testing](#testing). It will still build if not present, but code coverage and the JUnit reports will not be included.

### Acceptance testing

In your environment, run the following code in the terminal at the root of the repository directory, replacing and including python versions that are supported:

```zsh
pyenv shell 3.11.a 3.11.b && tox
```

### Versions

> Note: Versioning should only occur for the master branch.

- Before merging, ensure that the version number listed in `src/scihence/__init__.py` is updated.
- Version numbers are usually given as `major.minor.patch`. This is how the `__version__` variable in [`__init__.py`](src/scihence/__init__.py) should be specified when merging from `dev` into `master`.
- Having specified the `__version__` correctly before merging into `master`, [GitLab CI](.gitlab-ci.yml) will take care of packaging and releasing automatically.
- When creating a development version that you would like to upload to the package index, version numbers such as `major.minor.patch.devN` can be used, for example, `0.1.2.dev0` would be the first development release of version `0.1.2`.
- Similarly, alpha, beta, and release candidate releases can be versioned using the semantic notation `0.1.2a0`, `0.1.2b0`, `0.1.2rc0` respectively (without the 3rd `.`).

#### Non-release versions

Non-release versions of `scihence` that are in a merge request will automatically have a version created with the GitLab CI job ID appended as metadata. For example, a push of `0.1.2.dev12` that builds the package in a job with ID `987654321` would be uploaded to the [`scihence` development package registry](https://gitlab.com/HennersBro98/scihence/-/packages/) as version `0.1.2.dev12+job987654321`. This could then be installed locally for testing purposes using

```zsh
pip install scihence==0.1.2.dev12+job987654321
```

The extra index URL for this package registry where `pip` will look should already be configured in the `.venv/pip.conf` provided your environment was initially created using `make env`.

## TODO

- `tox -e py311-wheel` does not use wheel
- Test everything
- Document everything
- Save documentation and packages for individual commits
- Generalise to reinforcement learning pipeline
- Ensure accepts GNN inputs
