From e7cd8813aeb280a476a9730eb1ce6d2cd1bab193 Mon Sep 17 00:00:00 2001 From: Carsten Hinz <c.hinz@fz-juelich.de> Date: Wed, 26 Jun 2024 14:11:49 +0200 Subject: [PATCH] updated README.md to use python buildin removed poetry from README.md --- README.md | 46 ++++++++++++++++++++++++++++------------------ 1 file changed, 28 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 25ba0b6..15f12d0 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,7 @@ The documentation and this README are work in progress. # Requirements +This project requires python 3.11 or higher. TBD, see pyproject.toml @@ -23,7 +24,7 @@ TBD, see pyproject.toml Move to the folder you want to download this project to. We now need to download the source code from the [repository](https://gitlab.jsc.fz-juelich.de/esde/toar-public/toargridding/-/tree/dev?ref_type=heads) either as ZIP file or via git: -## Download with GIT +## 1) Download with GIT Clone the project from its git repository: ```bash git clone https://gitlab.jsc.fz-juelich.de/esde/toar-public/toargridding.git @@ -34,24 +35,33 @@ cd toargridding git checkout testing ``` -## Installing Dependencies and Setting up Virtual Environment +## 2) Installing Dependencies and Setting up Virtual Environment -The handling of required packages is done with [poetry](https://python-poetry.org/). -After installing poetry, you can simply install all required dependencies for this project by running poetry in the project directory: +Setup a virtual environment for your code to avoid conflicts with other projects. Here, you can use your preferred tool or run: ```bash -poetry install +python -m venv .venv +source .venv/bin/activate ``` -This also creates a virtual environment, which ensures that the dependencies of different projects do not interfere. -To run a jupyter notebook in the virtual environment execute +The latter line activates the virtual environment for the further usage. To deactivate your environment call +```bash +deactivate +``` +For the installation of all required dependencies call +```bash +pip install -e . +``` + + +To run scripts or notebooks use: ```bash #for selecting a notebook over the file browser in your webbrowser: -poetry run jupyter notebook +jupyter notebook #or for directly opening a notebook: -poetry run jupyter notebook [/path/to/notebookname.ipynb] +jupyter notebook [/path/to/notebookname.ipynb] ``` and to run a script use ```bash -poetry run python [/path/to/scriptname.py] +python [/path/to/scriptname.py] ``` # How does this tool work? @@ -94,13 +104,13 @@ For VS Code, please ensure to select the kernel of the virtual environment [see] Running the provided examples with the python environment created by poetry can be done by ```bash -poetry run jupyter notebook + jupyter notebook ``` as pointed out previously. ## High level function ```bash -poetry run jupyter notebook example/produce_data_manyStations.ipynb + jupyter notebook example/produce_data_manyStations.ipynb #(please see next notebook for a faster example) ``` This notebook provides an example on how to download data, apply gridding and save the results as [netCDF files](https://docs.xarray.dev/en/stable/user-guide/io.html). @@ -114,7 +124,7 @@ The subsequent requests function as a progress report and allow working with the As the gridding is done offline, it will be executed for already downloaded files, whenever the notebook is rerun. Please note, that the file name for the gridded data also contains the date of creation. ```bash -poetry run jupyter notebook example/produce_data_withOptional.ipynb + jupyter notebook example/produce_data_withOptional.ipynb ``` This example is based on the previous one but uses additional arguments to reduce the number of stations per request. As an example, different classifications of the stations are used: first the "toar1_category" and second the "type_of_area". Details can be found in [documentation of the FastAPI REST interface](https://toar-data.fz-juelich.de/api/v2/#stationmeta) or the [user guide](https://toar-data.fz-juelich.de/sphinx/TOAR_UG_Vol03_Database/build/latex/toardatabase--userguide.pdf). @@ -123,7 +133,7 @@ The selection of only a limited number of stations leads to significant faster r ## Retrieving data ```bash -poetry run jupyter notebook example/get_sample_data_manual.ipynb + jupyter notebook example/get_sample_data_manual.ipynb ``` Downloads data from the TOAR database with a manual creation of the request to the TOAR database. The extracted data are written to disc. No further processing or gridding is done. @@ -131,13 +141,13 @@ The result is a ZIP-file containing two CSV files. The first one contains the st ## Retrieving data ```bash -poetry run jupyter notebook example/get_sample_data.ipynb + jupyter notebook example/get_sample_data.ipynb ``` As a comparison to the previous example, this one performs the same request by using the interface of this project. ## Retrieving data and visualization ```bash -poetry run jupyter notebook example/quality_controll.ipynb + jupyter notebook example/quality_controll.ipynb ``` Notebook for downloading and visualization of data. The data are downloaded and reused for subsequent executions of this notebook. @@ -148,7 +158,7 @@ The gridding is done on the downloaded data. Gridded data are not saved to disc. ## Duration of Different Requests ```bash -poetry run jupyter notebook tests/benchmark.py + jupyter notebook tests/benchmark.py ``` This script requests datasets with different durations (days to month) from the TOAR Database and saves them to disc. It reports the duration for the different requests. @@ -174,7 +184,7 @@ At the moment time differences larger than one day are working, i.e. start and e This package comes with all required information. There is a first function to fetch an update of the available variables from the TAOR-DB. This will override the original file: ```bash -poetry run python toargridding/setupFunctions.py + python toargridding/setupFunctions.py ``` # Documentation of Source Code: -- GitLab