Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/daffidwilde/edolab
A command line tool for running experiments with `edo`.
https://github.com/daffidwilde/edolab
Last synced: 7 days ago
JSON representation
A command line tool for running experiments with `edo`.
- Host: GitHub
- URL: https://github.com/daffidwilde/edolab
- Owner: daffidwilde
- License: mit
- Created: 2020-08-04T10:06:47.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2021-01-03T16:35:25.000Z (almost 4 years ago)
- Last Synced: 2024-11-04T14:20:13.350Z (16 days ago)
- Language: Python
- Size: 75.2 KB
- Stars: 0
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
Awesome Lists containing this project
README
# edolab
[](https://pypi.org/project/edolab/)
[](https://github.com/psf/black)
[](https://doi.org/10.5281/zenodo.3979467)
A command line tool for running experiments with
[`edo`](https://github.com/daffidwilde/edo).
## Installation
`edolab` is `pip`-installable:
```
$ python -m pip install edolab
```
## Usage
### Experiment scripts
To use `edolab`, you will need to write a Python script configuring the
parameters of your experiment.
#### Required parameters
- `fitness`: A function that takes (at least) an `edo.Individual` instance
to be used as the fitness function by `edo`
- `distributions`: A list of `edo.distribution.Distribution` subclasses that
will be used to create the `edo.Family` instances for `edo`
- Variable assignments for all of the essential arguments in
`edo.DataOptimiser` except for `families`
#### Optional parameters
- `root`: A directory to which data should be written (and summarised from)
- `processes`: A number of processes for `edo` to use when calculating
population fitness
- Custom column distribution classes should be defined in the script
- If you wish to use a custom `stop` or `dwindle` method then define a subclass
of `edo.DataOptimiser` and assign that class to a variable called `optimiser`
- Any keyword arguments to pass to `fitness` or the `stop` and `dwindle` methods
should be assigned to the corresponding `_kwargs` variable.
An example of such a script would be something like this:
```python
""" /path/to/experiment/script.py """
import edo
import numpy as np
from edo.distributions import Uniform
class CustomOptimiser(edo.DataOptimiser):
""" This is an optimiser with custom stopping and dwindling methods. """
def stop(self, tol):
""" Stop if the median fitness is less than `tol` away from zero. """
self.converged = abs(np.median(self.pop_fitness)) < tol
def dwindle(self, rate):
""" Cut the mutation probability in half every `rate` generations. """
if self.generation % rate == 0:
self.mutation_prob /= 2
def fitness(individual, size, seed=0):
""" Randomly sample `size` values from an individual and return the
minimum. """
np.random.seed(seed)
values = individual.dataframe.values.flat
sample = np.random.choice(values, size=size)
return min(sample)
class NegativeUniform(Uniform):
""" A copy that only takes negative values. """
name = "NegativeUniform"
param_limits = {"bounds": [-1, 0]}
hard_limits = {"bounds": [-100, 0]}
size = 5
row_limits = [1, 5]
col_limits = [1, 2]
max_iter = 3
best_prop = 0.5
mutation_prob = 0.5
Uniform.param_limits["bounds"] = [0, 1]
distributions = [Uniform, NegativeUniform]
optimiser = CustomOptimiser
fitness_kwargs = {"size": 3}
stop_kwargs = {"tol": 1e-3}
dwindle_kwargs = {"rate": 10}
```
For more details on the parameters of `edo`, see its documentation:
### Running the experiment
Then, to run an experiment with this script do the following:
```
$ edolab run /path/to/experiment/script.py
```
### Summarising the experiment
And to summarise the data (for easy transfer):
```
$ edolab summarise /path/to/experiment/script.py
```
For further details on the commands, use the `--help` flag on the `run` and
`summarise` commands.
### A note on reproducibility
It is highly recommended that you use a virtual environment when using `edo` in
or outside of this command line tool as `edo` uses `pickle` to store various
objects created in a run that may not be retrievable with a different version of
Python.
## Contributing
This tool has been made to be pretty bare and could use some padding out. If
you'd like to contribute then make a fork and clone the repository locally:
```
$ git clone https://github.com//edolab.git
```
Install the package and replicate the `conda` environment (or install the
development dependencies manually):
```
$ cd edolab
$ python setup.py develop
$ conda env create -f environment.yml
$ conda activate edolab-dev
```
Make your changes and write tests to go with them, ensuring they pass:
```
$ python -m pytest --cov=edolab --cov-fail-under=100 tests
```
Commit, push to your fork and open a pull request!