Skip to content

Commit

Permalink
Documentation Part 2 (automl#116)
Browse files Browse the repository at this point in the history 
* Docstrings updated + Merging

Create docstrings. The documentation is updated, so that it will be created from the docstrings.
Start to merge with new commits of the forked repo.

* undo merge in json.py.

* Fix installation hint

* Change docstring format to NumPy

* update documentation, include requests

* Removed typo

* check of signatures

* Undo change in add_forbidden_components(..)

* Examples in Docstrings are testable.

Fix minor issues

* update Documentation

* Running Doctest from documentation from travis

* minor text improvements

* revert documentation target

* Update on PR

- Rename Guide to User-Guide.
- Fix output of tests (Formatting)
- Remove Sphinx-Gallery and auto examples
- Correct Typos
- Fix doctest irregularity: The sphinx doctest blocks "sometimes" work with a single ">>>". But in the case that the output of the doctest block produces a new blank line at the end, doctest blocks starting with a ">>>" dont remove the <BLANKLINE> from the output. In those cases, I switched from ">>>" to ".. doctest::". Actually this should be equivalent but somehow fixes the wrong behavior.

* Update PR

- incorporate request
- But haven't fixed the auto deploy of the docs!

* Fix Doctest

* update the doc building process

* remove local commands from Makefile
  • Loading branch information
@PhMueller @mfeurer
PhMueller authored and mfeurer committed Sep 30, 2019
1 parent e05490a commit 0fb684a
Show file tree
Hide file tree
Showing 16 changed files with 1,028 additions and 916 deletions.
2 changes: 1 addition & 1 deletion .travis.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -29,9 +29,9 @@ script:
./ci_scripts/flake8_diff.sh
fi
pytest -sv --cov=ConfigSpace test
- source ci_scripts/create_doc.sh $TRAVIS_BRANCH "doc_result"

after_success:
- source ci_scripts/create_doc.sh $TRAVIS_BRANCH "doc_result"
- codecov

deploy:
Expand Down
56 changes: 41 additions & 15 deletions ConfigSpace/conditions.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,9 +198,13 @@ cdef class EqualsCondition(AbstractCondition):
>>> a = CSH.CategoricalHyperparameter('a', choices=[1, 2, 3])
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
>>> cs.add_hyperparameters([a, b])
# makes 'b' an active hyperparameter if 'a' has the value 1
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]

make *b* an active hyperparameter if *a* has the value 1

>>> cond = CS.EqualsCondition(b, a, 1)
>>> cs.add_condition(cond)
b | a == 1

Parameters
----------
Expand All @@ -209,7 +213,7 @@ cdef class EqualsCondition(AbstractCondition):
if the *equal condition* is satisfied
parent : :ref:`Hyperparameters`
The hyperparameter, which has to satisfy the *equal condition*
value : (str, float, int)
value : str, float, int
Value, which the parent is compared to
"""

Expand Down Expand Up @@ -270,9 +274,13 @@ cdef class NotEqualsCondition(AbstractCondition):
>>> a = CSH.CategoricalHyperparameter('a', choices=[1, 2, 3])
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
>>> cs.add_hyperparameters([a, b])
# makes 'b' an active hyperparameter if 'a' has **not** the value 1
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]

make *b* an active hyperparameter if *a* has **not** the value 1

>>> cond = CS.NotEqualsCondition(b, a, 1)
>>> cs.add_condition(cond)
b | a != 1

Parameters
----------
Expand All @@ -282,7 +290,7 @@ cdef class NotEqualsCondition(AbstractCondition):
parent : :ref:`Hyperparameters`
The hyperparameter, which has to satisfy the
*not equal condition*
value : (str, float, int)
value : str, float, int
Value, which the parent is compared to

"""
Expand Down Expand Up @@ -342,9 +350,13 @@ cdef class LessThanCondition(AbstractCondition):
>>> a = CSH.UniformFloatHyperparameter('a', lower=0., upper=10.)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
>>> cs.add_hyperparameters([a, b])
# makes 'b' an active hyperparameter if 'a' is less than 5
[a, Type: UniformFloat, Range: [0.0, 10.0], Default: 5.0, b, Type: ...]

make *b* an active hyperparameter if *a* is less than 5

>>> cond = CS.LessThanCondition(b, a, 5.)
>>> cs.add_condition(cond)
b | a < 5.0

Parameters
----------
Expand All @@ -353,7 +365,7 @@ cdef class LessThanCondition(AbstractCondition):
if the *LessThanCondition* is satisfied
parent : :ref:`Hyperparameters`
The hyperparameter, which has to satisfy the *LessThanCondition*
value : (str, float, int)
value : str, float, int
Value, which the parent is compared to

"""
Expand Down Expand Up @@ -411,13 +423,17 @@ cdef class GreaterThanCondition(AbstractCondition):

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformFloatHyperparameter('a', lower=0., upper=10.)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
>>> cs.add_hyperparameters([a, b])
# makes 'b' an active hyperparameter if 'a' is greater than 5
[a, Type: UniformFloat, Range: [0.0, 10.0], Default: 5.0, b, Type: ...]

make *b* an active hyperparameter if *a* is greater than 5

>>> cond = CS.GreaterThanCondition(b, a, 5.)
>>> cs.add_condition(cond)
b | a > 5.0

Parameters
----------
Expand All @@ -426,7 +442,7 @@ cdef class GreaterThanCondition(AbstractCondition):
if the *GreaterThanCondition* is satisfied
parent : :ref:`Hyperparameters`
The hyperparameter, which has to satisfy the *GreaterThanCondition*
value : (str, float, int)
value : str, float, int
Value, which the parent is compared to

"""
Expand Down Expand Up @@ -486,13 +502,17 @@ cdef class InCondition(AbstractCondition):

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=0, upper=10)
>>> b = CSH.UniformFloatHyperparameter('b', lower=1., upper=8., log=False)
>>> cs.add_hyperparameters([a, b])
# makes 'b' an active hyperparameter if 'a' is in the set [1, 2, 3, 4]
[a, Type: UniformInteger, Range: [0, 10], Default: 5, b, Type: ...]

make *b* an active hyperparameter if *a* is in the set [1, 2, 3, 4]

>>> cond = CS.InCondition(b, a, [1, 2, 3, 4])
>>> cs.add_condition(cond)
b | a in {1, 2, 3, 4}

Parameters
----------
Expand All @@ -501,7 +521,7 @@ cdef class InCondition(AbstractCondition):
if the *InCondition* is satisfied
parent : :ref:`Hyperparameters`
The hyperparameter, which has to satisfy the *InCondition*
values : list([str, float, int])
values : list(str, float, int)
Collection of values, which the parent is compared to

"""
Expand Down Expand Up @@ -716,7 +736,7 @@ cdef class AbstractConjunction(ConditionComponent):

cdef class AndConjunction(AbstractConjunction):
# TODO: test if an AndConjunction results in an illegal state or a
# Tautology! -> SAT solver
# Tautology! -> SAT solver
def __init__(self, *args: AbstractCondition) -> None:
"""
By using the *AndConjunction*, constraints can easily be connected.
Expand All @@ -728,14 +748,17 @@ cdef class AndConjunction(AbstractConjunction):

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=5, upper=15)
>>> b = CSH.UniformIntegerHyperparameter('b', lower=0, upper=10)
>>> c = CSH.UniformFloatHyperparameter('c', lower=0., upper=1.)
>>> cs.add_hyperparameters([a, b, c])
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]

>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
>>> cs.add_condition(CS.AndConjunction(less_cond, greater_cond))
(c | a < 10 && c | b > 5)

Parameters
----------
Expand Down Expand Up @@ -788,14 +811,17 @@ cdef class OrConjunction(AbstractConjunction):

>>> import ConfigSpace as CS
>>> import ConfigSpace.hyperparameters as CSH
>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.UniformIntegerHyperparameter('a', lower=5, upper=15)
>>> b = CSH.UniformIntegerHyperparameter('b', lower=0, upper=10)
>>> c = CSH.UniformFloatHyperparameter('c', lower=0., upper=1.)
>>> cs.add_hyperparameters([a, b, c])
[a, Type: UniformInteger, Range: [5, 15], Default: 10, b, Type: ...]

>>> less_cond = CS.LessThanCondition(c, a, 10)
>>> greater_cond = CS.GreaterThanCondition(c, b, 5)
>>> cs.add_condition(CS.OrConjunction(less_cond, greater_cond))
(c | a < 10 || c | b > 5)

Parameters
----------
Expand Down
43 changes: 23 additions & 20 deletions ConfigSpace/configuration_space.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,11 +78,11 @@ class ConfigurationSpace(object):

Parameters
----------
name : (str, optional)
name : str, optional
Name of the configuration space
seed : (int, optional)
seed : int, optional
random seed
meta : (dict, optional)
meta : dict, optional
Field for holding meta data provided by the user.
Not used by the configuration space.
"""
Expand Down Expand Up @@ -124,7 +124,7 @@ class ConfigurationSpace(object):

Parameters
----------
bounds : list(list([Any, Any)])
bounds : list[tuple([Any, Any])]
List containing lists with two elements: lower and upper bound
"""
for i, (l, u) in enumerate(bounds):
Expand Down Expand Up @@ -218,7 +218,7 @@ class ConfigurationSpace(object):
- The parent in a condition statement must exist
- The condition must add no cycles

The following array keeps track of all edges which must be
The internal array keeps track of all edges which must be
added to the DiGraph; if the checks don't raise any Exception,
these edges are finally added at the end of the function.

Expand Down Expand Up @@ -615,9 +615,9 @@ class ConfigurationSpace(object):
forbidden clauses
configuration_space : :class:`~ConfigSpace.configuration_space.ConfigurationSpace`
The configuration space which should be added
delimiter : (str, optional)
Defaults to '':''.
parent_hyperparameter : (:ref:`Hyperparameters`, optional)
delimiter : str, optional
Defaults to ':'
parent_hyperparameter : :ref:`Hyperparameters`, optional
Adds for each new hyperparameter the condition, that
``parent_hyperparameter`` is active

Expand Down Expand Up @@ -848,7 +848,7 @@ class ConfigurationSpace(object):

Parameters
----------
name : (str, :ref:`Hyperparameters`)
name : str, :ref:`Hyperparameters`
Hyperparameter or its name, for which all children are requested

Returns
Expand Down Expand Up @@ -877,7 +877,7 @@ class ConfigurationSpace(object):

Parameters
----------
name : (str, :ref:`Hyperparameters`)
name : str, :ref:`Hyperparameters`
Hyperparameter or its name, for which conditions are requested

Returns
Expand Down Expand Up @@ -905,7 +905,7 @@ class ConfigurationSpace(object):

Parameters
----------
name : (str, :ref:`Hyperparameters`)
name : str, :ref:`Hyperparameters`
Can either be the name of a hyperparameter or the hyperparameter
object

Expand Down Expand Up @@ -946,7 +946,7 @@ class ConfigurationSpace(object):

Parameters
----------
name : (str, :ref:`Hyperparameters`)
name : str, :ref:`Hyperparameters`
Can either be the name of a hyperparameter or the hyperparameter
object

Expand Down Expand Up @@ -1060,7 +1060,7 @@ class ConfigurationSpace(object):

def check_configuration_vector_representation(self, vector: np.ndarray) -> None:
"""
Raise error f configuration in vector representation is not legal.
Raise error if configuration in vector representation is not legal.

Parameters
----------
Expand Down Expand Up @@ -1214,7 +1214,7 @@ class ConfigurationSpace(object):

Parameters
----------
size : (int, optional)
size : int, optional
Number of configurations to sample. Default to 1

Returns
Expand Down Expand Up @@ -1321,23 +1321,26 @@ class Configuration(object):
:class:`~ConfigSpace.configuration_space.ConfigurationSpace` stores the
definitions for the hyperparameters (value ranges, constraints,...), a
:class:`~ConfigSpace.configuration_space.Configuration` object is
more like a instance of it.
more an instance of it. Parameters of a
:class:`~ConfigSpace.configuration_space.Configuration` object can be
accessed and modified similar to python dictionaries
(c.f. :ref:`Guide<1st_Example>`).

Parameters
----------
configuration_space : :class:`~ConfigSpace.configuration_space.ConfigurationSpace`
values : (dict, optional)
values : dict, optional
A dictionary with pairs (hyperparameter_name, value), where value is
a legal value of the hyperparameter in the above
configuration_space
vector : (np.ndarray, optional)
vector : np.ndarray, optional
A numpy array for efficient representation. Either values or vector
has to be given
allow_inactive_with_values : (bool, optional)
allow_inactive_with_values : bool, optional
Whether an Exception will be raised if a value for an inactive
hyperparameter is given. Default is to raise an Exception.
Default to False
origin : (Any, optional)
origin : Any, optional
Store information about the origin of this configuration.
Default to None
"""
Expand Down Expand Up @@ -1459,7 +1462,7 @@ class Configuration(object):
----------
item : str
Name of the desired hyperparameter
default : (None, Any)
default : None, Any

Returns
-------
Expand Down
21 changes: 16 additions & 5 deletions ConfigSpace/forbidden.pyx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -247,9 +247,13 @@ cdef class ForbiddenEqualsClause(SingleValueForbiddenClause):
>>> cs = CS.ConfigurationSpace()
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
>>> cs.add_hyperparameters([a])
# It forbids the value 2 for the hyperparameter a
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1]
It forbids the value 2 for the hyperparameter *a*
>>> forbidden_clause_a = CS.ForbiddenEqualsClause(a, 2)
>>> cs.add_forbidden_clause(forbidden_clause_a)
Forbidden: a == 2
Parameters
----------
Expand Down Expand Up @@ -286,12 +290,16 @@ cdef class ForbiddenInClause(MultipleValueForbiddenClause):
Example
-------

>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
>>> cs.add_hyperparameters([a])
# It forbids the values 2, 3, 4 for the hyperparameter 'a'
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1]

It forbids the values 2, 3, 4 for the hyperparameter *a*

>>> forbidden_clause_a = CS.ForbiddenInClause(a, [2, 3])
>>> cs.add_forbidden_clause(forbidden_clause_a)
Forbidden: a in {2, 3}

Parameters
----------
Expand Down Expand Up @@ -455,18 +463,21 @@ cdef class ForbiddenAndConjunction(AbstractForbiddenConjunction):
Example
-------
>>> cs = CS.ConfigurationSpace()
>>> cs = CS.ConfigurationSpace(seed=1)
>>> a = CSH.CategoricalHyperparameter('a', [1,2,3])
>>> b = CSH.CategoricalHyperparameter('b', [2,5,6])
>>> cs.add_hyperparameters([a, b])
[a, Type: Categorical, Choices: {1, 2, 3}, Default: 1, b, Type: ...]
>>> forbidden_clause_a = CS.ForbiddenEqualsClause(a, 2)
>>> forbidden_clause_b = CS.ForbiddenInClause(b, [2])
>>> forbidden_clause = CS.ForbiddenAndConjunction(forbidden_clause_a, forbidden_clause_b)
>>> cs.add_forbidden_clause(forbidden_clause)
(Forbidden: a == 2 && Forbidden: b in {2})
Parameters
----------
*args : list([:ref:`Forbidden clauses`])
*args : list(:ref:`Forbidden clauses`)
forbidden clauses, which should be combined
"""

Expand Down
Loading

0 comments on commit 0fb684a

Please sign in to comment.