sciunit package

Submodules

sciunit.base module

The base class for many SciUnit objects.

class sciunit.base.Config(*args, **kwargs)[source]

Bases: dict

Configuration class for sciunit

__getitem__(key)[source]

x.__getitem__(y) <==> x[y]

__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.base'
__setitem__(key, val)[source]

Set self[key] to value.

__weakref__

list of weak references to the object (if defined)

_path = PosixPath('/home/docs/.sciunit/config.json')
create(data: dict = None) → bool[source]

Create a config file that store any data from the user.

Args:
data (dict): The data that will be written to the new config file.
Returns:
bool: Config file creation is successful
default = {'cmap_high': 218, 'cmap_low': 38, 'cwd': 'sciunit', 'log_level': 20, 'prevalidate': False, 'sciunit_version': None, 'score_log_level': 1}
get(key, default=None, update_from_disk=True)[source]

Return the value for key if key is in the dictionary, else default.

get_from_disk()[source]
load()[source]
path

Guarantees that the requested path will be Path object

save()[source]
set(key, val)[source]
class sciunit.base.QuantitiesHandler(context)[source]

Bases: jsonpickle.handlers.BaseHandler

__module__ = 'sciunit.base'
flatten(obj, data)[source]

This methods flattens all quantities into a base and units

restore(data)[source]

If jsonpickle.encode() is called with unpicklable=True then this method is used by jsonpickle.decode() to unserialize.

class sciunit.base.SciUnit[source]

Bases: sciunit.base.Versioned

Abstract base class for models, tests, and scores.

__getstate__() → dict[source]

Copy the object’s state from self.__dict__.

Contains all of the instance attributes. Always uses the dict.copy() method to avoid modifying the original state.

Returns:
dict: The state of this instance.
__init__()[source]

Instantiate a SciUnit object.

__module__ = 'sciunit.base'
_class
_url = None

A list of attributes that cannot or should not be pickled. A URL where the code for this object can be found.

diff(other, add_props=False)[source]
get_list_attr_with_bases(attr: str) → list[source]

Gets a concatenated list of values for an attribute across all parent classes. The attribute must be a list.

hash(serialization: str = None) → str[source]

A unique numeric identifier of the current state of a SciUnit object.

Returns:
str: The unique numeric identifier of the current model state.
json(add_props: bool = True, string: bool = True, unpicklable: bool = False, make_refs: bool = False) → str[source]

Generate a Json format encoded sciunit instance.

Args:
add_props (bool, optional): Whether to add additional properties of the object to the serialization. Defaults to False. string (bool, optional): The json content will be str type if True, dict type otherwise. Defaults to True.
Returns:
str: The Json format encoded sciunit instance.
properties(keys: list = None, exclude: list = None) → dict[source]

Get the properties of the instance.

Args:
keys (list, optional): If not None, only the properties that are in keys will be included in
the return data. Defaults to None.

exclude (list, optional): The list of properties that will not be included in return data. Defaults to None.

Returns:
dict: The dict of properties of the instance.
property_names() → list[source]

Get the raw properties of the instance.

Returns:
list: The list of raw properties.
state_hide = ['hash', 'pickling', 'temp_dir']
url
verbose = 1

A verbosity level for printing information.

class sciunit.base.SciUnitHandler(context)[source]

Bases: jsonpickle.handlers.BaseHandler

jsonpickle handler for SciUnit objects

__module__ = 'sciunit.base'
add_props = True
flatten(obj, data)[source]

Flatten SciUnit objects

make_refs = False
restore(data)[source]

Restore an object of the registered type from the json-friendly representation obj and return it.

simplify(d)[source]

Set all ‘py/’ key:value pairs to their value

string = True
unpicklable = False
class sciunit.base.TestWeighted[source]

Bases: object

Base class for objects with test weights.

__module__ = 'sciunit.base'
__weakref__

list of weak references to the object (if defined)

weights

Returns a normalized list of test weights.

Returns:
List[float]: The normalized list of test weights.
class sciunit.base.UnitQuantitiesHandler(context)[source]

Bases: jsonpickle.handlers.BaseHandler

Same as above but for unit quantities e.g. Test.units

__module__ = 'sciunit.base'
flatten(obj, data)[source]

Flatten obj into a json-friendly form and write result to data.

Parameters:
  • obj (object) – The object to be serialized.
  • data (dict) – A partially filled dictionary which will contain the json-friendly representation of obj once this method has finished.
restore(data)[source]

Restore an object of the registered type from the json-friendly representation obj and return it.

class sciunit.base.Versioned[source]

Bases: object

A Mixin class for SciUnit objects.

Provides a version string based on the Git repository where the model is tracked. Provided in part by Andrew Davison in issue #53.

__module__ = 'sciunit.base'
__weakref__

list of weak references to the object (if defined)

get_remote(remote_name: str = 'origin', **kwargs) → git.remote.Remote[source]

Get a git remote object for this instance.

Args:
remote_name (str, optional): The remote Git repo. Defaults to ‘origin’.
Returns:
Remote: The git remote object for this instance.
get_remote_url(remote: str = 'origin', cached: bool = True) → str[source]

Get a git remote URL for this instance.

Args:
remote (str, optional): The remote Git repo. Defaults to ‘origin’. cached (bool, optional): Whether to use cached data. Defaults to True.
Raises:
ex: A Git command error.
Returns:
str: The git remote URL for this instance.
get_repo(cached: bool = True) → git.repo.base.Repo[source]

Get a git repository object for this instance.

Args:
cached (bool, optional): Whether to use cached data. Defaults to True.
Returns:
Repo: The git repo for this instance.
get_version(cached: bool = True) → str[source]

Get a git version (i.e. a git commit hash) for this instance.

Args:
cached (bool, optional): Whether to use the cached data. Defaults to True.
Returns:
str: The git version for this instance.
remote_url

Get a git remote URL for this instance.

Args:
remote (str, optional): The remote Git repo. Defaults to ‘origin’. cached (bool, optional): Whether to use cached data. Defaults to True.
Raises:
ex: A Git command error.
Returns:
str: The git remote URL for this instance.
version

Get a git version (i.e. a git commit hash) for this instance.

Args:
cached (bool, optional): Whether to use the cached data. Defaults to True.
Returns:
str: The git version for this instance.
sciunit.base.deep_exclude(state: dict, exclude: list) → dict[source]

[summary]

Args:
state (dict): A dict that represents the state of an instance. exclude (list): Attributes that will be marked as ‘removed’
Returns:
dict: [description]
sciunit.base.log(*args, **kwargs)[source]
sciunit.base.strip_html(html)[source]

sciunit.capabilities module

The base class for SciUnit capabilities.

By inheriting a capability class, a model tells the test that it implements that capability and that all of its methods are safe to call. The capability must then be implemented by the modeler (i.e. all of the capabilty’s methods must implemented in the model class).

class sciunit.capabilities.Capability[source]

Bases: sciunit.base.SciUnit

Abstract base class for sciunit capabilities.

class __metaclass__[source]

Bases: type

__module__ = 'sciunit.capabilities'
name
__module__ = 'sciunit.capabilities'
__str__() → str[source]

Return str(self).

classmethod check(model: sciunit.Model, require_extra: bool = False) → bool[source]

Check whether the provided model has this capability.

By default, uses isinstance. If require_extra, also requires that an instance check be present in model.extra_capability_checks.

Args:

model (Model): A sciunit model instance require_extra (bool, optional): Requiring that an instance check be present in

model.extra_capability_checks. Defaults to False.
Returns:
bool: Whether the provided model has this capability.
classmethod source_check(model: sciunit.Model) → bool[source]
unimplemented(message: str = '') → None[source]

Raise a CapabilityNotImplementedError with details.

Args:
message (str, optional): Message for not implemented exception. Defaults to ‘’.
Raises:
CapabilityNotImplementedError: Raise a CapabilityNotImplementedError with details.
class sciunit.capabilities.ProducesNumber[source]

Bases: sciunit.capabilities.Capability

An example capability for producing some generic number.

__module__ = 'sciunit.capabilities'
produce_number() → None[source]

Produce a number.

class sciunit.capabilities.Runnable[source]

Bases: sciunit.capabilities.Capability

Capability for models that can be run, i.e. simulated.

__module__ = 'sciunit.capabilities'
run(**run_params) → None[source]

Run, i.e. simulate the model.

set_default_run_params(**default_run_params) → None[source]

Set default parameters for all runs.

Note these are parameters of the simulation itself, not the model.

set_run_params(**run_params) → None[source]

Set parameters for the next run.

Note these are parameters of the simulation itself, not the model.

sciunit.converters module

Classes for converting from the output of a model/data comparison to the value required for particular score type.

class sciunit.converters.AtLeastToBoolean(cutoff: int)[source]

Bases: sciunit.converters.Converter

Converts a score to Pass if its value is at least $cutoff, otherwise False.

__init__(cutoff: int)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.converters'
_convert(score: sciunit.scores.base.Score) → sciunit.scores.complete.BooleanScore[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.
class sciunit.converters.AtMostToBoolean(cutoff: int)[source]

Bases: sciunit.converters.Converter

Converts a score to pass if its value is at most $cutoff, otherwise False.

__init__(cutoff: int)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.converters'
_convert(score: sciunit.scores.base.Score) → sciunit.scores.complete.BooleanScore[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.
class sciunit.converters.Converter[source]

Bases: object

Base converter class. Only derived classes should be used in applications.

__module__ = 'sciunit.converters'
__weakref__

list of weak references to the object (if defined)

_convert(score: sciunit.scores.base.Score) → None[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.
convert(score: sciunit.scores.base.Score) → sciunit.scores.base.Score[source]

Convert a type of score to another type of score.

Args:
score (Score): The original score.
Returns:
Score: The converted score.
description
class sciunit.converters.LambdaConversion(f: Callable)[source]

Bases: sciunit.converters.Converter

Converts a score according to a lambda function.

__init__(f: Callable)[source]

f should be a lambda function

Args:
f (Callable): The Lambda function that will be used for the score conversion.
__module__ = 'sciunit.converters'
_convert(score: sciunit.scores.base.Score) → sciunit.scores.base.Score[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.
class sciunit.converters.NoConversion[source]

Bases: sciunit.converters.Converter

Applies no conversion.

__module__ = 'sciunit.converters'
_convert(score: sciunit.scores.base.Score) → sciunit.scores.base.Score[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.
class sciunit.converters.RangeToBoolean(low_cutoff: int, high_cutoff: int)[source]

Bases: sciunit.converters.Converter

Converts a score to Pass if its value is within the range [$low_cutoff,$high_cutoff], otherwise Fail.

__init__(low_cutoff: int, high_cutoff: int)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.converters'
_convert(score: sciunit.scores.base.Score) → sciunit.scores.complete.BooleanScore[source]

Takes the score attribute of a score instance and recasts it as instance of another score type.

Args:
score (Score): An instance of Score.
Raises:
NotImplementedError: Not implemented if not overrided.

sciunit.errors module

Exception classes for SciUnit

exception sciunit.errors.BadParameterValueError(name: str, value: int)[source]

Bases: sciunit.errors.Error

Error raised when a model parameter value is unreasonable.

__init__(name: str, value: int)[source]

Constructor of BadParameterValueError object.

Args:
name (str): Name of the parameter that caused this error. value (int): The value of the parameter.
__module__ = 'sciunit.errors'
exception sciunit.errors.CapabilityError(model: sciunit.models.base.Model, capability: sciunit.capabilities.Capability, details: str = '')[source]

Bases: sciunit.errors.Error

Abstract error class for capabilities

__init__(model: sciunit.models.base.Model, capability: sciunit.capabilities.Capability, details: str = '')[source]

A constructor. Args:

model (Model): A sciunit model instance. capability (Capability): a capability class. details (str, optional): Details of the error information. Defaults to ‘’.
__module__ = 'sciunit.errors'
action = None

The action that has failed (‘provide’ or ‘implement’).

capability = None

The capability class that is not provided.

model = None

The model instance that does not have the capability.

exception sciunit.errors.CapabilityNotImplementedError(model: sciunit.models.base.Model, capability: sciunit.capabilities.Capability, details: str = '')[source]

Bases: sciunit.errors.CapabilityError

Error raised when a required capability is not implemented by a model. Do not use for capabilities that are not provided at all.

__module__ = 'sciunit.errors'
action = 'implement'
exception sciunit.errors.CapabilityNotProvidedError(model: sciunit.models.base.Model, capability: sciunit.capabilities.Capability, details: str = '')[source]

Bases: sciunit.errors.CapabilityError

Error raised when a required capability is not provided by a model. Do not use for capabilities provided but not implemented.

__module__ = 'sciunit.errors'
action = 'provide'
exception sciunit.errors.Error[source]

Bases: Exception

Base class for errors in sciunit’s core.

__module__ = 'sciunit.errors'
__weakref__

list of weak references to the object (if defined)

exception sciunit.errors.InvalidScoreError[source]

Bases: sciunit.errors.Error

Error raised when a score is invalid.

__module__ = 'sciunit.errors'
exception sciunit.errors.ObservationError[source]

Bases: sciunit.errors.Error

Raised when an observation passed to a test is invalid.

__module__ = 'sciunit.errors'
exception sciunit.errors.ParametersError[source]

Bases: sciunit.errors.Error

Raised when params passed to a test are invalid.

__module__ = 'sciunit.errors'
exception sciunit.errors.PredictionError(model: sciunit.models.base.Model, method: str, **args)[source]

Bases: sciunit.errors.Error

Raised when a tests’s generate_prediction chokes on a model’s method.

__init__(model: sciunit.models.base.Model, method: str, **args)[source]

Constructor of PredictionError object.

Args:
model (Model): A sciunit Model. method (str): The method that caused this error.
__module__ = 'sciunit.errors'
argument = None

The argument that could not be handled.

model = None

The model that does not have the capability.

sciunit.suites module

Base class for SciUnit test suites.

class sciunit.suites.TestSuite(tests: List[sciunit.tests.Test], name: str = None, weights=None, include_models: List[sciunit.models.base.Model] = None, skip_models: List[sciunit.models.base.Model] = None, hooks: dict = None, optimizer=None)[source]

Bases: sciunit.base.SciUnit, sciunit.base.TestWeighted

A collection of tests.

__getitem__(item: Union[str, int]) → sciunit.tests.Test[source]
__init__(tests: List[sciunit.tests.Test], name: str = None, weights=None, include_models: List[sciunit.models.base.Model] = None, skip_models: List[sciunit.models.base.Model] = None, hooks: dict = None, optimizer=None)[source]

The constructor of TestSuite class.

Args:
tests (List[Test]): The list of tests. name (str, optional): The name of this test suite. Defaults to None. weights (optional): [description]. Defaults to None. include_models (List[Model], optional): The list of models. Defaults to None. skip_models (List[Model], optional): A list of models that will be skipped. Defaults to None. hooks (dict, optional): [description]. Defaults to None. optimizer (optional): A function to bind to self.optimize (first argument must be a TestSuite). Defaults to None.
__len__() → int[source]
__module__ = 'sciunit.suites'
__str__()[source]

Represent the TestSuite instance as a string.

assert_models(models: Union[sciunit.models.base.Model, List[sciunit.models.base.Model]]) → Union[Tuple[sciunit.models.base.Model], List[sciunit.models.base.Model]][source]

Check and in some cases fixes the list of models.

Args:
models (Union[Model, List[Model]]): The model(s) to be checked and fixed.
Raises:
TypeError: models contains a non-Test. TypeError: models Test suite’s judge method not provided with a model or iterable.”
Returns:
Union[Tuple[Model], List[Model]]: Checked and fixed model(s).
assert_tests(tests: Union[List[sciunit.tests.Test], sciunit.tests.Test]) → Union[List[sciunit.tests.Test], sciunit.tests.Test][source]

Check and in some cases fixes the list of tests.

Args:
tests (Union[List[Test], Test])): The test suite to be checked and fixed.
Raises:
TypeError: tests contains a non-Test. TypeError: tests was not provided with a test or iterable.
Returns:
Union[List[Test], Test]): Checked and fixed test(s).
check(models: Union[sciunit.models.base.Model, List[sciunit.models.base.Model]], skip_incapable: bool = True, require_extra: bool = False, stop_on_error: bool = True) → sciunit.scores.collections.ScoreMatrix[source]

Like judge, but without actually running the test.

Just returns a ScoreMatrix indicating whether each model can take each test or not. A TBDScore indicates that it can, and an NAScore indicates that it cannot.

Args:

models (Union[Model, List[Model]]): A list of sciunit model or a single sciunit model. skip_incapable (bool, optional): Whether to skip incapable models

(or raise an exception). Defaults to True.
require_extra (bool, optional): Check to see whether the model implements certain other methods.
Defaults to False.
stop_on_error (bool, optional): Whether to raise an Exception if an error
is encountered or just produce an ErrorScore. Defaults to True.
Returns:
ScoreMatrix: The ScoreMatrix indicating whether each model can take each test or not.
check_capabilities(model: sciunit.models.base.Model, skip_incapable: bool = False, require_extra: bool = False) → list[source]

Check model capabilities against those required by the suite.

Returns a list of booleans (one for each test in the suite) corresponding to

Args:

model (Model): A sciunit model instance. skip_incapable (bool, optional): Whether to skip incapable models.

(or raise an exception). Defaults to False.

require_extra (bool, optional): Check to see whether the model implements certain other methods. Defaults to False.

Returns:
list: A list of booleans that shows whether the required
capabilities of each test are satisfied by the model.
description = None

The description of the test suite. No default.

classmethod from_observations(tests_info: List[Tuple[Test, dict]], name: Optional[str] = None)[source]

Instantiate a test suite from a set of observations.

tests_info should be a list of tuples containing the test class and the observation, e.g. [(TestClass1,obs1),(TestClass2,obs2),…]. The desired test name may appear as an optional third item in the tuple, e.g. (TestClass1,obse1,”my_test”). The same test class may be used multiple times, e.g. [(TestClass1,obs1a),(TestClass1,obs1b),…].

Args:
tests_info (List[Tuple[“Test”, dict]]): [description] name (Optional[str], optional): The name of this test suite. Defaults to None.
Returns:
TestSuite: An instance of TestSuite that contains the tests based on the observations.
include_models = []

List of names or instances of models to judge (all passed to judge are judged by default).

is_skipped(model: sciunit.models.base.Model) → bool[source]

Indicate whether model will be judged or not.

Args:
model (Model): A sciunit model instance.
Returns:
bool: Whether model will be judged or not.
judge(models: Union[sciunit.models.base.Model, List[sciunit.models.base.Model]], skip_incapable: bool = False, stop_on_error: bool = True, deep_error: bool = False) → sciunit.scores.collections.ScoreMatrix[source]

Judge the provided models against each test in the test suite.

Args:

models (list): The models to be judged. skip_incapable (bool): Whether to skip incapable models

(or raise an exception).
stop_on_error (bool): Whether to raise an Exception if an error
is encountered or just produce an ErrorScore.
deep_error (bool): Whether the error message should penetrate
all the way to the root of the error.
Returns:
ScoreMatrix: The resulting scores for all test/model combos.
judge_one(model: sciunit.models.base.Model, test: sciunit.tests.Test, sm: sciunit.scores.collections.ScoreMatrix, skip_incapable: bool = True, stop_on_error: bool = True, deep_error: bool = False) → Score[source]

Judge model and put score in the ScoreMatrix.

Returns:
Score: The generated score.
name = None

The name of the test suite. Defaults to the class name.

optimize(model: sciunit.models.base.Model, *args, **kwargs) → None[source]

Optimize model parameters to get the best Test Suite scores.

Args:
model (Model): A sciunit model instance.
Raises:
NotImplementedError: Exception raised if this method is not implemented (not overrided in the subclass).
set_hooks(test: sciunit.tests.Test, score: Score) → None[source]

Set hook functions to run after each test is executed.

Args:
test (Test): A sciunit Test instance. score (Score): A sciunit Model instance.
set_verbose(verbose: bool) → None[source]

Set the verbosity for logged information about test execution.

Args:
verbose (bool): The verbosity to be set for each test.
skip_models = []

List of names or instances of models to not judge (all passed to judge are judged by default).

tests = None

The sequence of tests that this suite contains.

sciunit.tests module

SciUnit tests live in this module.

class sciunit.tests.ProtocolToFeaturesTest(observation: Union[List[int], Tuple[int, int]], name: Optional[str] = None, **params)[source]

Bases: sciunit.tests.Test

Assume that generating a prediction consists of: 1) Setting up a simulation experiment protocol. Depending on the backend, this could include editing simulation parameters in memory or editing a model file. It could include any kind of experimental protocol, such as a perturbation. 2) Running a model (using e.g. RunnableModel). 3) Extract features from the results.

Developers should not need to manually implement generate_prediction, and instead should focus on the other three methods here.

__module__ = 'sciunit.tests'
extract_features(model: sciunit.models.base.Model, result) → NotImplementedError[source]

[summary]

Args:
model (Model): A sciunit model instance. result ([type]): [description]
Returns:
NotImplementedError: Exception raised if this method is not implemented (overrided in the subclass).
generate_prediction(model: sciunit.models.base.Model) → dict[source]

Generate a prediction by the sciunit model.

Args:
model (Model): A sciunit model instance.
Returns:
dict: The prediction generated by the sciunit model.
get_result(model: sciunit.models.base.Model) → NotImplementedError[source]

Get the result of this test against the model model.

Args:
model (Model): A sciunit model instance.
Returns:
NotImplementedError: Exception raised if this method is not implemented (not overrided in the subclass).
setup_protocol(model: sciunit.models.base.Model) → NotImplementedError[source]

[summary]

Args:
model (Model): A sciunit model instance.
Returns:
NotImplementedError: Exception raised if this method is not implemented (not overrided in the subclass).
class sciunit.tests.RangeTest(observation: Union[Tuple[int, int], List[int]], name: Optional[str] = None)[source]

Bases: sciunit.tests.Test

Test if the model generates a number within a certain range.

__init__(observation: Union[Tuple[int, int], List[int]], name: Optional[str] = None) → None[source]

Args: observation (dict): A dictionary of observed values to parameterize

the test.

name (str, optional): Name of the test instance.

__module__ = 'sciunit.tests'
compute_score(observation: List[int], prediction: float) → sciunit.scores.base.Score[source]

Get the score of the predictions

Args:
observation (List[int]): The observation to be used in computing the score. prediction (float): The prediction to be used in computing the score.
Returns:
Score: Computed score.
generate_prediction(model: sciunit.models.base.Model) → float[source]

Using the model to generate a prediction.

Args:
model (Model): A sciunit model instance.
Returns:
float: The prediction generated.
required_capabilities = (<class 'sciunit.capabilities.ProducesNumber'>,)
score_type

alias of sciunit.scores.complete.BooleanScore

validate_observation(observation: List[int]) → None[source]

Validate the observation.

Args:
observation (List[int]): [description]
class sciunit.tests.Test(observation: Union[List[int], Tuple[int, int]], name: Optional[str] = None, **params)[source]

Bases: sciunit.base.SciUnit

Abstract base class for tests.

__init__(observation: Union[List[int], Tuple[int, int]], name: Optional[str] = None, **params)[source]
Args:
observation (dict): A dictionary of observed values to parameterize
the test.

name (str, optional): Name of the test instance.

__module__ = 'sciunit.tests'
__str__() → str[source]

Return the string representation of the test’s name.

Returns:
str: The string representation of the test’s name.
_bind_score(score: sciunit.scores.base.Score, model: sciunit.models.base.Model, observation: Union[list, dict], prediction: Union[list, dict]) → None[source]

Bind some useful attributes to the score.

Args:
score (Score): The sciunit score. model (Model): A sciunit model instance. observation (Union[list, dict]): The observation data. prediction (Union[list, dict]): The prediction data.
_judge(model: sciunit.models.base.Model, skip_incapable: bool = True, cached_prediction=False) → sciunit.scores.base.Score[source]

Generate a score for the model (internal API use only).

Args:
model (Model): A sciunit model instance. skip_incapable (bool, optional): Skip the incapable tests. Defaults to True. predict: Whether to make a prediction or use a pre-computed one
Returns:
Score: The generated score.
ace() → sciunit.scores.base.Score[source]

Generate the best possible score of the associated score type.

Returns:
Score: The best possible score of the associated score type.
bind_score(score: sciunit.scores.base.Score, model: sciunit.models.base.Model, observation: Union[list, dict], prediction: Union[list, dict]) → None[source]

For the user to bind additional features to the score.

Args:
score (Score): The sciunit score. model (Model): A sciunit model instance. observation (Union[list, dict]): The observation data. prediction (Union[list, dict]): The prediction data.
check(model: sciunit.models.base.Model, skip_incapable: bool = True, stop_on_error: bool = True, require_extra: bool = False) → sciunit.scores.base.Score[source]

Check to see if the test can run this model.

Like judge, but without actually running the test. Just returns a Score indicating whether the model can take the test or not.

Args:
model (Model): A sciunit model instance skip_incapable (bool, optional): Skip the incapable tests. Defaults to True. stop_on_error (bool, optional): Whether to stop on an error.. Defaults to True. require_extra (bool, optional): Check to see whether the model implements certain other methods.. Defaults to False.
Raises:
e: Raise if there is any exception.
Returns:
Score: A TBDScore instance if check is passed, a NAScore instance otherwise.
check_capabilities(model: sciunit.models.base.Model, skip_incapable: bool = False, require_extra: bool = False) → bool[source]

Check that test’s required capabilities are implemented by model.

Args:
model (Model): A sciunit model instance skip_incapable (bool, optional): Skip the incapable tests. Defaults to False. require_extra (bool, optional): Check to see whether the model implements certain other methods.. Defaults to False.
Raises:
Error: Raises an Error if model is not a Model.
Raises a CapabilityError if model does not have a capability.
Returns:
bool: true if the test’s required capabilities are implemented.
check_capability(model: sciunit.models.base.Model, c: Capability, skip_incapable: bool = False, require_extra: bool = False) → bool[source]

Check if model has capability c.

Optionally (default:True) raise a CapabilityError if it does not.

Args:
model (Model): The sciunit model instance to be checked. c (Capability): A sciunit Capability instance. skip_incapable (bool, optional): If true, then skip the raising of the error. Defaults to False. require_extra (bool, optional): Check to see whether the model implements certain other methods.. Defaults to False.
Raises:
CapabilityError: raise a CapabilityError if it does not has the capability.
Returns:
bool: True if model has the capability.
check_prediction(prediction: float) → None[source]

Check the prediction for acceptable values.

No default implementation.

Args:
prediction (float): The predicted value.
check_score_type(score: sciunit.scores.base.Score) → None[source]

Check that the score is the correct type for this test.

Args:
score (Score): A sciunit score instance.
Raises:
InvalidScoreError: Raise an exception if score is not a sciunit Score.
compute_params() → None[source]

Compute new params from existing self.params. Inserts those new params into self.params. Use this when some params depend upon the values of others. Example: self.params[‘c’] = self.params[‘a’] + self.params[‘b’]

compute_score(observation: dict, prediction: dict) → sciunit.scores.base.Score[source]

Generates a score given the observations provided in the constructor and the prediction generated by generate_prediction.

Must generate a score of score_type. No default implementation.

Args:
observation (dict): The observation from the real world. prediction (dict): The prediction generated by a model.
Raises:
NotImplementedError: Exception raised if this method is not implemented (overrided in the subclass).
Returns:
Score: The generated score.
condition_model(model: sciunit.models.base.Model)[source]

Update the model in any way needed before generating the prediction.

This could include updating parameters such as simulation durations that do not define the model but do define experiments performed on the model. No default implementation.

Args:
model (Model): A sciunit model instance.
converter = None

A conversion to be done on the score after it is computed.

default_params = {}

A dictionary containing the parameters to the test.

describe() → str[source]

Describe the test in words.

Returns:
str: The description of the test.
description = None

A description of the test. Defaults to the docstring for the class.

feature_judge(model: sciunit.models.base.Model, skip_incapable: bool = False, stop_on_error: bool = True, deep_error: bool = False) → sciunit.scores.base.Score[source]

For backwards compatibility

generate_prediction(model: sciunit.models.base.Model) → None[source]

Generate a prediction from a model using the required capabilities.

No default implementation.

Args:
model (Model): A sciunit model instance.
Raises:
NotImplementedError: Exception raised if this method is not implemented (overrided in the subclass).
classmethod is_test_class(other_cls: Any) → bool[source]

Return whether other_cls is a subclass of this test class.

Args:
other_cls (RangeTest): The class to be checked.
Returns:
bool: Whether other_cls is a subclass of this test class.
judge(model: sciunit.models.base.Model, skip_incapable: bool = False, stop_on_error: bool = True, deep_error: bool = False, cached_prediction: bool = False) → sciunit.scores.base.Score[source]

Generate a score for the provided model (public method).

Operates as follows: 1. Checks if the model has all the required capabilities. If it does

not, and skip_incapable=False, then a CapabilityError is raised.
  1. Calls validate_observation to validate the observation.
  2. Calls generate_prediction to generate model prediction.
  3. Compute score.
  4. Checks that the score is of score_type, raising an InvalidScoreError.
  5. Equips the score with metadata: a) A reference to the model, in attribute model. b) A reference to the test, in attribute test. c) A reference to the prediction, in attribute prediction. d) A reference to the observation, in attribute observation.
  6. Returns the score.

If stop_on_error is true (default), exceptions propagate upward. If false, an ErrorScore is generated containing the exception.

Args:

model (Model): A sciunit model instance skip_incapable (bool, optional): Skip the incapable tests. Defaults to False. stop_on_error (bool, optional): Whether to stop on an error (exceptions propagate upward).

If false, an ErrorScore is generated containing the exception. Defaults to True.
deep_error (bool, optional): Whether the traceback will contain the actual code
execution error, instead of the content of an ErrorScore. Defaults to False.
Raises:
score.score: Raise ErrorScore if encountered and stop_on_error is true.
Returns:
Score: The generated score for the provided model.
name = None

The name of the test. Defaults to the test class name.

observation = None

The empirical observation that the test is using.

observation_schema = None

A schema that the observation must adhere to (validated by cerberus). Can also be a list of schemas, one of which the observation must match. If it is a list, each schema in the list can optionally be named by putting (name, schema) tuples in that list.

classmethod observation_schema_names() → List[str][source]

Return a list of names of observation schema, if they are set.

Returns:
List[str]: The list of names of observation schema.
observation_validator

alias of sciunit.validators.ObservationValidator

optimize(model: sciunit.models.base.Model) → None[source]

Optimize the parameters of the model to get the best score.

Args:
model (Model): A sciunit model instance to be optimized.
Raises:
NotImplementedError: Raise the exception if this method is not implemented (not overrided in the subclass).
params_schema = None

A schema that the params must adhere to (validated by cerberus). Can also be a list of schemas, one of which the params must match.

params_validator

alias of sciunit.validators.ParametersValidator

required_capabilities = ()

A sequence of capabilities that a model must have in order for the test to be run. Defaults to empty.

score_type

alias of sciunit.scores.complete.BooleanScore

state

Get the frozen (pickled) model state.

Returns:
dict: The frozen (pickled) model state
state_hide = ['last_model']
units = Dimensionless('dimensionless', 1.0 * dimensionless)
validate_observation(observation: dict) → dict[source]

Validate the observation provided to the constructor.

Args:
observation (dict): The observation to be validated.
Raises:
ObservationError: Raises an ObservationError if invalid.
Returns:
dict: The observation that was validated.
validate_params(params: dict) → dict[source]

Validate the params provided to the constructor.

Args:
params (dict): the params provided to the constructor.
Raises:
ParametersError: Raises an ParametersError if invalid.
Returns:
dict: params that is validated.
class sciunit.tests.TestM2M(observation=None, name=None, **params)[source]

Bases: sciunit.tests.Test

Abstract class for handling tests involving multiple models.

Enables comparison of model to model predictions, and also against experimental reference data (optional).

Note: ‘TestM2M’ would typically be used when handling mutliple (>2) models, with/without experimental reference data. For single model tests, you can use the ‘Test’ class.

__init__(observation=None, name=None, **params)[source]

Args: observation (dict): A dictionary of observed values to parameterize

the test.

name (str, optional): Name of the test instance.

__module__ = 'sciunit.tests'
_bind_score(score: sciunit.scores.base.Score, prediction1: dict, prediction2: dict, model1: sciunit.models.base.Model, model2: sciunit.models.base.Model)[source]

Bind some useful attributes to the score.

Args:
score (Score): A sciunit score instance prediction1 (dict): The prediction generated by the first model. prediction2 (dict): The prediction generated by the second model. model1 (Model): The first model. model2 (Model): The second model.
_judge(prediction1, prediction2, model1: sciunit.models.base.Model, model2: sciunit.models.base.Model = None) → sciunit.scores.base.Score[source]

Generate a score to compare the predictions by the models.

Args:
prediction1 (dict): The prediction generated by the first model. prediction2 (dict): The prediction generated by the second model. model1 (Model): The first model. model2 (Model): The second model. Defaults to None.
Raises:
InvalidScoreError: Score type oncorrect.
Returns:
Score: A sciunit score instance.
bind_score(score: sciunit.scores.base.Score, prediction1: dict, prediction2: dict, model1: sciunit.models.base.Model, model2: sciunit.models.base.Model)[source]

For the user to bind additional features to the score.

Args:
score (Score): A sciunit score instance. prediction1 (dict): The prediction generated by the first model. prediction2 (dict): The prediction generated by the second model. model1 (Model): The first model. model2 (Model): The second model.
compute_score(prediction1: dict, prediction2: dict) → sciunit.scores.base.Score[source]

Generate a score given the observations provided in the constructor and/or the prediction(s) generated by generate_prediction.

Must generate a score of score_type.

No default implementation.

Args:
prediction1 (dict): The prediction generated by the first model. prediction2 (dict): The prediction generated by the second model.
Raises:
NotImplementedError: Error raised if this method is not implemented. Exception: Score computing fails.
Returns:
Score: Computed score.
judge(models: List[sciunit.models.base.Model], skip_incapable: bool = False, stop_on_error: bool = True, deep_error: bool = False, only_lower_triangle: bool = False) → ScoreMatrixM2M[source]

Generate a score matrix for the provided model(s). only_lower_triangle: Only compute the lower triangle (not include

the diagonal) of this square ScoreMatrix and copy the other values across. Leave the diagonal blank. If False, compute all.

Operates as follows: 1. Check if models have been specified as a list/tuple/set.

If not, raise exception.
  1. Create a list of predictions. If a test observation is provided, add it to predictions.

  2. Checks if all models have all the required capabilities. If a model does not, then a CapabilityError is raised.

  3. Calls generate_prediction to generate predictions for each model, and these are appeneded to the predictions list.

  4. Generate a 2D list as a placeholder for all the scores.

  5. Calls score_prediction to generate scores for each comparison.

  6. Checks that the score is of score_type, raising an InvalidScoreError.

  7. Equips the score with metadata: a) Reference(s) to the model(s), in attribute model1 (and model2). b) A reference to the test, in attribute test. c) A reference to the predictions, in attributes prediction1 and

    prediction2.

  8. Returns the score as a Pandas DataFrame.

If stop_on_error is true (default), exceptions propagate upward. If false, an ErrorScore is generated containing the exception.

If deep_error is true (not default), the traceback will contain the actual code execution error, instead of the content of an ErrorScore.

Args:
models (List[Model]): A list of sciunit model instances. skip_incapable (bool, optional): Skip the incapable tests. Defaults to False. stop_on_error (bool, optional): Whether to stop on an error.. Defaults to True. deep_error (bool, optional): [description]. Defaults to False. only_lower_triangle (bool, optional): [description]. Defaults to False.
Raises:
TypeError: The model is not a sciunit model. Exception: TestM2M’s judge method resulted in error. CapabilityError: Encounter capability error when checking the capabilities.
Returns:
ScoreMatrixM2M: The created ScoreMatrixM2M instance.
validate_observation(observation: dict) → None[source]

Validate the observation provided to the constructor.

Note: TestM2M does not compulsorily require an observation (i.e. None allowed).

Args:
observation (dict): The observation to be validated.

sciunit.utils module

Utility functions for SciUnit.

class sciunit.utils.MockDevice[source]

Bases: _io.TextIOWrapper

A mock device to temporarily suppress output to stdout Similar to UNIX /dev/null.

__module__ = 'sciunit.utils'
write(s: str) → None[source]

[summary]

Args:
s (str): The string to be written.
class sciunit.utils.NotebookTools(*args, **kwargs)[source]

Bases: object

A class for manipulating and executing Jupyter notebooks.

Attributes:
path (str): Relative path to the parent directory of the notebook. gen_dir_name (str): Name of directory where files generated by do_notebook are stored. gen_file_level (int): Number of levels up from notebook directory where generated files are stored.
__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.utils'
__weakref__

list of weak references to the object (if defined)

_do_notebook(name: str, convert_notebooks: bool = False) → None[source]

Called by do_notebook to actually run the notebook.

Args:
name (str): name of the notebook file. convert_notebooks (bool): True if the notebook need conversion before executing. Defaults to False.
clean_code(name: str, forbidden: List[Any]) → str[source]

Remove lines containing items in ‘forbidden’ from the code. Helpful for executing converted notebooks that still retain IPython magic commands.

Args:
name (str): name of the notebook file forbidden (List[Any]): [description]
Returns:
str: [description]
convert_and_execute_notebook(name: str) → None[source]

Converts a notebook into a python file and then runs it.

Args:
name (str): name of the notebook file.
convert_notebook(name: str) → None[source]

Converts a notebook into a python file.

Args:
name (str): name of the notebook file.
classmethod convert_path(file: Union[str, list]) → Union[str, int][source]

Check to see if an extended path is given and convert appropriately.

Args:
file (Union[str, list]): A path to the file as a string or list.
Returns:
Union[str, int]: An int -1 when file is not a str or list,
otherwise, a string, which is a path to the file.
do_notebook(name: str) → None[source]

Run a notebook file after optionally. converting it to a python file.

Args:
name (str): name of the notebook file.
execute_notebook(name: str) → None[source]

Loads and then runs a notebook file.

Args:
name (str): name of the notebook file.
fix_display() → None[source]

If this is being run on a headless system the Matplotlib backend must be changed to one that doesn’t need a display.

gen_dir_name = 'GeneratedFiles'
gen_file_level = 2
gen_file_path(name: str) → pathlib.Path[source]

Returns full path to generated files.

Checks to see if directory exists where generated files are stored and creates one otherwise.

Args:
name (str): [description]
Returns:
str: [description]
get_path(file: pathlib.Path) → pathlib.Path[source]

Get the full path of the notebook found in the directory specified by self.path.

Args:
file (Path): the path to the notebook file.
Returns:
Path: The fully resolved path to the notebook file.
load_notebook(name: str) → Tuple[nbformat.notebooknode.NotebookNode, Union[str, pathlib.Path]][source]

Loads a notebook file into memory.

Args:
name (str): name of the notebook file.
Returns:
Tuple[nbformat.NotebookNode, Union[str, Path]]: The notebook that was read and the path to the notebook file.
path = ''
read_code(name: str) → str[source]

Reads code from a python file called ‘name’.

Args:
name (str): name of the python file.
Returns:
str: the code in the python file.
run_notebook(nb: nbformat.notebooknode.NotebookNode, file_path: Union[str, pathlib.Path]) → None[source]

Runs a loaded notebook file.

Args:
nb (nbformat.NotebookNode): The notebook that was loaded. f (Union[str, Path]): The path to the notebook file.
Raises:
Exception: The exception that is thrown when running the notebook.
classmethod strip_line_magic(line: str, magics_allowed: List[str]) → str[source]

Handles lines that contain get_ipython.run_line_magic() commands.

Args:
line (str): the line that contain get_ipython.run_line_magic() commands. magics_allowed (List[str]): [description]
Returns:
str: line after being stripped.
classmethod strip_line_magic_v3(line: str) → Tuple[str, str][source]

strip_line_magic() implementation for Python 3.

Args:
line (str): [description]
Returns:
Tuple[str, str]: [description]
write_code(name: str, code: str) → None[source]

Writes code to a python file called ‘name’, erasing the previous contents.

Files are created in a directory specified by gen_dir_name (see function gen_file_path). File name is second argument of path.

Args:
name (str): name of the file. code (str): code to be added into the file.
class sciunit.utils.TmpTestFolder(location: Union[str, pathlib.Path, None] = None)[source]

Bases: object

A class for creating and deleting a folder in “./unit_test/”.

__init__(location: Union[str, pathlib.Path, None] = None) → None[source]

Initialize self. See help(type(self)) for accurate signature.

__module__ = 'sciunit.utils'
__weakref__

list of weak references to the object (if defined)

create() → None[source]
delete() → None[source]
path = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/sciunit/envs/master/lib/python3.7/site-packages/sciunit-0.2.5-py3.7.egg/sciunit/unit_test/delete_after_tests')
sciunit.utils._dummy_init(self, *args, **kwargs)[source]

Prevents __init__ from being called if returning a obj copy.

sciunit.utils._generic_fn(*args, **kwargs)[source]
sciunit.utils._null_new

staticmethod(function) -> method

Convert a function to be a static method.

A static method does not receive an implicit first argument. To declare a static method, use this idiom:

class C:

@staticmethod def f(arg1, arg2, …):

It can be called either on the class (e.g. C.f()) or on an instance (e.g. C().f()). The instance is ignored except for its class.

Static methods in Python are similar to those found in Java or C++. For a more advanced concept, see the classmethod builtin.

sciunit.utils.assert_dimensionless(value: Union[float, quantities.quantity.Quantity]) → float[source]

Tests for dimensionlessness of input. If input is dimensionless but expressed as a Quantity, it returns the bare value. If it not, it raised an error.

Args:
value (Union[float, Quantity]): The value to be checked for dimensionlessness.
Raises:
TypeError: Score value must be dimensionless.
Returns:
float: The bare value of value.
sciunit.utils.class_intern(cls_)

Transforms the provided class into an interned class.

That is, initializing the class multiple times with the same arguments (even if in a different order if using keyword arguments) should always produce the same object, and __init__ should only be called the first time for each unique set of arguments.

This means that mutations will effectively be shared by all “instances” of the class which shared initialization arguments. This might be useful for storing metadata, for example.

>>> class N(object):
...     def __init__(self, n):
...         self.n = n
>>> N = intern(N)
>>> five = N(5)
>>> five2 = N(5)
>>> five is five2
True
>>> five.is_odd = True
>>> five2.is_odd
True

To enforce immutability of particular attributes, see the setonce property modifier.

The use of the term “intern” comes from the practice of string interning used widely in programming languages, including Python. Look it up.

Can be used as a class decorator in Python 2.6+. Otherwise, use like this:

>>> class Test(object): pass
>>> Test = intern(Test)

Note

Subclassing of intern classes with different __init__ arguments is tricky and probably should not be done if you don’t understand precisely how this works.

If you subclass with the same __init__ arguments (preferably the same __init__) it will use the SAME pool. This can be used to automate adding metadata as above, though you should probably just do that with a function.

Note

You can override the hash function used by providing a value for __init__._intern__hash_function. This should take None as the first argument (substituting for self) and then *args and **kwargs (or your particular signature for __init__) and produce a hash or hashable value.

The default implementation is provided by fn_arg_hash_function applied to __init__, or generic_arg_hash_function if that doesn’t work.

sciunit.utils.decorator(d)[source]

Creates a proper decorator.

If the default for the first (function) argument is None, creates a version which be invoked as either @decorator or @decorator(kwargs…).

See examples below.

sciunit.utils.dict_combine(*dict_list) → dict[source]

Return the union of several dictionaries. Uses the values from later dictionaries in the argument list when duplicate keys are encountered. In Python 3 this can simply be {**d1, **d2, …} but Python 2 does not support this dict unpacking syntax.

Returns:
dict: the dict from combining the dicts
sciunit.utils.dict_hash(d)[source]
sciunit.utils.fn_arg_hash_function(fn)[source]

Creates a hash function which will return the same hashable value if passed a set of *args and **kwargs which are equivalent from the perspective of a function call.

That is, the order of keyword arguments, or the fact that an argument without a default was called as a kwarg, will not produce a different hash.

If any arguments provided are not hashable, a TypeError is raised.

*args and **kwargs are supported.

sciunit.utils.fn_available_argcount(callable)[source]

Returns the number of explicit non-keyword arguments that the callable can be called with.

Bound methods are called with an implicit first argument, so this takes that into account.

Excludes *args and **kwargs declarations.

sciunit.utils.fn_has_args(callable)

Returns whether the provided callable’s underlying function takes *args.

sciunit.utils.fn_has_kwargs(callable)

Returns whether the provided callable’s underlying function takes **kwargs.

sciunit.utils.fn_is_generator(callable)

Returns whether the provided callable’s underlying function is a generator.

sciunit.utils.fn_kwargs(callable)[source]

Returns a dict with the kwargs from the provided function.

Example

>>> def x(a, b=0, *args, **kwargs): pass
>>> func_kwargs(x) == { 'b': 0 }
sciunit.utils.fn_uses_future_division(callable)

Returns whether the provided callable’s underlying function uses future division.

sciunit.utils.generic_arg_hash_function(*args, **kwargs)
sciunit.utils.get_fn(callable)[source]

Returns the underlying function that will be called by the () operator.

  • For regular functions, returns callable
  • For bound methods, returns callable.im_func
  • For unbound methods, returns callable.__func__
  • For classes, returns callable.__init__.__func__.
  • For callable objects, returns callable.__call__.im_func.
sciunit.utils.get_fn_or_method(callable)[source]

Returns the underlying function or method that will be called by the () operator.

  • For regular functions and methods, returns callable
  • For classes, returns callable.__init__
  • For callable objects, returns callable.__call__
sciunit.utils.html_log(*args, **kwargs) → None[source]

[summary]

sciunit.utils.import_all_modules(package, skip: list = None, verbose: bool = False, prefix: str = '', depth: int = 0) → None[source]

Recursively imports all subpackages, modules, and submodules of a given package. ‘package’ should be an imported package, not a string. ‘skip’ is a list of modules or subpackages not to import. Args:

package ([type]): [description] skip (list, optional): [description]. Defaults to None. verbose (bool, optional): [description]. Defaults to False. prefix (str, optional): [description]. Defaults to “”. depth (int, optional): [description]. Defaults to 0.
sciunit.utils.import_module_from_path(module_path: pathlib.Path, name=None) → module[source]

Import the python modual by the path to the file (module).

Args:
module_path (str): [description] name (str): [description]. Defaults to None.
Returns:
ModuleType: [description]
class sciunit.utils.intern[source]

Bases: object

__module__ = 'sciunit.utils'
__weakref__

list of weak references to the object (if defined)

static intern(cls_)[source]

Transforms the provided class into an interned class.

That is, initializing the class multiple times with the same arguments (even if in a different order if using keyword arguments) should always produce the same object, and __init__ should only be called the first time for each unique set of arguments.

This means that mutations will effectively be shared by all “instances” of the class which shared initialization arguments. This might be useful for storing metadata, for example.

>>> class N(object):
...     def __init__(self, n):
...         self.n = n
>>> N = intern(N)
>>> five = N(5)
>>> five2 = N(5)
>>> five is five2
True
>>> five.is_odd = True
>>> five2.is_odd
True

To enforce immutability of particular attributes, see the setonce property modifier.

The use of the term “intern” comes from the practice of string interning used widely in programming languages, including Python. Look it up.

Can be used as a class decorator in Python 2.6+. Otherwise, use like this:

>>> class Test(object): pass
>>> Test = intern(Test)

Note

Subclassing of intern classes with different __init__ arguments is tricky and probably should not be done if you don’t understand precisely how this works.

If you subclass with the same __init__ arguments (preferably the same __init__) it will use the SAME pool. This can be used to automate adding metadata as above, though you should probably just do that with a function.

Note

You can override the hash function used by providing a value for __init__._intern__hash_function. This should take None as the first argument (substituting for self) and then *args and **kwargs (or your particular signature for __init__) and produce a hash or hashable value.

The default implementation is provided by fn_arg_hash_function applied to __init__, or generic_arg_hash_function if that doesn’t work.

sciunit.utils.memoize(fn=None)[source]

Caches the result of the provided function.

sciunit.utils.method_cache(by: str = 'value', method: str = 'run') → Callable[source]

A decorator used on any model method which calls the model’s ‘method’ method if that latter method has not been called using the current arguments or simply sets model attributes to match the run results if it has.

Args:
by (str, optional): [description]. Defaults to ‘value’. method (str, optional): the method that being called. Defaults to ‘run’.
Returns:
Callable: [description]
sciunit.utils.method_memoize(fn=None)

Caches the result of the provided function.

sciunit.utils.set_warnings_traceback(tb: bool = True) → None[source]

Set to True to give tracebacks for all warnings, or False to restore default behavior.

Args:
tb (bool, optional): Defaults to True.
sciunit.utils.style()[source]

Style a notebook with the current sciunit CSS file

sciunit.utils.warn_with_traceback(message: str, category: Type[Warning], filename: str, lineno: int, file: TextIO = None, line: str = None) → None[source]

A function to use with warnings.showwarning to show a traceback.

Args:
message (str): A message that will be included in the warning. category (Type[Warning]): A category (subclass) of the warning. filename (str): Name of the file that raises the warning lineno (int): Number of line in the file that causes this warning. file (TextIO, optional): A file object for recording the log. Defaults to None. line (str, optional): A line of source code to be included in the warning message. Defaults to None.

sciunit.validators module

Cerberus validator classes for SciUnit.

class sciunit.validators.ObservationValidator(*args, **kwargs)[source]

Bases: cerberus.validator.Validator

Cerberus validator class for observations.

Attributes:
test (Test): A sciunit test instance to be validated. _error (str, str): The error that happens during the validating process.
__init__(*args, **kwargs)[source]

Constructor of ObservationValidator.

Must pass test as a keyword argument. Cannot be a positional argument without modifications to cerberus.

Raises:
Exception: “Observation validator constructor must have a test keyword argument.”
__module__ = 'sciunit.validators'
_types_from_methods = ()
_validate_iterable(is_iterable: bool, key: str, value: Any) → None[source]

Validate fields with iterable key in schema set to True The rule’s arguments are validated against this schema: {‘type’: ‘boolean’}

_validate_units(has_units: bool, key: str, value: Any) → None[source]

Validate fields with units key in schema set to True. The rule’s arguments are validated against this schema: {‘type’: ‘boolean’}

checkers = ()
coercers = ()
default_setters = ()
class sciunit.validators.ParametersValidator(*args, **kwargs)[source]

Bases: cerberus.validator.Validator

Cerberus validator class for observations.

Attributes:
units_type ([type]): The type of Python quantity’s unit. _error (str, str): value is not a Python quantity instance.
__module__ = 'sciunit.validators'
_types_from_methods = ('current', 'time', 'voltage')
_validate_type_current(value: quantities.quantity.Quantity) → bool[source]

Validate fields requiring units of amps.

Args:
value (pq.quantity.Quantity): A python quantity instance.
Returns:
bool: Whether it is valid.
_validate_type_time(value: quantities.quantity.Quantity) → bool[source]

Validate fields requiring units of seconds.

Args:
value (pq.quantity.Quantity): A python quantity instance.
Returns:
bool: Whether it is valid.
_validate_type_voltage(value: quantities.quantity.Quantity) → bool[source]

Validate fields requiring units of volts.

Args:
value (pq.quantity.Quantity): A python quantity instance.
Returns:
bool: Whether it is valid.
checkers = ()
coercers = ()
default_setters = ()
units_map = {'current': 'A', 'time': 's', 'voltage': 'V'}
validate_quantity(value: quantities.quantity.Quantity) → None[source]

Validate that the value is of the Quantity type.

Args:
value (pq.quantity.Quantity): The Quantity instance to be validated.
validate_units(value: quantities.quantity.Quantity) → bool[source]

Validate units, assuming that it was called by _validate_type_*.

Args:
value (pq.quantity.Quantity): A python quantity instance.
Returns:
bool: Whether it is valid.
sciunit.validators.register_quantity(quantity: quantities.quantity.Quantity, name: str) → None[source]

Register name as a type to validate as an instance of the class of quantity.

Args:
quantity (pq.Quantity): a quantity. name (str): the name to be registered.
sciunit.validators.register_type(cls, name: str) → None[source]

Register name as a type to validate as an instance of class cls.

Args:
cls: a class name (str): the name to be registered.

sciunit.version module

Module contents

SciUnit.

A Testing Framework for Data-Driven Validation of Quantitative Scientific Models