From 1da644f63e2c4e42d8c7e8bab2eabb9a51163ace Mon Sep 17 00:00:00 2001 From: Michal Stolarczyk Date: Thu, 24 Jun 2021 10:00:09 -0400 Subject: [PATCH] add status docs to readmes --- README.md | 42 ++++- docs/README.md | 42 ++++- docs_jupyter/cli.md | 311 ---------------------------------- docs_jupyter/python_api.ipynb | 136 +++++++-------- 4 files changed, 148 insertions(+), 383 deletions(-) delete mode 100644 docs_jupyter/cli.md diff --git a/README.md b/README.md index cec9c068..4f8c41f7 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,9 @@ export PIPESTAT_RESULTS_FILE=results_file.yaml export PIPESTAT_NAMESPACE=my_namespace ``` -## Report a result +## Pipeline results reporting and retrieval + +### Report a result From command line: @@ -47,7 +49,7 @@ psm = pipestat.PipestatManager() psm.report(values={"result_name": 1.1}) ``` -## Retrieve a result +### Retrieve a result From command line: @@ -63,3 +65,39 @@ import pipestat psm = pipestat.PipestatManager() psm.retrieve(result_identifier="result_name") ``` + +## Pipeline status management + +## Set status + +From command line: + +```console +pipestat status set running +``` + +From Python: + +```python +import pipestat + +psm = pipestat.PipestatManager() +psm.set_status(status_identifier="running") +``` + +## Get status + +From command line: + +```console +pipestat status get +``` + +From Python: + +```python +import pipestat + +psm = pipestat.PipestatManager() +psm.get_status() +``` diff --git a/docs/README.md b/docs/README.md index cec9c068..4f8c41f7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -30,7 +30,9 @@ export PIPESTAT_RESULTS_FILE=results_file.yaml export PIPESTAT_NAMESPACE=my_namespace ``` -## Report a result +## Pipeline results reporting and retrieval + +### Report a result From command line: @@ -47,7 +49,7 @@ psm = pipestat.PipestatManager() psm.report(values={"result_name": 1.1}) ``` -## Retrieve a result +### Retrieve a result From command line: @@ -63,3 +65,39 @@ import pipestat psm = pipestat.PipestatManager() psm.retrieve(result_identifier="result_name") ``` + +## Pipeline status management + +## Set status + +From command line: + +```console +pipestat status set running +``` + +From Python: + +```python +import pipestat + +psm = pipestat.PipestatManager() +psm.set_status(status_identifier="running") +``` + +## Get status + +From command line: + +```console +pipestat status get +``` + +From Python: + +```python +import pipestat + +psm = pipestat.PipestatManager() +psm.get_status() +``` diff --git a/docs_jupyter/cli.md b/docs_jupyter/cli.md deleted file mode 100644 index 3e7b064e..00000000 --- a/docs_jupyter/cli.md +++ /dev/null @@ -1,311 +0,0 @@ -# Pipestat CLI - -Before following this tutorial please make sure you're familiar with "Pipestat Python API" tutorial. - -## Usage reference - -To learn about the usage `pipestat` usage use `--help`/`-h` option on any level: - - -```bash -pipestat -h -``` - - version: 0.0.1 - usage: pipestat [-h] [--version] [--silent] [--verbosity V] [--logdev] - {report,inspect,remove,retrieve} ... - - pipestat - report pipeline results - - positional arguments: - {report,inspect,remove,retrieve} - report Report a result. - inspect Inspect a database. - remove Remove a result. - retrieve Retrieve a result. - - optional arguments: - -h, --help show this help message and exit - --version show program's version number and exit - --silent Silence logging. Overrides verbosity. - --verbosity V Set logging level (1-5 or logging module level name) - --logdev Expand content of logging message format. - - pipestat standardizes reporting of pipeline results. It formalizes a way for - pipeline developers and downstream tools developers to communicate -- results - produced by a pipeline can easily and reliably become an input for downstream - analyses. The ovject exposes API for interacting with the results can be - backed by either a YAML-formatted file or a PostgreSQL database. - - - -```bash -pipestat report -h -``` - - usage: pipestat report [-h] -n N (-f F | -c C | -a) -s S -i I -r R -v V [-o] - [-t] - - Report a result. - - optional arguments: - -h, --help show this help message and exit - -n N, --namespace N Name of the pipeline to report result for - -f F, --results-file F - Path to the YAML file where the results will be - stored. This file will be used as pipestat backend and - to restore the reported results across sesssions - -c C, --database-config C - Path to the YAML file with PostgreSQL database - configuration. Please refer to the documentation for - the file format requirements. - -a, --database-only Whether the reported data should not be stored in the - memory, only in the database. - -s S, --schema S Path to the schema that defines the results that can - be eported - -i I, --result-identifier I - ID of the result to report; needs to be defined in the - schema - -r R, --record-identifier R - ID of the record to report the result for - -v V, --value V Value of the result to report - -o, --overwrite Whether the result should override existing ones in - case of name clashes - -t, --try-convert Whether to try to convert the reported value into - reqiuired class in case it does not meet the schema - requirements - - - -```bash -pipestat retrieve -h -``` - - usage: pipestat retrieve [-h] -n N (-f F | -c C | -a) [-s S] -i I -r R - - Retrieve a result. - - optional arguments: - -h, --help show this help message and exit - -n N, --namespace N Name of the pipeline to report result for - -f F, --results-file F - Path to the YAML file where the results will be - stored. This file will be used as pipestat backend and - to restore the reported results across sesssions - -c C, --database-config C - Path to the YAML file with PostgreSQL database - configuration. Please refer to the documentation for - the file format requirements. - -a, --database-only Whether the reported data should not be stored in the - memory, only in the database. - -s S, --schema S Path to the schema that defines the results that can - be eported - -i I, --result-identifier I - ID of the result to report; needs to be defined in the - schema - -r R, --record-identifier R - ID of the record to report the result for - - - -```bash -pipestat remove -h -``` - - usage: pipestat remove [-h] -n N (-f F | -c C | -a) [-s S] -i I -r R - - Remove a result. - - optional arguments: - -h, --help show this help message and exit - -n N, --namespace N Name of the pipeline to report result for - -f F, --results-file F - Path to the YAML file where the results will be - stored. This file will be used as pipestat backend and - to restore the reported results across sesssions - -c C, --database-config C - Path to the YAML file with PostgreSQL database - configuration. Please refer to the documentation for - the file format requirements. - -a, --database-only Whether the reported data should not be stored in the - memory, only in the database. - -s S, --schema S Path to the schema that defines the results that can - be eported - -i I, --result-identifier I - ID of the result to report; needs to be defined in the - schema - -r R, --record-identifier R - ID of the record to report the result for - - - -```bash -pipestat inspect -h -``` - - usage: pipestat inspect [-h] -n N (-f F | -c C | -a) [-s S] [-d] - - Inspect a database. - - optional arguments: - -h, --help show this help message and exit - -n N, --namespace N Name of the pipeline to report result for - -f F, --results-file F - Path to the YAML file where the results will be - stored. This file will be used as pipestat backend and - to restore the reported results across sesssions - -c C, --database-config C - Path to the YAML file with PostgreSQL database - configuration. Please refer to the documentation for - the file format requirements. - -a, --database-only Whether the reported data should not be stored in the - memory, only in the database. - -s S, --schema S Path to the schema that defines the results that can - be eported - -d, --data Whether to display the data - - -## Usage demonstration - -### Reporting - -Naturally, the command line interface provides access to all the Python API functionalities of `pipestat`. So, for example, to report a result and back the object by a file use: - - -```bash -temp_file=`mktemp` -pipestat report -f $temp_file -n test -r sample1 -i number_of_things -v 100 -s ../tests/data/sample_output_schema.yaml --try-convert -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - Reported records for 'sample1' in 'test' namespace: - - number_of_things: 100 - - -The result has been reported and the database file has been updated: - - -```bash -cat $temp_file -``` - - test: - sample1: - number_of_things: 100 - - -Let's report another result: - - -```bash -pipestat report -f $temp_file -n test -r sample1 -i percentage_of_things -v 1.1 -s ../tests/data/sample_output_schema.yaml --try-convert -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - Reported records for 'sample1' in 'test' namespace: - - percentage_of_things: 1.1 - - - -```bash -cat $temp_file -``` - - test: - sample1: - number_of_things: 100 - percentage_of_things: 1.1 - - -### Inspection - -`pipestat inspect` command is a way to briefly look at the general `PipestatManager` state, like number of records, type of backend etc. - - -```bash -pipestat inspect -f $temp_file -n test -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - - - PipestatManager (test) - Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d) - Records count: 1 - - -In order to display the contents of the results file or database table associated with the indicated namespace, add `--data` flag: - - -```bash -pipestat inspect --data -f $temp_file -n test -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - - - PipestatManager (test) - Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d) - Records count: 1 - - Data: - test: - sample1: - number_of_things: 100 - percentage_of_things: 1.1 - - -### Retrieval - -Naturally, the reported results can be retrieved. Just call `pipestat retrieve` to do so: - - -```bash -pipestat retrieve -f $temp_file -n test -r sample1 -i percentage_of_things -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - 1.1 - - -### Removal - -In order to remove a result call `pipestat remove`: - - -```bash -pipestat remove -f $temp_file -n test -r sample1 -i percentage_of_things -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - Removed result 'percentage_of_things' for record 'sample1' from 'test' namespace - - -The results file and the state of the `PipestatManager` object reflect the removal: - - -```bash -cat $temp_file -``` - - test: - sample1: - number_of_things: 100 - - - -```bash -pipestat inspect --data -f $temp_file -n test -``` - - Reading data from '/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d' - - - PipestatManager (test) - Backend: file (/var/folders/3f/0wj7rs2144l9zsgxd3jn5nxc0000gn/T/tmp.G6Gtt93d) - Records count: 1 - - Data: - test: - sample1: - number_of_things: 100 diff --git a/docs_jupyter/python_api.ipynb b/docs_jupyter/python_api.ipynb index ab78c94f..851e3c87 100644 --- a/docs_jupyter/python_api.ipynb +++ b/docs_jupyter/python_api.ipynb @@ -12,13 +12,8 @@ "\n", "## Introduction\n", "\n", - "To make your Python pipeline pipestat-compatible, you first need to initialize pipestat with some important configuration setup:" - ] - }, - { - "cell_type": "markdown", - "metadata": {}, - "source": [ + "To make your Python pipeline pipestat-compatible, you first need to initialize pipestat with some important configuration setup:\n", + "\n", "1. **pipestat schema**: a path to a JSON-schema file that defines results reported by this pipeline\n", "2. **namespace**: defines a unique group name for reported results, typically a pipeline name\n", "3. **record identifier**: a unique name for a particular *run* of the pipeline, typically corresponding to a sample name\n", @@ -40,9 +35,14 @@ "Start by importing the `pipestat` package in Python." ] }, + { + "cell_type": "markdown", + "metadata": {}, + "source": [] + }, { "cell_type": "code", - "execution_count": 35, + "execution_count": 239, "metadata": {}, "outputs": [], "source": [ @@ -59,14 +59,14 @@ }, { "cell_type": "code", - "execution_count": 36, + "execution_count": 240, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ - "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpubs9xbqr.yaml\n" + "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpjupp4wcz.yaml\n" ] } ], @@ -86,7 +86,7 @@ }, { "cell_type": "code", - "execution_count": 37, + "execution_count": 241, "metadata": {}, "outputs": [], "source": [ @@ -107,7 +107,7 @@ }, { "cell_type": "code", - "execution_count": 38, + "execution_count": 242, "metadata": {}, "outputs": [ { @@ -118,7 +118,7 @@ ] }, "metadata": {}, - "execution_count": 38 + "execution_count": 242 } ], "source": [ @@ -134,7 +134,7 @@ }, { "cell_type": "code", - "execution_count": 39, + "execution_count": 243, "metadata": {}, "outputs": [ { @@ -145,7 +145,7 @@ ] }, "metadata": {}, - "execution_count": 39 + "execution_count": 243 } ], "source": [ @@ -161,7 +161,7 @@ }, { "cell_type": "code", - "execution_count": 40, + "execution_count": 244, "metadata": {}, "outputs": [ { @@ -172,7 +172,7 @@ ] }, "metadata": {}, - "execution_count": 40 + "execution_count": 244 } ], "source": [ @@ -202,7 +202,7 @@ }, { "cell_type": "code", - "execution_count": 41, + "execution_count": 245, "metadata": {}, "outputs": [ { @@ -227,7 +227,7 @@ ] }, "metadata": {}, - "execution_count": 41 + "execution_count": 245 } ], "source": [ @@ -243,7 +243,7 @@ }, { "cell_type": "code", - "execution_count": 42, + "execution_count": 246, "metadata": {}, "outputs": [ { @@ -257,7 +257,7 @@ ] }, "metadata": {}, - "execution_count": 42 + "execution_count": 246 } ], "source": [ @@ -274,7 +274,7 @@ }, { "cell_type": "code", - "execution_count": 43, + "execution_count": 247, "metadata": {}, "outputs": [ { @@ -301,7 +301,7 @@ }, { "cell_type": "code", - "execution_count": 44, + "execution_count": 248, "metadata": {}, "outputs": [ { @@ -319,7 +319,7 @@ ] }, "metadata": {}, - "execution_count": 44 + "execution_count": 248 } ], "source": [ @@ -342,7 +342,7 @@ }, { "cell_type": "code", - "execution_count": 45, + "execution_count": 249, "metadata": {}, "outputs": [ { @@ -357,7 +357,7 @@ ] }, "metadata": {}, - "execution_count": 45 + "execution_count": 249 } ], "source": [ @@ -373,7 +373,7 @@ }, { "cell_type": "code", - "execution_count": 46, + "execution_count": 250, "metadata": {}, "outputs": [ { @@ -391,7 +391,7 @@ ] }, "metadata": {}, - "execution_count": 46 + "execution_count": 250 } ], "source": [ @@ -407,7 +407,7 @@ }, { "cell_type": "code", - "execution_count": 47, + "execution_count": 251, "metadata": {}, "outputs": [ { @@ -432,7 +432,7 @@ ] }, "metadata": {}, - "execution_count": 47 + "execution_count": 251 } ], "source": [ @@ -457,7 +457,7 @@ }, { "cell_type": "code", - "execution_count": 48, + "execution_count": 252, "metadata": {}, "outputs": [], "source": [ @@ -471,7 +471,7 @@ }, { "cell_type": "code", - "execution_count": 49, + "execution_count": 253, "metadata": {}, "outputs": [ { @@ -486,7 +486,7 @@ ] }, "metadata": {}, - "execution_count": 49 + "execution_count": 253 } ], "source": [ @@ -502,14 +502,14 @@ }, { "cell_type": "code", - "execution_count": 50, + "execution_count": 254, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ - "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpubs9xbqr.yaml\n", + "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpjupp4wcz.yaml\n", "test:\n", " sample1:\n", " output_file:\n", @@ -538,7 +538,7 @@ }, { "cell_type": "code", - "execution_count": 51, + "execution_count": 255, "metadata": {}, "outputs": [ { @@ -549,7 +549,7 @@ ] }, "metadata": {}, - "execution_count": 51 + "execution_count": 255 } ], "source": [ @@ -558,7 +558,7 @@ }, { "cell_type": "code", - "execution_count": 52, + "execution_count": 256, "metadata": {}, "outputs": [ { @@ -576,7 +576,7 @@ ] }, "metadata": {}, - "execution_count": 52 + "execution_count": 256 } ], "source": [ @@ -592,7 +592,7 @@ }, { "cell_type": "code", - "execution_count": 53, + "execution_count": 257, "metadata": {}, "outputs": [ { @@ -621,7 +621,7 @@ }, { "cell_type": "code", - "execution_count": 54, + "execution_count": 258, "metadata": {}, "outputs": [ { @@ -637,7 +637,7 @@ ] }, "metadata": {}, - "execution_count": 54 + "execution_count": 258 } ], "source": [ @@ -657,7 +657,7 @@ }, { "cell_type": "code", - "execution_count": 55, + "execution_count": 259, "metadata": {}, "outputs": [ { @@ -668,7 +668,7 @@ ] }, "metadata": {}, - "execution_count": 55 + "execution_count": 259 } ], "source": [ @@ -684,7 +684,7 @@ }, { "cell_type": "code", - "execution_count": 56, + "execution_count": 260, "metadata": {}, "outputs": [ { @@ -697,7 +697,7 @@ ] }, "metadata": {}, - "execution_count": 56 + "execution_count": 260 } ], "source": [ @@ -720,7 +720,7 @@ }, { "cell_type": "code", - "execution_count": 57, + "execution_count": 261, "metadata": {}, "outputs": [ { @@ -738,7 +738,7 @@ ] }, "metadata": {}, - "execution_count": 57 + "execution_count": 261 } ], "source": [ @@ -754,7 +754,7 @@ }, { "cell_type": "code", - "execution_count": 58, + "execution_count": 262, "metadata": {}, "outputs": [ { @@ -772,7 +772,7 @@ ] }, "metadata": {}, - "execution_count": 58 + "execution_count": 262 } ], "source": [ @@ -788,7 +788,7 @@ }, { "cell_type": "code", - "execution_count": 59, + "execution_count": 263, "metadata": { "pycharm": { "name": "#%%\n" @@ -803,7 +803,7 @@ ] }, "metadata": {}, - "execution_count": 59 + "execution_count": 263 } ], "source": [ @@ -821,14 +821,14 @@ }, { "cell_type": "code", - "execution_count": 60, + "execution_count": 264, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ - "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpu8uxttep.yaml\n" + "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpshtnle33.yaml\n" ] } ], @@ -855,7 +855,7 @@ }, { "cell_type": "code", - "execution_count": 61, + "execution_count": 265, "metadata": {}, "outputs": [ { @@ -890,7 +890,7 @@ ] }, "metadata": {}, - "execution_count": 61 + "execution_count": 265 } ], "source": [ @@ -906,7 +906,7 @@ }, { "cell_type": "code", - "execution_count": 62, + "execution_count": 266, "metadata": {}, "outputs": [ { @@ -917,7 +917,7 @@ ] }, "metadata": {}, - "execution_count": 62 + "execution_count": 266 } ], "source": [ @@ -937,7 +937,7 @@ }, { "cell_type": "code", - "execution_count": 63, + "execution_count": 267, "metadata": {}, "outputs": [], "source": [ @@ -953,7 +953,7 @@ }, { "cell_type": "code", - "execution_count": 64, + "execution_count": 268, "metadata": {}, "outputs": [ { @@ -964,7 +964,7 @@ ] }, "metadata": {}, - "execution_count": 64 + "execution_count": 268 } ], "source": [ @@ -980,7 +980,7 @@ }, { "cell_type": "code", - "execution_count": 65, + "execution_count": 269, "metadata": {}, "outputs": [ { @@ -999,7 +999,7 @@ ] }, "metadata": {}, - "execution_count": 65 + "execution_count": 269 } ], "source": [ @@ -1028,14 +1028,14 @@ }, { "cell_type": "code", - "execution_count": 66, + "execution_count": 270, "metadata": {}, "outputs": [ { "output_type": "stream", "name": "stdout", "text": [ - "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmp5xtkiy3c.yaml\n" + "/var/folders/h8/8npwnh2s4rb8lr6hsy2ydrsh0000gp/T/tmpauamyheb.yaml\n" ] } ], @@ -1057,7 +1057,7 @@ }, { "cell_type": "code", - "execution_count": 67, + "execution_count": 271, "metadata": {}, "outputs": [ { @@ -1084,7 +1084,7 @@ }, { "cell_type": "code", - "execution_count": 68, + "execution_count": 272, "metadata": {}, "outputs": [ { @@ -1095,7 +1095,7 @@ ] }, "metadata": {}, - "execution_count": 68 + "execution_count": 272 } ], "source": [