# Data generator for synthetic data including artificial classes, intraclass correlations, pseudo-classes and random data - [Sphinx Doc](https://sigrun-may.github.io/biomedical-data-generator/)
## Table of Contents
- [Purpose](#purpose)
- [Data structure](#data-structure)
- [Different parts of the data set](#different-parts-of-the-data-set)
- [Data distribution and effect sizes](#data-distribution-and-effect-sizes)
- [Correlations](#correlations)
- [Pseudo-classes](#pseudo-classes)
- [Random Features](#random-features)
- [Installation](#installation)
- [Licensing](#licensing)
## Purpose
In order to develop new methods or to compare existing methods for feature selection, reference data with known dependencies and importance of the individual features are needed. This data generator can be used to simulate biological data for example artificial high throughput data including artificial biomarkers. Since commonly not all true biomarkers and internal dependencies of high-dimensional biological datasets are known with
certainty, artificial data **enables to know the expected outcome in advance**. In synthetic data, the feature importances and the distribution of each class are known. Irrelevant features can be purely random or belong to a pseudo-class. Such data can be used, for example, to make random effects observable.
## Data structure
### Different parts of the data set
The biomedical-data-generator produces data sets consisting of up to three main parts:
1. **Relevant features** belonging to an artificial class (for example artificial biomarkers)
1. [optional] **Pseudo-classes** (for example a patient's height or gender, which have no association with a particular disease)
1. [optional] **Random data** representing the features (for example biomarker candidates) that are not associated with any class
The number of artificial classes is not limited. Each class is generated individually and then combined with the others.
In order to simulate artificial biomarkers in total, all individual classes have the same number of features in total.
This is an example of simulated binary biological data including artificial biomarkers:
### Data distribution and effect sizes
For each class, either the **normal distribution or the log normal distribution** can be selected. The different **classes can be shifted** to regulate the effect sizes and to influence the difficulty of data analysis.
The normally distributed data could, for example, represent the range of values of healthy individuals.
In the case of a disease, biological systems are in some way out of balance.
Extreme changes in values as well as outliers can then be observed ([Concordet et al., 2009](https://doi.org/10.1016/j.cca.2009.03.057)).
Therefore, the values of a diseased individual could be simulated with a lognormal distribution.
Example of log-normal and normal distributed classes:
### Correlations
**Intra-class correlation can be generated for each artificial class**. Any number of groups
containing correlated features can be combined with any given number of uncorrelated features.
However, a high correlation within a group does not necessarily lead to
a high correlation to other groups or features of the same class. An example of a class with three
highly correlated groups but without high correlations between all groups:
It is probably likely that biomarkers of healthy individuals usually have a relatively low correlation. On average,
their values are within a usual "normal" range. In this case, one biomarker tends to be in the upper normal range and another biomarker in the lower normal range. However, individually it can also be exactly the opposite, so that the correlation between healthy individuals would be rather low. Therefore, the **values of healthy people
could be simulated without any special artificially generated correlations**.
In the case of a disease, however, a biological system is brought out of balance in a certain way and must react to it.
For example, this reaction can then happen in a coordinated manner involving several biomarkers,
or corresponding cascades (e.g. pathways) can be activated or blocked. This can result in a **rather stronger
correlation of biomarkers in patients suffering from a disease**. To simulate these intra-class correlations,
a class is divided into a given number of groups with high internal correlation
(the respective strength can be defined).
## Pseudo-classes
One option for an element of the generated data set is a pseudo-class. For example, this could be a
patient's height or gender, which are not related to a specific disease.
The generated pseudo-class contains the same number of classes with identical distributions as the artificial biomarkers.
But after the generation of the individual classes, all samples (rows) are randomly shuffled.
Finally, combining the shuffled data with the original, unshuffled class labels, the pseudo-class no longer
has a valid association with any class label. Consequently, no element of the pseudo-class should be
recognized as relevant by a feature selection algorithm.
## Random Features
The artificial biomarkers and, if applicable, the optional pseudo-classes can be combined with any number
of random features. Varying the number of random features can be used, for example, to analyze random effects
that occur in small sample sizes with a very large number of features.
## Installation
The biomedical-data-generator is available at [the Python Package Index (PyPI)](https://pypi.org/project/biomedical-data-generator/).
It can be installed with pip:
```bash
$ pip install biomedical-data-generator
```
## Quickstart example
This is an example of how to generate a synthetic dataset:
```python
from biomedical_data_generator import DatasetConfig, generate_dataset
cfg = DatasetConfig(
n_samples=30,
n_features=200,
n_informative=5,
random_state=42,
)
X, y, meta = generate_dataset(cfg)
print(X.shape, y.shape, meta.n_classes)
```
## Licensing
Copyright (c) 2022 Sigrun May, Helmholtz-Zentrum für Infektionsforschung GmbH (HZI)<br/>
Copyright (c) 2022 Sigrun May, Ostfalia Hochschule für angewandte Wissenschaften
Licensed under the **MIT License** (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License by reviewing the file
[LICENSE](https://github.com/sigrun-may/biomedical-data-generator/blob/main/LICENSE) in the repository.
Raw data
{
"_id": null,
"home_page": null,
"name": "biomedical-data-generator",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.10",
"maintainer_email": null,
"keywords": "artificial data, synthetic data, data generation, data simulation, data science, machine learning, statistics, data analysis",
"author": "Sigrun May",
"author_email": "s.may@ostfalia.de",
"download_url": "https://files.pythonhosted.org/packages/5a/16/f12d627185e46d133a3dc56ebd0fd16304d48544e7b60ff7ccf710b5e4ab/biomedical_data_generator-0.1.4.tar.gz",
"platform": null,
"description": "# Data generator for synthetic data including artificial classes, intraclass correlations, pseudo-classes and random data - [Sphinx Doc](https://sigrun-may.github.io/biomedical-data-generator/)\n\n## Table of Contents\n\n- [Purpose](#purpose)\n- [Data structure](#data-structure)\n - [Different parts of the data set](#different-parts-of-the-data-set)\n - [Data distribution and effect sizes](#data-distribution-and-effect-sizes)\n - [Correlations](#correlations)\n- [Pseudo-classes](#pseudo-classes)\n- [Random Features](#random-features)\n- [Installation](#installation)\n- [Licensing](#licensing)\n\n## Purpose\n\nIn order to develop new methods or to compare existing methods for feature selection, reference data with known dependencies and importance of the individual features are needed. This data generator can be used to simulate biological data for example artificial high throughput data including artificial biomarkers. Since commonly not all true biomarkers and internal dependencies of high-dimensional biological datasets are known with\ncertainty, artificial data **enables to know the expected outcome in advance**. In synthetic data, the feature importances and the distribution of each class are known. Irrelevant features can be purely random or belong to a pseudo-class. Such data can be used, for example, to make random effects observable.\n\n## Data structure\n\n### Different parts of the data set\n\nThe biomedical-data-generator produces data sets consisting of up to three main parts:\n\n1. **Relevant features** belonging to an artificial class (for example artificial biomarkers)\n1. [optional] **Pseudo-classes** (for example a patient's height or gender, which have no association with a particular disease)\n1. [optional] **Random data** representing the features (for example biomarker candidates) that are not associated with any class\n\nThe number of artificial classes is not limited. Each class is generated individually and then combined with the others.\nIn order to simulate artificial biomarkers in total, all individual classes have the same number of features in total.\n\nThis is an example of simulated binary biological data including artificial biomarkers:\n\n\n\n### Data distribution and effect sizes\n\nFor each class, either the **normal distribution or the log normal distribution** can be selected. The different **classes can be shifted** to regulate the effect sizes and to influence the difficulty of data analysis.\n\nThe normally distributed data could, for example, represent the range of values of healthy individuals.\nIn the case of a disease, biological systems are in some way out of balance.\nExtreme changes in values as well as outliers can then be observed ([Concordet et al., 2009](https://doi.org/10.1016/j.cca.2009.03.057)).\nTherefore, the values of a diseased individual could be simulated with a lognormal distribution.\n\nExample of log-normal and normal distributed classes:\n\n\n\n### Correlations\n\n**Intra-class correlation can be generated for each artificial class**. Any number of groups\ncontaining correlated features can be combined with any given number of uncorrelated features.\n\nHowever, a high correlation within a group does not necessarily lead to\na high correlation to other groups or features of the same class. An example of a class with three\nhighly correlated groups but without high correlations between all groups:\n\n\n\nIt is probably likely that biomarkers of healthy individuals usually have a relatively low correlation. On average,\ntheir values are within a usual \"normal\" range. In this case, one biomarker tends to be in the upper normal range and another biomarker in the lower normal range. However, individually it can also be exactly the opposite, so that the correlation between healthy individuals would be rather low. Therefore, the **values of healthy people\ncould be simulated without any special artificially generated correlations**.\n\nIn the case of a disease, however, a biological system is brought out of balance in a certain way and must react to it.\nFor example, this reaction can then happen in a coordinated manner involving several biomarkers,\nor corresponding cascades (e.g. pathways) can be activated or blocked. This can result in a **rather stronger\ncorrelation of biomarkers in patients suffering from a disease**. To simulate these intra-class correlations,\na class is divided into a given number of groups with high internal correlation\n(the respective strength can be defined).\n\n## Pseudo-classes\n\nOne option for an element of the generated data set is a pseudo-class. For example, this could be a\npatient's height or gender, which are not related to a specific disease.\n\nThe generated pseudo-class contains the same number of classes with identical distributions as the artificial biomarkers.\nBut after the generation of the individual classes, all samples (rows) are randomly shuffled.\nFinally, combining the shuffled data with the original, unshuffled class labels, the pseudo-class no longer\nhas a valid association with any class label. Consequently, no element of the pseudo-class should be\nrecognized as relevant by a feature selection algorithm.\n\n## Random Features\n\nThe artificial biomarkers and, if applicable, the optional pseudo-classes can be combined with any number\nof random features. Varying the number of random features can be used, for example, to analyze random effects\nthat occur in small sample sizes with a very large number of features.\n\n## Installation\n\nThe biomedical-data-generator is available at [the Python Package Index (PyPI)](https://pypi.org/project/biomedical-data-generator/).\nIt can be installed with pip:\n\n```bash\n$ pip install biomedical-data-generator\n```\n\n## Quickstart example\n\nThis is an example of how to generate a synthetic dataset:\n\n```python\nfrom biomedical_data_generator import DatasetConfig, generate_dataset\n\ncfg = DatasetConfig(\n n_samples=30,\n n_features=200,\n n_informative=5,\n random_state=42,\n)\n\nX, y, meta = generate_dataset(cfg)\nprint(X.shape, y.shape, meta.n_classes)\n```\n\n## Licensing\n\nCopyright (c) 2022 Sigrun May, Helmholtz-Zentrum f\u00fcr Infektionsforschung GmbH (HZI)<br/>\nCopyright (c) 2022 Sigrun May, Ostfalia Hochschule f\u00fcr angewandte Wissenschaften\n\nLicensed under the **MIT License** (the \"License\"); you may not use this file except in compliance with the License.\nYou may obtain a copy of the License by reviewing the file\n[LICENSE](https://github.com/sigrun-may/biomedical-data-generator/blob/main/LICENSE) in the repository.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Generate synthetic data for data science, machine learning, and statistics.",
"version": "0.1.4",
"project_urls": {
"Bug Tracker": "https://github.com/sigrun-may/biomedical-data-generator/issues",
"Homepage": "https://github.com/sigrun-may/biomedical-data-generator"
},
"split_keywords": [
"artificial data",
" synthetic data",
" data generation",
" data simulation",
" data science",
" machine learning",
" statistics",
" data analysis"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ef868d7ecc0d3ba2106ca3b0bd1035e42cc1f59a34bd053c52d861cd91fadf6c",
"md5": "1171309004205e9b7177bf5df3dba25e",
"sha256": "2a61b903bb8e11e148d538648419c5ed23d4033aeba179ae615ab395bf06cb99"
},
"downloads": -1,
"filename": "biomedical_data_generator-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "1171309004205e9b7177bf5df3dba25e",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.10",
"size": 23027,
"upload_time": "2025-10-06T10:26:16",
"upload_time_iso_8601": "2025-10-06T10:26:16.192879Z",
"url": "https://files.pythonhosted.org/packages/ef/86/8d7ecc0d3ba2106ca3b0bd1035e42cc1f59a34bd053c52d861cd91fadf6c/biomedical_data_generator-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5a16f12d627185e46d133a3dc56ebd0fd16304d48544e7b60ff7ccf710b5e4ab",
"md5": "0380e480752ab1998496fc342530e1ab",
"sha256": "c02c655b054e652bee7ec27da685e2caaae305209f930077ff578773abe59c8c"
},
"downloads": -1,
"filename": "biomedical_data_generator-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "0380e480752ab1998496fc342530e1ab",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.10",
"size": 23134,
"upload_time": "2025-10-06T10:26:17",
"upload_time_iso_8601": "2025-10-06T10:26:17.359716Z",
"url": "https://files.pythonhosted.org/packages/5a/16/f12d627185e46d133a3dc56ebd0fd16304d48544e7b60ff7ccf710b5e4ab/biomedical_data_generator-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-06 10:26:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "sigrun-may",
"github_project": "biomedical-data-generator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "biomedical-data-generator"
}
JSON
