Bio Models

This module provides functionality for retrieving, parsing, and loading biological Boolean network models from public online repositories.

The boolforge.bio_models module allows users to programmatically access and import published Boolean and logical gene regulatory network models from GitHub repositories such as:

  • expert-curated (ckadelka): manually curated models from the Design Principles of Gene Regulatory Networks repository.

  • pystablemotifs (jcrozum): models accompanying the PyStableMotifs library.

  • biodivine (sybila): models from the Sybila Biodivine Boolean Models repository.

Functions are provided to:

  • Recursively list and download files from GitHub folders using the REST API.

  • Fetch raw text or byte content from remote sources.

  • Parse Boolean network models into BooleanNetwork objects.

  • Batch-download and convert all models from supported repositories.

This module is intended to facilitate reproducible research by providing direct access to real-world Boolean GRN models for simulation, comparison, and benchmarking.

Example

>>> from boolforge import bio_models
>>> result = bio_models.get_bio_models_from_repository('expert-curated (ckadelka)')
>>> len(result['BooleanNetworks'])
122
>>> result['BooleanNetworks'][0].variables[:5]
['GeneA', 'GeneB', 'GeneC', 'GeneD', 'GeneE']
boolforge.bio_models.get_content_in_remote_folder(url: str) → tuple[source]

Retrieve file names and raw download URLs from a GitHub repository folder.

Parameters

urlstr

GitHub API URL pointing to a repository folder.

Returns

tuple[list[str], list[str]]

A tuple (file_names, file_download_urls), where:

  • file_names contains the names of discovered files.

  • file_download_urls contains corresponding raw download URLs.

boolforge.bio_models.fetch_file(download_url: str) → str[source]

Download raw text content from a remote file.

Parameters

download_urlstr

Direct download URL to the file.

Returns

str

File content as plain text.

boolforge.bio_models.fetch_file_bytes(download_url: str) → bytes[source]

Download raw binary content from a remote file.

Parameters

download_urlstr

Direct download URL to the file.

Returns

bytes

File content as raw bytes.

boolforge.bio_models.load_model(download_url: str, max_degree: int = 24, possible_separators: list = ['* =', '*=', '=', ','], original_not: str = 'NOT', original_and: str = 'AND', original_or: str = 'OR', IGNORE_FIRST_LINE: bool = False) → BooleanNetwork[source]

Load and parse a Boolean network model from a remote text file.

Parameters

download_urlstr

Direct download URL to the model file.

max_degreeint, optional

Maximum allowed in-degree for nodes (default: 24).

possible_separatorslist[str], optional

Possible assignment separators used in the model file.

original_notstr, optional

Logical negation operator used in the model file.

original_andstr, optional

Logical AND operator used in the model file.

original_orstr, optional

Logical OR operator used in the model file.

IGNORE_FIRST_LINEbool, optional

If True, skip the first line of the file (default: False).

Returns

BooleanNetwork

Parsed Boolean network.

Raises

ValueError

If the model cannot be parsed.

boolforge.bio_models.get_bio_models_from_repository(repository: str = 'expert-curated (ckadelka)', download_urls_pystablemotifs: list[str] | None = None) → dict[source]

Load Boolean network models from selected online repositories.

This function downloads, parses, and constructs Boolean network models from several curated online repositories. Models that cannot be parsed are skipped and recorded separately.

Parameters

repositorystr, optional

Identifier of the source repository. Supported values are:

  • ‘expert-curated (ckadelka)’ (default)

  • ‘pystablemotifs (jcrozum)’

  • ‘biodivine (sybila)’

download_urls_pystablemotifslist[str] or None, optional

Optional list of direct download URLs for PyStableMotifs models. If provided, these URLs are used instead of querying the GitHub API (faster). If None (default), model URLs are fetched dynamically from GitHub.

Returns

dict

Dictionary with the following keys:

  • ‘BooleanNetworks’list[BooleanNetwork]

    List of successfully parsed Boolean network models.

  • ‘SuccessfulDownloadURLs’list[str]

    URLs corresponding to models that were successfully loaded.

  • ‘FailedDownloadURLs’list[str]

    URLs corresponding to models that could not be parsed or loaded.