From 23d028a8be5ff74df8859e3388be7499ea6b628e Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Fri, 10 May 2024 14:16:02 +0200 Subject: [PATCH 1/7] update info about pre-release and its installation --- docs/index.md | 4 ++-- docs/install.md | 3 ++- 2 files changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/index.md b/docs/index.md index 07bf18e8..a3ee931e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,5 +7,5 @@ For a deep understanding of NPLinker, please refer to the [original paper](https !!! warning "Under Development" - NPLinker v2 is under active development. The documentation is not complete yet. If you have any - questions, please contact us via [GitHub Issues](https://github.com/NPLinker/nplinker/issues) \ No newline at end of file + NPLinker v2 is under active development ([See its pre-releases](https://pypi.org/project/nplinker/#history)). + The documentation is not complete yet. If you have any questions, please contact us via [GitHub Issues](https://github.com/NPLinker/nplinker/issues). \ No newline at end of file diff --git a/docs/install.md b/docs/install.md index 7ddff8ae..0951cbd8 100644 --- a/docs/install.md +++ b/docs/install.md @@ -18,13 +18,14 @@ python -m venv env # (1)! source env/bin/activate # install nplinker package -pip install nplinker +pip install nplinker==2.0.0a1 # (2)! # install nplinker non-pypi dependencies and databases install-nplinker-deps ``` 1. A virtual environment is ***required*** to install the the non-pypi dependencies. You can also use `conda` to create a new environment. But NPLinker is not available on conda yet. +2. NPLinker v2 is still under development and released as [pre-releases](https://pypi.org/project/nplinker/#history). To install the pre-release, you have to explicitly specifiy the version. Using `pip install nplinker` will install the legacy NPLinker (v1.3.2), which is not recommended. ## Install from source code From 3ea97cad388c69eee3a651fe5b332cb0559e9ada Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Fri, 10 May 2024 14:35:25 +0200 Subject: [PATCH 2/7] add disk space requirement for installation --- docs/install.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/install.md b/docs/install.md index 0951cbd8..85e80831 100644 --- a/docs/install.md +++ b/docs/install.md @@ -5,7 +5,9 @@ - Python version ≥3.9 -NPLinker is a python package that has both pypi packages and non-pypi packages as dependencies. +NPLinker is a python package that has both pypi packages and non-pypi packages as dependencies. It +requires **~4.5GB** of disk space to install all the dependencies. + Install `nplinker` package as following: @@ -17,10 +19,10 @@ python --version python -m venv env # (1)! source env/bin/activate -# install nplinker package +# install nplinker package (requiring ~300MB of disk space) pip install nplinker==2.0.0a1 # (2)! -# install nplinker non-pypi dependencies and databases +# install nplinker non-pypi dependencies and databases (~4GB) install-nplinker-deps ``` From 019246cc15423073e9b5dab8e3c5e7c3411e884d Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Fri, 10 May 2024 15:10:15 +0200 Subject: [PATCH 3/7] add doc about logging --- docs/logging.md | 50 +++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 51 insertions(+) create mode 100644 docs/logging.md diff --git a/docs/logging.md b/docs/logging.md new file mode 100644 index 00000000..45879080 --- /dev/null +++ b/docs/logging.md @@ -0,0 +1,50 @@ +NPLinker uses the standard library [logging](https://docs.python.org/3/library/logging.html#module-logging) +module for managing log messages and the python library [rich](https://rich.readthedocs.io/en/latest/logging.html) +to colorize the log messages. Depending on how you use NPLinker, you can set up logging in different ways. + +## NPLinker as an application +If you're using NPLinker as an application, you're running the whole workflow of NPLinker as +described in the [Quickstart](./quickstart.md). In this case, you can set up logging in the nplinker +configuration file `nplinker.toml`. + +## NPLinker as a library +If you're using NPLinker as a library, you're using only some functions and classes of NPLinker in +your script. By default, NPLinker will not log any messages. However, you can set up logging in your +script to log messages. + +```python title="Set up logging in 'your_script.py'" +# Set up logging configuration first +from nplinker import setup_logging + +setup_logging(level="DEBUG", file="nplinker.log", use_console=True) # (1)! + +# Your busniess code here +# e.g. download and extract nplinker example data +from nplinker.utils import download_and_extract_archive + +download_and_extract_archive( + url="https://zenodo.org/records/10822604/files/nplinker_local_mode_example.zip", + download_root=".", +) +``` + +1. The `setup_logging` function sets up the logging configuration. The `level` argument sets the + logging level. The `file` argument sets the log file. The `use_console` argument sets whether to + log messages to the console. + + +The log messages will be written to the log file `nplinker.log` and displayed in the console with a +format like this: `[Date Time] Level Log-message Module:Line`. + +```shell title="Run your script in a terminal" +# Run your script +$ python your_script.py +Downloading nplinker_local_mode_example.zip ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100.0% • 195.3/195.3 MB • 2.6 MB/s • 0:00:00 • 0:01:02 # (1)! +[2024-05-10 15:14:48] INFO Extracting nplinker_local_mode_example.zip to . utils.py:401 + +# Check the log file +$ cat nplinker.log +[2024-05-10 15:14:48] INFO Extracting nplinker_local_mode_example.zip to . utils.py:401 +``` + +1. This is a progress bar but not a log message. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index feecc0f0..e4759f66 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,7 @@ nav: - Welcome to NPLinker: index.md - Installation: install.md - Quickstart: quickstart.md + - Logging: logging.md # - Configuration: config.md # - NPLinker Architecture: architecture.md # - Arranger pipeline: arranger.md From f856176c9ead02d0eaad6d91beb28a36cc8fb64f Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Fri, 10 May 2024 15:57:41 +0200 Subject: [PATCH 4/7] Update README.md - update installation guideline - add guideline for testing --- README.md | 53 +++++++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 04dc9a6f..3184a398 100644 --- a/README.md +++ b/README.md @@ -31,22 +31,63 @@ Original paper: [Ranking microbial metabolomic and genomic links in the NPLinker ### Installation -NPLinker is a Python package, you can install it as following: +NPLinker is a python package, using both pypi packages and non-pypi packages as dependencies. It +requires **~4.5GB** of disk space to install all the dependencies. + ```shell -# create a new virtual environment +# Check python version (requiring ≥3.9) +python --version + +# Create a new virtual environment python -m venv env source env/bin/activate -# install nplinker package -pip install nplinker +# install from nplinker releases (requiring ~300MB of disk space) +pip install nplinker==2.0.0a1 + +# or install the latest from source code +pip install git+https://github.com/nplinker/nplinker@dev -# install nplinker non-pypi dependencies and databases +# install nplinker non-pypi dependencies and databases (~4GB) install-nplinker-deps ``` - A virtual environment is *required* to install the the non-pypi dependencies. You can also use `conda` to manage python environments. +### Testing + +To run the tests, you need to clone this repo and install the development dependencies: + +```shell +# Create a new virtual environment +python -m venv env +source env/bin/activate + +# Clone the repository and install the development dependencies +git clone https://github.com/NPLinker/nplinker.git +cd nplinker +pip install -e ".[dev]" +install-nplinker-deps +``` + +#### Unit tests + +To run the unit tests, you can use the following command: + +```shell +pytest +``` +Pytest will use all available CPU cores to run the unit tests in parallel. + +#### Integration tests + +To run the integration tests, you can use the following command: + +```shell +pytest -n1 tests/integration +``` +The `-n1` is to use one CPU core to run the tests. Change it to `-n2` if you want to use two CPU cores to run in parallel. + ### Usage See the [documentation](https://nplinker.github.io/nplinker) for more information about how to use NPLinker. From 853d7b78f91b20982ccbda7558c3855de7019e0e Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Tue, 21 May 2024 10:27:02 +0200 Subject: [PATCH 5/7] Update docs/index.md Co-authored-by: Giulia Crocioni <55382553+gcroci2@users.noreply.github.com> --- docs/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/index.md b/docs/index.md index a3ee931e..f443c12c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -7,5 +7,5 @@ For a deep understanding of NPLinker, please refer to the [original paper](https !!! warning "Under Development" - NPLinker v2 is under active development ([See its pre-releases](https://pypi.org/project/nplinker/#history)). + NPLinker v2 is under active development ([see its pre-releases](https://pypi.org/project/nplinker/#history)). The documentation is not complete yet. If you have any questions, please contact us via [GitHub Issues](https://github.com/NPLinker/nplinker/issues). \ No newline at end of file From c55ae06fd301e6eeabe71e7f50ffb60a815369d9 Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Tue, 21 May 2024 10:27:27 +0200 Subject: [PATCH 6/7] Update docs/install.md Co-authored-by: Giulia Crocioni <55382553+gcroci2@users.noreply.github.com> --- docs/install.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/install.md b/docs/install.md index 85e80831..37e7960c 100644 --- a/docs/install.md +++ b/docs/install.md @@ -27,7 +27,7 @@ install-nplinker-deps ``` 1. A virtual environment is ***required*** to install the the non-pypi dependencies. You can also use `conda` to create a new environment. But NPLinker is not available on conda yet. -2. NPLinker v2 is still under development and released as [pre-releases](https://pypi.org/project/nplinker/#history). To install the pre-release, you have to explicitly specifiy the version. Using `pip install nplinker` will install the legacy NPLinker (v1.3.2), which is not recommended. +2. NPLinker v2 is still under development and released as [pre-release](https://pypi.org/project/nplinker/#history). To install the pre-release, you have to explicitly specifiy the version. The command `pip install nplinker` will install the legacy NPLinker (v1.3.2), which is not recommended. ## Install from source code From f831f61dcd1ce99bb4273e6f4af01097d42598c7 Mon Sep 17 00:00:00 2001 From: Cunliang Geng Date: Tue, 21 May 2024 10:27:38 +0200 Subject: [PATCH 7/7] Update docs/logging.md Co-authored-by: Giulia Crocioni <55382553+gcroci2@users.noreply.github.com> --- docs/logging.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/logging.md b/docs/logging.md index 45879080..2e3af133 100644 --- a/docs/logging.md +++ b/docs/logging.md @@ -18,7 +18,7 @@ from nplinker import setup_logging setup_logging(level="DEBUG", file="nplinker.log", use_console=True) # (1)! -# Your busniess code here +# Your business code here # e.g. download and extract nplinker example data from nplinker.utils import download_and_extract_archive