BioCypher Project template discussion

[ecarrenolozano]

👋 Hi dear BioCypher community,

I would like to introduce the context before my questions

Context:

Imagine I've cloned the BioCypher project template repository to create an adapter tailored to my needs, which I've named "omnipath-secondary-adapter". Before I begin working with the template, I need to complete the following steps:

1. Change the adapter's name (/template_package/adapters/example_adapter.py)
2. Adjust the pyproject.toml file

Questions:

1. Do you have defined an nomenclature to name the adater's file (for instance, omnipath_sec_adapter.py)? In case of having defined this, I would like to stick to it. In case no, this could be proposed too.

2. Which parameters should I, as a user, modify in the TOML file?

   • name? <--- should be the name of the current repository? For instance: "omnipath-secondary-adapater"
   • version? <--- Is this the version of BioCypher? Currently, last release is 0.6.0. Should I, as user, change this?
   • authors? <--- The names of the authors who are creating the adapter, correct?

Reference pyproject.toml file in the template:

[tool.poetry]
name = "biocypher-project-template"
version = "0.5.43"
description = "Template for creating a BioCypher-driven knowledge graph"
authors = [
    "Sebastian Lobentanzer <[email protected]>",
    "Andreas Maier <[email protected]>",
]
license = "MIT"
readme = "README.md"

[tool.poetry.dependencies]
python = "^3.10"
biocypher = "^0.5.43"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

Thanks in advance!!!

[slobentanzer]

Thanks @ecarrenolozano. Here are my opinions:

Do you have defined an nomenclature to name the adater's file (for instance, omnipath_sec_adapter.py)? In case of having defined this, I would like to stick to it. In case no, this could be proposed too.

There is no nomenclature currently. omnipath_sec_adapter.py sounds reasonable, but also not sure the sec is necessary, because it is implied by the name (OmniPath is not an atomic resource). I usually go with omnipath_adapter.py; we may also want to record the input format, so maybe something like omnipath_json_adapter.py would be informative.

Which parameters should I, as a user, modify in the TOML file?
name? <--- should be the name of the current repository? For instance: "omnipath-secondary-adapater"

Yes, the name should reflect the current repo. However, a repo is not just an adapter, but a pipeline, which can consist of multiple adapters. This would be the name of the project, which in your case is also OmniPath, so there would not be much difference. I would not call the repo an adapter though; the adapter is just a part of the pipeline.

version? <--- Is this the version of BioCypher? Currently, last release is 0.6.0. Should I, as user, change this?

No, this is the version of the pipeline. If you change something in the pipeline, these changes should be versioned. This is independent of BioCypher version.

authors? <--- The names of the authors who are creating the adapter, correct?

Not the adapter, but the pipeline (repository). All contents of the TOML refer to the repository it contains, which is a pipeline in BioCypher terms.

[ecarrenolozano]

There is no nomenclature currently. omnipath_sec_adapter.py sounds reasonable, but also not sure the sec is necessary, because it is implied by the name (OmniPath is not an atomic resource). I usually go with omnipath_adapter.py; we may also want to record the input format, so maybe something like omnipath_json_adapter.py would be informative.

1. Nomenclature for adapter names.
   Based on your explanation, I propose the following:

  <name of the adapter>_adapter_<input format>.py
  
  <name of the adapter>: one short word indicating the origin of the information.
  <input_format>: one word indicating the following:
  	- if a file: the format of the files used as inputs for the adapter.
  	- if a database: the name of the database/data warehouse/cloud technology where the data resides.
  	
  Examples:
   - omnipath_adapter_json.py
   - omnipath_adapter_parquet.py
   - collectri_adapter_bigquery.py
   - collectri_adapter_csv.py
   - annotations_adapter_mysql.py

Notes: I propose this with the following advantages for the future

• We can add progressively new words to the name in case of require this.
  - for instance: annotations_adapter_mysql_v1.py, here v1 has been added, but for now it is not required.
• In case of built a system to collect metadata for our already made adapters, we can collect metadata easily by just processing the names following an structure.

Yes, the name should reflect the current repo. However, a repo is not just an adapter, but a pipeline, which can consist of multiple adapters. This would be the name of the project, which in your case is also OmniPath, so there would not be much difference. I would not call the repo an adapter though; the adapter is just a part of the pipeline.

2. Pipeline concept.

• Please correct me if I am wrong. We explicitly say that a repository by itself should be treated as a desired pipeline, it means that I can have the cases:
  • Having a single repository means a single pipeline, and it could contains multiple adapters to consume the information.
  • Having multiple repositories, means having multiple pipelines (serving different purposes). Each pipeline can contain multiple adapters.

3. Pipeline versioning

• As an user, I could put an arbitrary version, for my own purposes. For instance: I can put version 1.0.0, 2.0.0 or 3.0.0. That is sufficient for my experiments. But in case of planning to share my super pipeline with the community, who controls the version in this case?

[slobentanzer]

This is correct. I would probably not include a version in the adapter file name though. This is a problem to be solved later (eg, could be related to the planned adapters repository).

The pipeline version is at the discretion of the maintainer of each pipeline. We can suggest to follow SemVer conventions.