fair-ca-visualization 0.4.0__py3-none-any.whl

fair_ca_visualization-0.4.0.dist-info/METADATA

@@ -0,0 +1,84 @@
+Metadata-Version: 2.5
+Name: fair-ca-visualization
+Version: 0.4.0
+Summary: Interactive visualization of the FAIR COMBINE Archive Indicators (FAIR-CA) for computational models.
+Project-URL: Homepage, https://faircombine.streamlit.app
+Project-URL: Documentation, https://matthiaskoenig.github.io/fair-ca-visualization
+Project-URL: Repository, https://github.com/matthiaskoenig/fair-ca-visualization
+Project-URL: Issues, https://github.com/matthiaskoenig/fair-ca-visualization/issues
+Project-URL: Changelog, https://github.com/matthiaskoenig/fair-ca-visualization/tree/develop/release-notes
+Project-URL: Download, https://pypi.org/project/fair-ca-visualization
+Author-email: Matthias König <konigmatt@googlemail.com>
+Maintainer-email: Matthias König <konigmatt@googlemail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: COMBINE,FAIR,indicators,modeling,standardization,streamlit
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.14
+Requires-Dist: numpy>=2.4.3
+Requires-Dist: openpyxl>=3.1.5
+Requires-Dist: pandas<3,>=2.3.3
+Requires-Dist: plotly>=6.6.0
+Requires-Dist: pyarrow>=23.0.1
+Requires-Dist: rich>=14.3.3
+Requires-Dist: streamlit>=1.55.0
+Description-Content-Type: text/markdown
+
+![fair-ca-visualization logo](https://github.com/matthiaskoenig/fair-ca-visualization/raw/develop/docs/images/fair-ca-logo.png)
+
+# fair-ca-visualization
+
+[![GitHub Actions CI/CD Status](https://github.com/matthiaskoenig/fair-ca-visualization/actions/workflows/ci-cd.yml/badge.svg)](https://github.com/matthiaskoenig/fair-ca-visualization/actions/workflows/ci-cd.yml) [![Documentation](https://img.shields.io/badge/docs-fair--ca--visualization-008080.svg)](https://matthiaskoenig.github.io/fair-ca-visualization) [![Version](https://img.shields.io/pypi/v/fair-ca-visualization.svg)](https://pypi.org/project/fair-ca-visualization/) [![Python Versions](https://img.shields.io/pypi/pyversions/fair-ca-visualization.svg)](https://pypi.org/project/fair-ca-visualization/) [![MIT License](https://img.shields.io/pypi/l/fair-ca-visualization.svg)](https://opensource.org/licenses/MIT) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13755820.svg)](https://doi.org/10.5281/zenodo.13755820)
+
+Computational models are essential tools for studying complex systems which, particularly in clinical settings, need to be quality-approved and transparent. A community-driven approach to enhance the transparency and communication of model features is adherence to the principles of Findability, Accessibility, Interoperability and Reusability (FAIR). The FAIR COMBINE Archive Indicators (FAIR-CA) adapt the FAIR indicators published by the Research Data Alliance to assess the FAIRness of models encoded in domain-specific standards, such as those established by [COMBINE](https://co.mbine.org).
+
+The FAIR COMBINE Archive Indicators project is available from [https://github.com/FAIR-CA-indicators/FAIR-CA-indicators.github.io](https://github.com/FAIR-CA-indicators/FAIR-CA-indicators.github.io).
+
+`fair-ca-visualization` visualizes FAIR-CA assessments interactively. The app is available from https://faircombine.streamlit.app, the documentation from https://matthiaskoenig.github.io/fair-ca-visualization.
+
+[![The fair-ca-visualization app](https://github.com/matthiaskoenig/fair-ca-visualization/raw/develop/docs/images/fair-ca-example.png)](https://faircombine.streamlit.app)
+
+# Installation
+
+To run the app locally, install the package from [PyPI](https://pypi.org/project/fair-ca-visualization/) (python 3.14) and start it with `fairvis`:
+
+```bash
+uv tool install fair-ca-visualization
+fairvis
+```
+
+See the [installation guide](https://matthiaskoenig.github.io/fair-ca-visualization/installation/) for pip and for running from a checkout, and [contributing](https://matthiaskoenig.github.io/fair-ca-visualization/development/) for the development setup.
+
+# How to cite
+
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13755820.svg)](https://doi.org/10.5281/zenodo.13755820)
+
+> König M. fair-ca-visualization: interactive visualization of the FAIR COMBINE Archive Indicators. Zenodo. [doi:10.5281/zenodo.13755820](https://doi.org/10.5281/zenodo.13755820)
+
+```bibtex
+@software{fair_ca_visualization,
+  author    = {König, Matthias},
+  title     = {fair-ca-visualization: interactive visualization of the FAIR COMBINE Archive Indicators},
+  publisher = {Zenodo},
+  doi       = {10.5281/zenodo.13755820},
+  url       = {https://doi.org/10.5281/zenodo.13755820}
+}
+```
+
+# License
+
+- Source Code: [MIT](https://opensource.org/license/MIT)
+- Documentation: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
+
+# Funding
+
+Matthias König (MK) was supported by the Federal Ministry of Education and Research (BMBF, Germany) within the research network Systems Medicine of the Liver (LiSyM, grant number 031L0054). MK is supported by the Federal Ministry of Education and Research (BMBF, Germany) within ATLAS by grant number 031L0304B and by the German Research Foundation (DFG) within the Research Unit Program FOR 5151 QuaLiPerF (Quantifying Liver Perfusion-Function Relationship in Complex Resection - A Systems Medicine Approach) by grant number 436883643 and by grant number 465194077 (Priority Programme SPP 2311, Subproject SimLivA).
+
+© 2024 - 2026 Matthias König

fair_ca_visualization-0.4.0.dist-info/RECORD

@@ -0,0 +1,26 @@
+fairvis/__init__.py,sha256=QKec5mel6WuhYiJfip0L7zUSPROakL6gNrvqSFNK7W0,135
+fairvis/__main__.py,sha256=nko_6M0jQuqHg4XRfaPcqSYzo7urXqA_yCIjQQwq8j8,115
+fairvis/app.py,sha256=dv0NPANrVbnzun-yvRSfcfG1AW9bIlyCcmNhIEkHEu4,7942
+fairvis/cli.py,sha256=_fp--nPtPuEF4ZudbhulCafQkDmLci3wqviJJtaDXy0,1517
+fairvis/console.py,sha256=GaohtlJZurR4ExXRtL7GIHrj67_6-jFYTw2ai6QYVnQ,331
+fairvis/data_io.py,sha256=nTCKUTvUai-XdxEx8ZYBpiZwaVD7X87GYJyz2nYXWdE,5208
+fairvis/example.py,sha256=XPfjXfkMHlbPyaadSjhVHqpkBqr_lbZZqoUoswNLT_Q,417
+fairvis/settings.py,sha256=yoajWwJ9SkNG8F4cwbCFqotx9uF7TpYH5jljYtKEf0s,589
+fairvis/visualization.py,sha256=pPFi55209bd76TUsTN0XgnNUZ42fNTf42degrCkyJvA,3118
+fairvis/data/FAIR_assessment_template.xlsx,sha256=-VzXMptkrXSgVktUEPN17898o8Coe5TgEsydDnHcU54,17011
+fairvis/data/assessments/Alejandro2026_empagliflozin.xlsx,sha256=IXrMmyHaKuQ4uaf59_B1br5Swc-NZSFYE8q45jT-c9Y,67728
+fairvis/data/assessments/BioModels_C19_curated.xlsx,sha256=meLgXWwnvH0q4rntdmtw2zZCSjfZuoStUpeHU8PVb5Y,18859
+fairvis/data/assessments/BioModels_curated.xlsx,sha256=gcj8prxjigVI0Q21gh-3wprbFd3oEUpJJrGd0yel-pc,17585
+fairvis/data/assessments/BioModels_non_curated.xlsx,sha256=o-H948t6T1GJcN0o_QRvel-Piz4fvFZdOqIrxNkEWGA,18896
+fairvis/data/assessments/Casabianca2026_rivaroxaban.xlsx,sha256=9Rq9fz1RqFIthmo1E79lCRN-djiC8qPtBDzuQ5F0vzk,67726
+fairvis/data/assessments/Elias2025_glimepiride.xlsx,sha256=8ghUfq29mvFjoqoPKM_td9I3GuzwgPnHLn25NRNU1EU,67724
+fairvis/data/assessments/Nemitz2026_dapagliflozin.xlsx,sha256=2cawChl4OOQ7Q-uKPGrJ4Vvnjna62pYRXz64rKefr_Y,67191
+fairvis/data/assessments/PMR_curated.xlsx,sha256=jv5nNGNwMw1Ygyja-WoNRDSfvs9tGcRG0vxMBWOrel0,18063
+fairvis/data/assessments/PMR_non_curated.xlsx,sha256=AVRNTnu6-kVkNEYZ2EjRaY3d2PXnuRa5KEk5RSRd_LU,18385
+fairvis/data/assessments/Tensil2026_losartan.xlsx,sha256=XqXSsu4lOZp2LvrPQOD6jxMQBXJHcFhHEC7iqF6RCHw,67724
+fairvis/data/assessments/Tereshchuk2026_canagliflozin.xlsx,sha256=oaHDUthxVrrsFP4jubURX2-8ytiLnJQzWjwaAvw7ukY,67728
+fair_ca_visualization-0.4.0.dist-info/METADATA,sha256=i5sRmKRKPi06te8EhL8OuGoVWrwC-BBUFYPtEzKBTNA,5673
+fair_ca_visualization-0.4.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+fair_ca_visualization-0.4.0.dist-info/entry_points.txt,sha256=TGDUiYZ6BRCWrAu3umTEc4QuVQzNLyxYxKUBdoBv3eg,45
+fair_ca_visualization-0.4.0.dist-info/licenses/LICENSE,sha256=-nDb-yPz_IzNCxwvh--aoEgFTIBZBpvjwVSsxPAgRUM,1064
+fair_ca_visualization-0.4.0.dist-info/RECORD,,

fair_ca_visualization-0.4.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

fair_ca_visualization-0.4.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+fairvis = fairvis.cli:main

fair_ca_visualization-0.4.0.dist-info/licenses/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) 2025-2026 Matthias König
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

fairvis/__init__.py

@@ -0,0 +1,4 @@
+"""fairvis: interactive visualization of the FAIR COMBINE Archive Indicators."""
+
+__author__ = "Matthias König"
+__version__ = "0.4.0"

fairvis/__main__.py

@@ -0,0 +1,6 @@
+"""Start the app with `python -m fairvis`."""
+
+from fairvis.cli import main
+
+if __name__ == "__main__":
+    main()

fairvis/app.py

@@ -0,0 +1,208 @@
+"""Streamlit app of the FAIR COMBINE Archive Indicators.
+
+Run with `fairvis`, or from a checkout with `streamlit run src/fairvis/app.py`.
+"""
+
+import pandas as pd
+import streamlit as st
+
+from fairvis.data_io import load_assessment, load_indicators, load_model_assessments
+from fairvis.settings import TEMPLATE_PATH
+from fairvis.visualization import visualize_barplot, visualize_polar_barplots
+
+st.set_page_config(
+    page_title="FAIR-CA-Indicators",
+    page_icon="🧊",
+    layout="wide",
+    menu_items={
+        "Get help": "mailto:konigmatt@googlemail.com",
+        "Report a bug": "https://github.com/matthiaskoenig/fair-ca-visualization/issues/new",
+        "About": """
+        FAIR-CA-Indicators application.
+        """,
+    },
+)
+st.markdown(
+    """
+        <style>
+               .block-container {
+                    padding-top: 2rem;
+                    padding-bottom: 1rem;
+                    padding-left: 5rem;
+                    padding-right: 5rem;
+                }
+        </style>
+        """,
+    unsafe_allow_html=True,
+)
+
+
+@st.cache_data
+def load_data() -> tuple[pd.DataFrame, dict[str, pd.DataFrame]]:
+    """Load the indicators and the example assessments.
+
+    Returns:
+        indicators with the counts of their assessments, and the assessments by
+        model id.
+    """
+    df_models = load_model_assessments()
+    df_indicators = load_indicators(df_models=df_models)
+
+    return df_indicators, df_models
+
+
+df_indicators, models = load_data()
+
+
+# --- Main ----------------------------------------------------------------------------
+st.markdown(
+    """
+    # Visualize FAIR COMBINE Archive Indicators
+    """
+)
+tab_about, tab_assessment, tab_models, tab_indicators = st.tabs(
+    [
+        "About",
+        "Assess Model",
+        "Example Assessments",
+        "Indicators",
+    ]
+)
+
+with tab_about:
+    st.markdown(
+        """
+        ## Motivation
+        Computational models are essential tools for studying complex biological systems. In biomedical and clinical contexts in particular, models must be transparent, well-documented, and **reproducible** to ensure reliability and reuse.
+
+        A community-driven approach to improving transparency and communication of model characteristics is the adoption of the **FAIR principles**: *Findability, Accessibility, Interoperability, and Reusability*. Building on the FAIR indicators developed by the **Research Data Alliance (RDA)**, we propose an adaptation specifically designed for computational models encoded in domain standards developed within the **[COMBINE](https://co.mbine.org)** community.
+
+        The **FAIR COMBINE Archive Indicators** enable systematic assessment of the FAIRness of models packaged as COMBINE archives and support improved documentation, sharing, and reuse of computational models in the life sciences. More information is available from:
+
+        >*Balaur I., Nickerson D.P., Welter D., Wodke J.A.H., Ancien F., Gebhardt T., Grouès V., Hermjakob H., König M., Radde N., Rougny A., Schneider R., Malik-Sheriff R.S., Shiferaw K.B., Stefan M., Satagopam V., Waltemath D. (2025).*
+        >**FAIRification of computational models in biology.**
+        >bioRxiv 2025.03.21.644517 (preprint). doi: [10.1101/2025.03.21.644517](https://doi.org/10.1101/2025.03.21.644517)
+
+        ## Usage
+        This webpage provides an interactive visualization of the **FAIR COMBINE Archive Indicators**,
+
+        - Use the **Assess Model** tab to assess your own model (a template for the indicators is provided).
+        - Use the **Example Assessments** tab to explore FAIR indicator assessments for example models.
+        - Use the **Indicators** tab to browse the individual FAIR indicators.
+
+        ## How to cite the visualization tool
+        [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13755820.svg)](https://doi.org/10.5281/zenodo.13755820)
+
+        ## Funding
+        Matthias König was supported by the **German Federal Ministry of Education and Research (BMBF)** within the ATLAS project (grant number 031L0304B) and by the **German Research Foundation (DFG)** within the Research Unit Program **FOR 5151 QuaLiPerF** (grant number 436883643) and the **Priority Programme SPP 2311 (Subproject SimLivA)** (grant number 465194077).
+
+        ## Example visualization
+        The example visualization demonstrates the **Model** and **Model Metadata** FAIR indicators using the *BioModels_C19_curated* example.
+        """
+    )
+    figs_example = visualize_polar_barplots(df_data=models["BioModels_C19_curated"])
+    col1a, col2a = st.columns(2)
+    with col1a:
+        st.plotly_chart(figs_example[0], key="pchart_example1")
+    with col2a:
+        st.plotly_chart(figs_example[1], key="pchart_example2")
+
+
+with tab_indicators:
+    st.dataframe(
+        data=df_indicators,
+        width="stretch",
+        column_config={
+            "Assessment": st.column_config.BarChartColumn(
+                "FAIR Assessment",
+                help="Assessment of all models (NA, 0.0, 0.5, 1.0)",
+            ),
+        },
+    )
+
+
+with tab_models:
+    col_select, col_fair, _ = st.columns(3)
+    with col_select:
+        model_id = st.selectbox(
+            "Select model",
+            index=0,
+            options=list(models.keys()),
+        )
+        df_model = models[model_id]
+
+    with col_fair:
+        fig_bar = visualize_barplot(df_data=df_model)
+        st.plotly_chart(fig_bar, width="content", key="pchart_models_bar1")
+
+    # plotly plot
+    figs = visualize_polar_barplots(df_data=df_model)
+    col1, col2 = st.columns(2)
+    with col1:
+        st.plotly_chart(figs[0], key="pchart_models_col1")
+    with col2:
+        st.plotly_chart(figs[1], key="pchart_models_col2")
+    col3, col4 = st.columns(2)
+    with col3:
+        st.plotly_chart(figs[2], key="pchart_models_col3")
+    with col4:
+        st.plotly_chart(figs[3], key="pchart_models_col4")
+
+    # show dataframe
+    st.dataframe(df_model, width="stretch")
+
+with tab_assessment:
+    col_upload, col_template, col_fair_upload = st.columns(3, gap="medium")
+    with col_upload:
+        uploaded_xlsx = st.file_uploader(
+            "Upload FAIR model assessment",
+            type="xlsx",
+            accept_multiple_files=False,
+        )
+        df_model_upload: pd.DataFrame | None = None
+        if uploaded_xlsx is not None:
+            try:
+                df_model_upload = load_assessment(uploaded_xlsx)
+            except ValueError as err:
+                st.error(f"The uploaded file is no valid FAIR assessment: {err}")
+
+    with col_template:
+        st.html(
+            """
+            The template for assessment is available here:
+            """
+        )
+        st.download_button(
+            "Download FAIR Template",
+            TEMPLATE_PATH.read_bytes(),
+            file_name="FAIR_assessment_template.xlsx",
+            help="FAIR assessment template. Fill out and reupload for evaluation.",
+        )
+    with col_fair_upload:
+        if df_model_upload is not None:
+            fig_bar = visualize_barplot(df_data=df_model_upload)
+            st.plotly_chart(fig_bar, width="content")
+
+    if df_model_upload is not None:
+        # plotly plot
+        figs = visualize_polar_barplots(df_data=df_model_upload)
+        col1, col2 = st.columns(2)
+        with col1:
+            st.plotly_chart(figs[0], key="pchart_assessment_col1")
+        with col2:
+            st.plotly_chart(figs[1], key="pchart_assessment_col2")
+        col3, col4 = st.columns(2)
+        with col3:
+            st.plotly_chart(figs[2], key="pchart_assessment_col3")
+        with col4:
+            st.plotly_chart(figs[3], key="pchart_assessment_col4")
+
+        # show dataframe
+        st.dataframe(df_model_upload, width="stretch")
+
+st.divider()
+st.markdown(
+    """
+    © 2024-2026 [Matthias König](https://livermetabolism.com) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.13755820.svg)](https://doi.org/10.5281/zenodo.13755820)
+    """
+)

fairvis/cli.py

@@ -0,0 +1,46 @@
+"""Console script `fairvis`, starts the app with streamlit.
+
+The options of `.streamlit/config.toml` of the repository are not read when the
+app runs from an installed package, so they are passed on the command line.
+Further arguments are passed to `streamlit run`, e.g. `fairvis --server.port 8502`.
+"""
+
+import io
+import sys
+
+from streamlit.web import cli as stcli
+
+from fairvis.settings import APP_PATH
+
+STREAMLIT_OPTIONS: tuple[str, ...] = (
+    "--browser.gatherUsageStats=false",
+    "--theme.base=light",
+)
+"""Default options of `streamlit run`, the same as in `.streamlit/config.toml`."""
+
+
+def streamlit_argv(args: list[str]) -> list[str]:
+    """Command line of `streamlit run` for the app.
+
+    Args:
+        args: further arguments for `streamlit run`; they follow the defaults,
+            so they override them.
+
+    Returns:
+        the arguments, starting with the program name `streamlit`.
+    """
+    return ["streamlit", "run", str(APP_PATH), *STREAMLIT_OPTIONS, *args]
+
+
+def main() -> None:
+    """Start the FAIR-CA visualization app.
+
+    The output is written as UTF-8: the messages of streamlit contain non ascii
+    characters, which the ansi code page of a redirected stdout on windows, e.g.
+    cp1252, cannot encode (UTF-8 is the default from python 3.15 on, PEP 686).
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if isinstance(stream, io.TextIOWrapper):
+            stream.reconfigure(encoding="utf-8")
+    sys.argv = streamlit_argv(sys.argv[1:])
+    sys.exit(stcli.main())

fairvis/console.py

@@ -0,0 +1,17 @@
+"""Rich console for logging."""
+
+from rich import pretty
+from rich.console import Console
+from rich.theme import Theme
+
+pretty.install()
+custom_theme = Theme(
+    {
+        "success": "green",
+        "info": "blue",
+        "warning": "orange3",
+        "error": "red",
+    }
+)
+
+console = Console(record=True, theme=custom_theme)

fairvis/data_io.py

@@ -0,0 +1,163 @@
+"""Loading and validation of FAIR assessments and the indicators."""
+
+from numbers import Real
+from pathlib import Path
+from typing import BinaryIO
+
+import numpy as np
+import pandas as pd
+
+from fairvis.console import console
+from fairvis.settings import ASSESSMENTS_PATH, TEMPLATE_PATH
+
+REQUIRED_COLUMNS: tuple[str, ...] = (
+    "ID",
+    "Short",
+    "Type",
+    "Category",
+    "Priority",
+    "Indicator",
+    "Description",
+    "Assessment details",
+    "Assessment",
+)
+"""Columns of the template an assessment needs."""
+
+ASSESSMENT_VALUES: tuple[float, ...] = (0.0, 0.5, 1.0)
+"""Allowed assessment values besides NA (not applicable, an empty cell)."""
+
+
+def assessment_class(value: object) -> int:
+    """Class of an assessment value.
+
+    Args:
+        value: assessment of an indicator, NaN for NA.
+
+    Returns:
+        0 for NA, 1 for 0.0, 2 for 0.5 and 3 for 1.0.
+
+    Raises:
+        ValueError: if the value is none of NA, 0, 0.5 and 1.
+    """
+    if isinstance(value, Real) and not isinstance(value, bool):
+        number = float(value)
+        if np.isnan(number):
+            return 0
+        for k, reference in enumerate(ASSESSMENT_VALUES, start=1):
+            if np.isclose(number, reference):
+                return k
+    if isinstance(value, str) and _is_number(value):
+        raise ValueError(
+            f"assessment value {value!r} is stored as text, enter it as a number"
+        )
+    raise ValueError(f"assessment value {value!r} is none of NA, 0, 0.5, 1")
+
+
+def _is_number(text: str) -> bool:
+    try:
+        float(text)
+    except ValueError:
+        return False
+    return True
+
+
+def validate_assessment(df: pd.DataFrame) -> None:
+    """Validate the structure and the values of a raw assessment.
+
+    Args:
+        df: assessment as read from the xlsx file, before the `ID` index is set.
+
+    Raises:
+        ValueError: if a column of the template is missing or an assessment value
+            is none of NA, 0, 0.5 and 1.
+    """
+    missing = [column for column in REQUIRED_COLUMNS if column not in df.columns]
+    if missing:
+        raise ValueError(
+            f"The assessment misses the columns {', '.join(missing)}. "
+            "Fill out the FAIR assessment template."
+        )
+    for indicator_id, value in zip(df["ID"], df["Assessment"], strict=True):
+        try:
+            assessment_class(value)
+        except ValueError as err:
+            raise ValueError(f"Indicator '{indicator_id}': {err}.") from err
+
+
+def load_assessment(source: Path | BinaryIO) -> pd.DataFrame:
+    """Load an assessment from an xlsx file.
+
+    Args:
+        source: path of the xlsx file or an uploaded file.
+
+    Returns:
+        assessment indexed by the indicator `ID`, without the description columns
+        and without columns lacking a header (named `Unnamed: <n>` by pandas).
+
+    Raises:
+        ValueError: if the file is no readable xlsx file or no valid assessment.
+    """
+    try:
+        df = pd.read_excel(source, sheet_name=0)
+    except Exception as err:
+        raise ValueError(f"The file is no readable xlsx file: {err}") from err
+    validate_assessment(df)
+    unnamed = [column for column in df.columns if str(column).startswith("Unnamed")]
+    return df.set_index("ID").drop(
+        columns=["Description", "Assessment details", *unnamed]
+    )
+
+
+def load_model_assessments(
+    assessment_dir: Path = ASSESSMENTS_PATH,
+) -> dict[str, pd.DataFrame]:
+    """Load all model assessments of a directory.
+
+    Args:
+        assessment_dir: directory with one xlsx file per model.
+
+    Returns:
+        assessments by model id (the file name without suffix), sorted by model id.
+    """
+    return {
+        path.stem: load_assessment(path)
+        for path in sorted(assessment_dir.glob("*.xlsx"))
+    }
+
+
+def load_indicators(df_models: dict[str, pd.DataFrame]) -> pd.DataFrame:
+    """Load the indicators and count their assessments over all models.
+
+    Args:
+        df_models: assessments by model id, see `load_model_assessments`.
+
+    Returns:
+        indicators indexed by `ID`; the column `Assessment` holds the number of
+        models with NA, 0, 0.5 and 1 for the indicator.
+
+    Raises:
+        ValueError: if an assessment has other indicators than the template.
+    """
+    df_indicators = (
+        pd.read_excel(TEMPLATE_PATH, sheet_name=0)
+        .set_index("ID")
+        .drop(columns=["Description", "Assessment details", "Assessment", "Comment"])
+    )
+    assessments = [[0.0, 0.0, 0.0, 0.0] for _ in range(len(df_indicators))]
+    for model_id, df_model in df_models.items():
+        if not df_model.index.sort_values().equals(df_indicators.index.sort_values()):
+            raise ValueError(
+                f"The assessment '{model_id}' has other indicators than the template."
+            )
+        values = df_model["Assessment"].reindex(df_indicators.index).to_numpy()
+        for k, value in enumerate(values):
+            assessments[k][assessment_class(value)] += 1.0
+
+    df_indicators["Assessment"] = assessments
+    return df_indicators
+
+
+if __name__ == "__main__":
+    df_indicators = load_indicators(load_model_assessments())
+    console.rule("Indicators", align="left", style="red")
+    console.print(df_indicators)

fairvis/example.py

@@ -0,0 +1,10 @@
+"""Example showing the figures of a bundled assessment in the browser."""
+
+from fairvis.data_io import load_assessment
+from fairvis.settings import ASSESSMENTS_PATH
+from fairvis.visualization import visualize_barplot, visualize_polar_barplots
+
+if __name__ == "__main__":
+    df = load_assessment(ASSESSMENTS_PATH / "BioModels_curated.xlsx")
+    visualize_barplot(df).show()
+    visualize_polar_barplots(df)[0].show()

fairvis/settings.py

@@ -0,0 +1,18 @@
+"""Paths of the app and of the data bundled with the package."""
+
+from pathlib import Path
+
+PACKAGE_PATH: Path = Path(__file__).parent
+"""Directory of the installed `fairvis` package."""
+
+APP_PATH: Path = PACKAGE_PATH / "app.py"
+"""Streamlit script of the app."""
+
+DATA_PATH: Path = PACKAGE_PATH / "data"
+"""Data bundled with the package."""
+
+ASSESSMENTS_PATH: Path = DATA_PATH / "assessments"
+"""Example assessments, one xlsx file per model."""
+
+TEMPLATE_PATH: Path = DATA_PATH / "FAIR_assessment_template.xlsx"
+"""Template of a FAIR assessment, also the definition of the indicators."""

fairvis/visualization.py

@@ -0,0 +1,109 @@
+"""Plotly figures of a FAIR assessment."""
+
+import numpy as np
+import pandas as pd
+import plotly.express as px
+import plotly.graph_objects as go
+
+SUBSET_KEYS: tuple[str, ...] = (
+    "Model",
+    "Model metadata",
+    "Archive",
+    "Archive metadata",
+)
+"""Types of indicators, one polar figure each."""
+
+COLOR_DISCRETE_SEQUENCE: tuple[str, ...] = (
+    "#1f77b4",  # muted blue
+    "#ff7f0e",  # safety orange
+    "#2ca02c",  # cooked asparagus green
+    "#d62728",  # brick red
+    "#9467bd",  # muted purple
+    "#8c564b",  # chestnut brown
+    "#e377c2",  # raspberry yogurt pink
+    "#7f7f7f",  # middle gray
+    "#bcbd22",  # curry yellow-green
+    "#17becf",  # blue-teal
+)
+"""Colors of the categories."""
+
+
+def visualize_barplot(df_data: pd.DataFrame) -> go.Figure:
+    """Bar plot of the fraction of the indicators fulfilled per category.
+
+    Args:
+        df_data: assessment of a model, see `fairvis.data_io.load_assessment`.
+
+    Returns:
+        bar plot with the FAIR percentage per category.
+    """
+    # Count the fraction of indicators fullfilled per category
+    categories = df_data["Category"].unique()
+
+    values = dict.fromkeys(categories, 0.0)
+    totals = dict.fromkeys(categories, 0.0)
+    for _, row in df_data.iterrows():
+        category = row["Category"]
+        assessment = row["Assessment"]
+        totals[category] += 1.0
+        if not np.isnan(assessment):
+            values[category] += assessment
+
+    items = []
+    for category in categories:
+        items.append(
+            {
+                "category": category,
+                "value": values[category],
+                "total": totals[category],
+                "percentage": 100 * values[category] / totals[category],
+            }
+        )
+
+    df = pd.DataFrame(items)
+
+    # barplot
+    fig = px.bar(
+        df,
+        x="category",
+        y="percentage",
+        color="category",  # title="FAIR assessment",
+        color_discrete_sequence=list(COLOR_DISCRETE_SEQUENCE),
+        labels={"category": "Category", "percentage": "FAIR [%]"},
+    )
+    fig.update_layout(
+        title="FAIR assessment",
+        yaxis_range=[0, 100],
+        showlegend=False,
+        height=250,
+    )
+
+    return fig
+
+
+def visualize_polar_barplots(df_data: pd.DataFrame) -> list[go.Figure]:
+    """Polar bar plots of the indicators of a model, one per type of indicator.
+
+    Args:
+        df_data: assessment of a model, see `fairvis.data_io.load_assessment`.
+
+    Returns:
+        one polar bar plot per entry of `SUBSET_KEYS`, in that order.
+    """
+    figs = []
+    for key in SUBSET_KEYS:
+        df = df_data[df_data["Type"] == key]
+        fig = px.bar_polar(
+            df,
+            r="Assessment",
+            theta="Short",
+            color="Category",
+            hover_name="Indicator",
+            hover_data=["Indicator", "Category", "Priority"],
+            color_discrete_sequence=list(COLOR_DISCRETE_SEQUENCE),
+        )
+        fig.update_layout(title=key, showlegend=True)
+        fig.update_polars(radialaxis_tickvals=[0, 0.5, 1], angularaxis_showgrid=True)
+        figs.append(fig)
+
+    return figs