Readme file¶
sattoolbox¶
Description¶
sattoolbox is a python toolbox of useful functions used at the Department of Solar and Systems Engineering (“SAT”) at the University of Kassel. Starting May 2024, it collects code snippets, functions and modules, that the SAT researchers use for processing data, making plots and run certain evaluations. In January 2026 the sattoolbox was made available as a public project.
The sattoolbox is divided into three submodules:
data_processing
plots
If you are starting to make plots with sattoolbox, use the Beginner’s Guide to plotting with sattoolbox.evaluations
Current status: The plots submodule contains a quite powerfull Plotter class. Other submodules are still empty.
Installation¶
Download the .zip archive, unpack and save it whereever you like.
A script that shall use the sattoolbox needs to include the following in the top import section: (change the path to where you put sattoolbox)
import sys sys.path.append('C:/path/to/sattoolbox') # add the path to sattoolbox to pythonpath (keep the last 'sattoolbox'). This is the folder, where theREADME.md of sattoolbox is. Don't get confused, this folder again contains a folder named sattoolbox where the actual python code resides.
After that, the script can import sattoolbox, recommended use:
import sattoolbox as stb
You could also import certain modules (here moduleX) or functions (here functionX):
import sattoolbox.subpackage.moduleX as moduleX # import moduleX from sattoolbox.subpackage.moduleX import functionX # import functionX
Usage¶
The sattoolbox includes many functions for different use cases.
Please refer to the docstrings of the functions (Console: print(path.and.name_of_some_function().__doc__)
As an example, to make plots from a pandas dataframe df, you can use:
plotter = stb.plots.plots.Plotter()
fig, ax = plotter.plot(df)
Modules may also contain a function example, that demonstrates its functionalities, e.g. stb.plots.plots.example()
A documentation, built from the docstrings, is available here: sattoolbox’s documentation
Support¶
For general support, you may ask Johannes.
For support on certain functions or modules, please try to check from the code who has mainly written it and ask this person.
Contributing¶
Any user of sattoolbox is encouraged to contribute via issues, e.g. reporting bugs or proposing new features.
Even better are active contributions to the code. If you want to do that, please have a look at the readme for developers.
License¶
BSD 3-Clause License
Copyright (c) 2026, Open source contributors.
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project status¶
Active, pace of progress depending on resources of contributors.
Badges¶
On some READMEs, you may see small images that convey metadata, such as whether or not all the tests are passing for the project. You can use Shields to add some to your README. Many services also have instructions for adding a badge.
Development of sattoolbox¶
sattoolbox is developed by scientist at SAT - people with different background and most likely not computer scientist or experienced programmers. Nevertheless contributions by everyone are encouraged and highly welcome!
This README shall provide a rough guideline for contributing to the code of sattoolbox, so that we work productively together.
Whenever you see room for improvement of this guide - do it!
Set up¶
Clone the git repository to your machine. You may use sourcetree to manage your commits and other git commands.
If you are using an IDE that supports projects (such as spyder), you may create a corresponding project into the folder of the sattoolbox repository (not its sattoolbox subfolder with the python package).
During coding¶
1) Where to put your new code (branches)¶
For each new feature, please create a new branch from develop, e.g. “dev_new_feature”. Minor changes may be done on the develop branch directly.
2) Docstrings¶
Write docstrings for every module, class and method. Please follow the numpy style. The docstrings will be used to create the documentation of sattoolbox.
4) Adding new modules¶
If you introduce a new module (e.g. moduleX.py) or a new subpackage (i.e. a new subfolder subpackageX, that itself contains some modules and a file __init__.py), that contains functions, that should be used by users of sattoolbox, you need to add an import statement into the __init__.py in the folder, where your new module or subpackage is placed:
from . import moduleX # or subpackageX
5) Importing other sattoolbox modules¶
If you add imports of other modules from sattoolbox to a module of sattoolbox, please do it as an absolute import, using the full path to the place, where this module resides, starting from sattoolbox e.g.:
# Import of other modules from sattoolbox
from sattoolbox.path.to import moduleX
Note: Scripts within sattoolbox (= .py-files that actually run code and typically use classes and/or functions from other sattoolbox modules) must be placed in the topmost package ‘sattoolbox’ to make these imports work without errors. Usually, this script will be an example, please refer to paragraph “7) Provide Examples” in this readme for further information on examples.
6) Test your code (unittest)¶
Unittests should be written for all public classes / methods - but not for private methods (see discussion).
Writing and using unittests has multiple advantages:
Creating good unittests often also improves the quality of the tested classes / methods (e.g. find errors directly or get new ideas how to improve the code)
Detection of errors directly after they are introduced (and not after some time when a user actually encounters and reports it)
The tests documents the expected behavior of classes / methods
The unittests should test all features with various different inputs, assuring proper results or errors. For an example see plots_unittests.py.
To set up unittests, please follow these steps:
To test moduleX.py, place a file test_moduleX.py in the same subpackage (=folder) as the module itself.
In this test_moduleX.py write your test, following this structure (mind the comment regarding
xmlrunner!):
import unittest
import xmlrunner #should be imported from 'unittest-xml-reporting' and not from 'xmlrunner', otherwise error when writing the xml file
# other imports if needed
from sattoolbox.path.to.moduleX import moduleX
class TestClassFromModuleX(unittest.TestCase):
def setUp(self):
# do stuff, that should be done before each test
def test_method1(self):
# Write test cases for method1, this means do something, and assert that the results are as expected
values = moduleX.method1(some, parameters)
self.assertEqual(values, [1,2]) # if you expect a list with values [1,2]
if __name__ == '__main__':
with open('unittests_reports/unittests_report_moduleX.xml','wb') as output:
unittest.main(
argv=[''], exit=False,
verbosity=2,
testRunner=xmlrunner.XMLTestRunner(output=output),
failfast=False, buffer=False, catchbreak=False)
To run these tests on your computer, use this command in the terminal (unfortunately, it does not work properly in interactive consoles):
python -m sattoolbox.path.to.test_moduleXWhen you have written all tests and they don’t fail, add a call to your test file to the automatic tests (CI/CD pipeline) .gitlab-ci.yml:
in “unit-test-job” under “script” add:
- python3 -m xmlrunner sattoolbox/path/to/moduleX/test_moduleX.py –output-file unittests_reports/unittests_report_moduleX.xml
7) Provide examples¶
Demonstrate your code with some useful examples. To do so, include an example() function in your module like below.
def example():
"""
Run examples of the functions defined in this module.
To run this example, 'import sattoolbox as stb' and call 'stb.path.to.moduleX.example()'
Returns
-------
None.
"""
# demonstration of the functions of the module
Users of sattoolbox can now run this example via:
stb.path.to.moduleX.example()
Furthermore you need to add a call of your example to ‘script_examples.py’ (or ‘script_examples_special_tools.py’, if it is an example within the special_tools section), e.g.:
from sattoolbox.path.to import moduleX
moduleX.example()
This ensures that your example will be run during the code testing routines (CI/CD Pipeline). Furthermore, the script_examples files are a helpful collection of all examples across sattoolbox.
If your example contains requests to internet resources, they must be allowed by the IT Service so that the code testing routine works properly. Therefore, add the domain your code needs to access into the “external_domains.txt” (in sattoolbox top folder) and inform the ITS that requests to this domain must be allowed. (https://www.uni-kassel.de/its/dienstleistungen/speicher-und-backup/kontakt, Betreff “GitLab”)
8) Commit your new code¶
Please commit your changes regularly, so that there are rather small commits with a clear description. This helps to follow what happened from the history.
Good example:
Commit 1: “Added feature xy to method yz”
Commit 2: “Added docstring to method yz”
Commit 3: “Fixed error due to something in xy”
Bad example:
Commit: “Whatever I coded in July”
9) Push your work¶
Push your commits at least at the end of the day, so that they will be available for everyone in the public repository as soon as possible.
10) Create merge requests¶
When your new feature is ready, create a merge request from your dev_some_feature branch into develop. Have a look at the test results from the CI/CD pipeline, which will be triggered by your merge request. Please let someone else review your changes before merging.
Once several features are ready, a merge into main will be done.
Additional information¶
Design of classes and methods¶
This is a difficult topic. As we try to develop and use sattoolbox together, it is necessary to write code that others can understand. Here are some hints:
Keep the Zen of Python in mind (Link to illustration)
Take your time to think about the structure of classes and methods (e.g. check-out this discussion on class design in python).
Avoid repetion of code: If you are typing (almost) the same things in multiple places, you should instead use inheritance or write a method or function for this purpose.
Break down methods and functions into small bits. A single method/function should do a specific thing, that can be understood from its title. This means methods and functions should not look like scripts.
Check pylint results, try to understand those and follow the recommendations.
CI/CD pipeline¶
The project sattoolbox on gitlab includes a so called “CI/CD pipeline”. This is a collection of actions, that run once a merge request is opened. The Pipeline can also be triggered manually (Build => Pipelines => “Run Pipeline”). The pipeline is defined in a CI/CD configuration file. The pipeline consists of several jobs that:
run unitests (=> please include your new unittest files)
test scripts (=> please add new scripts and classes with an example() )
run pylint (=> please add your files to be linted)
build the documentation from docstrings (=> Reminder: write proper docstrings!)
pylint¶
pylint is a powerful tool that tests code for conventions and also indicates bad code structure and more. If you want to improve your code style, add a call your moduleX to the lint-test-job in the .gitlab-ci.yml (=> pylint path/to/moduleX.py). The output of pylint is a score. The test in the CI/CD pipeline passes, if it is at least 9 out of 10. Furthermore, pylint provides a message for every error it finds, so that you can improve on this (list of messages). Don’t take pylint as the only truth, it may complain about intended things. It can be configured via the a configuration file. You can disable certain message categories in the configurations, but please be careful with this option, it effects all future test runs for the whole project. It might be a better idea to disable a message for a specific line using ‘# pylint: disable=warning-name’.
3) Comments¶
Please add comments to your code wherever it is not absolutely obvious, what it is doing. That means, please structure your code with some headings that describe what step is taken and in addition comment on what happens in a specific line.