serocov: Estimating the distribution of COVID-19-susceptible, -recovered, and -vaccinated individuals in Germany up to April 2022

# serocov

Estimate the distribution of (past) infections and vaccinations in the German population.

## Results

All results from this study are given in the `csv`-file that can be located at
`cookbook/example_qsuite_framework/results_update_large_N_meas_1000/results.csv`.

## Install

Please install in development mode with

    pip install -e ./serocov

or
    make

`serocov` was developed and tested for 

* Python 3.6
* Python 3.7
* Python 3.8

So far, the package's functionality was tested on Mac OS X and CentOS only.

## Dependencies

`serocov` directly depends on the following packages which will be installed by `pip` during the installation process

* `numpy>=1.17` 
* `polars==0.11.1`
* `epipack>=0.1.7`
* `isoweek>=1.3.3`

You might also want to install

* `pyreadr`

afterwards (needed to convert `.rData`-files).

## Documentation

### Data

This package relies on vaccination-status incidence data obtained from the RKI-based
German reporting system *SurvNet*. This data is obtained by running an R-script called
`import_Covid19_SQL_Impfstatus.R`. This script is not included in this repository.
Once run, it will produce a file called `Data_SurvNet_Impfstatus.rData`. Please copy
it to `serocov/data/Data_SurvNet_Impfstatus.rData`.

This package further relies on vaccination data and sequence data. Update scripts for this data are given
in `serocov/data/`. Or just run

    make update

Note that you need precomputed incidence rate and vaccination rate files to do analyses. You can create those
yourself, but in `make update`, they are also created and afterwards can be found in

* `serocov/data/parsed_incidences_impute_unvacc.csv`
* `serocov/data/parsed_vacc_curves.csv`

### Analysis

Check out `cookbook/example_qsuite_framework/` for an exhaustive example (files `qsuite_config.py` and `simulation.py`).
You might want to install [benmaier/qsuite](github.com/benmaier/qsuite).

Alternatively, check out the analysis functions in `serocov/medium_model_purepython.py`.

Also, here's a short example of how to use the code:

```python
from datetime import date
from serocov.medium_model_purepython import get_final_state
from serocov.load_data import t0, get_population_size
from serocov.paths import get_package_root

kw = {
        'parsed_incidences_file': get_package_root() / 'data' / 'parsed_incidences_impute_unvacc.csv',
        'parsed_vacc_curves_file': get_package_root() / 'data' / 'parsed_vacc_curves.csv',
        'region': 11, # Berlin
        'age_group': '18-59',

        # days, the average time after which an infected person becomes eligible for reinfection or vaccination,
        'tau': 90,

        # 1 - relative probability of reinfection after last infection
        'recovered_immunity': 0.5,

        # factor with which the number of reported cases is scaled to obtain the "true" number of
        # infections
        'asc_inc': 2.0, 

        # factor with which the number of reported vaccinations is scaled to obtain the "true" number of
        # vaccinations
        'asc_vacc': 1.03, 

        # whether or not to obtain the results in absolute numbers or relative to population size
        'relative': False,

        # You can approximately filter out cases by variants, by passing either
        # `None`, `'omicron'` or `'nonomicron'`. `None` just uses all variants.
        'multiply_incidence_with_variant_share': None,
    }

result = get_final_state(
          kw['parsed_incidences_file'],
          kw['parsed_vacc_curves_file'],
          kw['region'],
          kw['age_group'],
          tau=kw['tau'],
          tmax=(date.today() - t0).days,
          ascertainment_factor_incidence=kw['asc_inc'],
          ascertainment_factor_vaccination=kw['asc_vacc'],
          relative=kw['relative'],
          recovered_immunity=kw['recovered_immunity'],
          multiply_incidence_with_variant_share=kw['multiply_incidence_with_variant_share'],
         )

for compartment, final_count in result.items():
    print(compartment,':',
          '{0:4.2f}%'.format(100 * final_count / get_population_size(region=kw['region'],age_group=kw['age_group']))
         )
```

Should result in sth like:

```
S : 3.35%
I : 4.47%
Y : 5.04%
V : 5.85%
IV : 1.16%
VI : 8.65%
IVI : 1.25%
VY : 4.79%
IVY : 0.62%
VV : 44.77%
VIV : 2.24%
IVV : 5.31%
IVIV : 0.25%
VVI : 7.41%
VIVI : 0.26%
IVVI : 0.86%
IVIVI : 0.03%
VVY : 3.22%
VIVY : 0.09%
IVVY : 0.37%
IVIVY : 0.01%
```

## License

This project is licensed under the [MIT License](https://github.com/benmaier/serocov/blob/main/LICENSE).
Note that this excludes any images/pictures/figures shown here or in the documentation.