Commit 52c2fba4 authored by Hueser, Christian (FWCC) - 138593's avatar Hueser, Christian (FWCC) - 138593 Committed by Erxleben, Fredo (FWCC) - 136987
Browse files

Add information to README about the survey analysis program

README now includes the following sections:
* Start Analysis from Command-Line-Interface
  * Flags
  * Commands
  * Run Analysis
* Contribute with Own Analysis Scripts
  * Essential Criteria for Developing Own Analysis Scripts
  * File-System Structure of Core Component
  * Files and Classes Explained
parent 797c8eb6
Pipeline #27582 passed with stages
in 7 minutes and 28 seconds
......@@ -43,7 +43,7 @@ Therefore, use below extended installation options.
$ pip install -e .[dev]
```
This install some packages that are required for performing quality checks.
This installs some packages that are required for performing quality checks.
Usually they are also performed via GitLab CI, but can also be executed locally.
It is common practice to run some checks locally before pushing them online.
......@@ -54,6 +54,222 @@ $ isort -rc .
$ make lint
```
## Start Analysis from Command-Line-Interface
The survey analysis package is a program to be executed on the
Command-Line-Interface (CLI).
### Quick Start Example: Run Analysis
In order to run the survey analysis you need to copy the data-file into
a central location like the [data/](data/) sub-folder and tell the program
the path to that data file.
Now you can do the following to start the survey analysis from the CLI:
```shell script
$ pipenv run survey_analysis analyze data/<data_file_name>.csv
```
It tells the program that you would like to do the analysis,
where to find the analysis scripts, the _metadata_-file as well as
the _data_-file to be taken into account for the analysis.
### Flags
The program accepts a couple of flags:
1. Help flag
2. Verbosity flag
3. Scripts flag
4. Output Format flag
#### Help flag
Calling the program with the _help_-flag is the first thing to do
when being encountered with this program.
It outputs a so-called _Usage_-message to the CLI:
```shell script
$ pipenv run survey_analysis --help
Usage: survey_analysis [OPTIONS] COMMAND [ARGS]...
Analyze a given CSV file with a set of independent python scripts.
Options:
-v, --verbose Enable verbose output. Repeat up to 2 times for
increased effect [default: 0]
-s, --scripts TEXT Select the folder containing analysis scripts
[default: scripts]
-f, --output-format TEXT Designate output format. Supported values are:
SCREEN, PDF, PNG, SVG [default: screen]
--help Show this message and exit.
Commands:
analyze Read the given files into global data and metadata objects.
version Get the library version.
```
#### Verbosity flag
The _verbosity_-flag can be provided in order to specify the verbosity
of the output to the CLI.
This flag is called `--verbose` or `-v` for short:
```shell script
$ pipenv run survey_analysis --verbose <COMMAND>
```
```shell script
$ pipenv run survey_analysis -v <COMMAND>
```
The verbosity of the output can be increased even more
by duplicating the flag `--verbose` or `-v` up to two times:
```shell script
$ pipenv run survey_analysis --verbose --verbose --verbose <COMMAND>
```
```shell script
$ pipenv run survey_analysis -vvv <COMMAND>
```
#### Scripts flag
Beside verbosity there is a _scripts_-flag called `--scripts` or
`-s` for short:
```shell script
$ pipenv run survey_analysis --scripts scripts/ <COMMAND>
```
```shell script
$ pipenv run survey_analysis -s scripts/ <COMMAND>
```
This will tell the program in which folder to look for the actual
analysis scripts.
In case the _scripts_-flag is omitted it defaults to sub-folder `scripts/`.
#### Output Format flag
The user is also able to let the application know in which output format the
diagrams should be generated during the analysis.
For this purpose there is a flag called `--output-format` or `-f` for short.
Allowed values to this flag are the following:
* SCREEN
* PDF
* PNG
* SVG
On the CLI the actual call looks like this:
```shell script
$ pipenv run survey_analysis --output-format PNG <COMMAND>
```
```shell script
$ pipenv run survey_analysis -f PNG <COMMAND>
```
### Commands
There are two different commands implemented which come with different
flags and parameters:
1. Command _version_
2. Command _analyze_
#### Command _version_
The `version` command outputs the version number of
this CLI-program like so:
```shell script
$ pipenv run survey_analysis version
0.0.1
```
#### Command _analyze_
The more interesting command is the `analyze` command
which comes with a _metadata_-flag `--metadata` or `-m` for short and
a _data_-parameter.
In case the _metadata_-flag is omitted it assumes the following
path to the metadata file:
`data/HIFIS_Software_Survey_2020_Questions.yml`.
The _data_-parameter can _not_ be omitted and need to be given explicitly
in order to be able to start the analysis.
This is an example of how to do the analysis:
```shell script
$ pipenv run survey_analysis analyze data/<data_file_name>.csv
```
## Contribute with Own Analysis Scripts
### Essential Criteria for Developing Own Analysis Scripts
As you might have read in the previous sections the actual analysis scripts
reside in a specific folder called `scripts/`.
All scripts in that folder will be automatically discovered by the package
`survey_analysis` when running the analysis.
In order that the program recognizes the scripts in that folder as
analysis scripts they need to fulfil the following two criteria:
1. The filename need to end on `.py`.
2. The file need to contain a function called `run` without any parameters.
```python
"""
A dummy script for testing the function dispatch
.. currentmodule:: survey_analysis.scripts.dummy
.. moduleauthor:: HIFIS Software <software@hifis.net>
"""
def run():
print("Example Script")
```
If both criteria are satisfied the program will execute the `run`-functions
of the analysis scripts in an arbitrary sequence.
### File-System Structure of Core Component
```shell script
$ tree survey_analysis/
survey_analysis/
├── answer.py
├── cli.py
├── data.py
├── dispatch.py
├── globals.py
├── metadata.py
├── question.py
├── settings.py
└── version.py
```
### Files and Classes Explained
**ToDo**: This section need to be extended to all files and classes
found in package `survey_analysis`.
#### Classes to Represent Questions
File `question.py` contains the following classes:
- `AbstractQuestion`: Abstract class providing properties of a question
like `id` and `text`.
- `Question`: Non-abstract class inheriting from abstract-base-class
`AbstractQuestion`. It represents a question with associated answers.
- `QuestionCollection`: Non-abstract class inheriting from abstract-base-class
`AbstractQuestion`. It represents a question with associated sub-questions.
#### Class to Represent Answers
File `answer.py` contains class `Answer`.
This class provides properties of an answer like `id` and `text`.
## Resources
Below are some handy resource links.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment