BiSO#

Class to generate a BISO report.

By default the report contains the following visualizations:

  • AnrProjects

  • Chapters

  • CollaborationMap: name = “world”, countries_to_ignore = [“France”]

  • CollaborationMap: name = “europe”, resolution = 50, map_zoom = True

  • CollaborationNames

  • Conferences

  • EuropeanProjects

  • Journals

  • OpenAccessWorks

  • WorksType

This comes from the default value of default_visualizations :

default_visualizations =  {
    "AnrProjects": [{}],
    "Chapters": [{}],
    "CollaborationMap": [
        {
            "name": "world",
            "countries_to_ignore": ["France"],
            "stats_to_save": {
                "collaborations_nb": "collaborationsnb",
                "institutions_nb": "institutionsnb",
                "countries_nb": "countriesnb"
            }
        },
        { "name": "europe", "resolution": 50, "map_zoom": True }
    ],
    "CollaborationNames": [
        {
            "countries_to_exclude": ["fr"]
        }
    ],
    "Conferences": [{}],
    "EuropeanProjects": [{}],
    "Journals": [],
    "OpenAccessWorks": [{}],
    "WorksType": [{}],
}

When needing statistics values to be printed in the report, you can export variables with the argument stats_to_save. You need to provide a dictionary with the keys being the name of the variables returned by the plotting library and the values being the name of the variable in the report (aka the name of the macro in the LaTeX report). In the above example, collaborations_nb is the key of the variable in the dictionary returned by the plotting library and and collaborationsnb is the name of the LaTeX macro containing the value of the variable for the report, callable with \collaborationsnb. The plotting library needs to return those variables in a dictionary returned by the method fetch_data().

The BiSO Class#

class dibisoreporting.biso.Biso(entity_id, year: int | None = None, lab_acronym: str = '', lab_full_name: str = '', latex_main_file_path: str | None = None, latex_main_file_url: str | None = None, latex_template_path: str | None = None, latex_template_url: str | None = None, max_entities: int | None = 1000, max_plotted_entities: int = 25, root_path: str | None = None, watermark_text: str = '')#

Bases: DibisoReporting

Class to generate the BiSO report

Variables:

  • class_mapping – Dictionary that maps class names to actual classes

  • default_plot_main_color – Default color for the main plot ()

  • default_visualizations – Dictionary contains each type of plot to include in the report with the parameters of each plot.

__init__(entity_id, year: int | None = None, lab_acronym: str = '', lab_full_name: str = '', latex_main_file_path: str | None = None, latex_main_file_url: str | None = None, latex_template_path: str | None = None, latex_template_url: str | None = None, max_entities: int | None = 1000, max_plotted_entities: int = 25, root_path: str | None = None, watermark_text: str = '')#

Initialize the Biso class with the given parameters.

Parameters:

  • entity_id (str) – The HAL collection identifier. This usually refers to the lab acronym.

  • year (int | None, optional) – The year for which to fetch data. If None, uses the current year.

  • lab_acronym (str) – The full acronym of the lab. Default to entity_id.

  • lab_full_name (str) – The full name of the lab.

  • latex_main_file_path (str | None, optional) – Path to a single LaTeX main file. This file is the one to use to compile the report. It will copy the main file to root_path. Default to None. If None, doesn’t try getting the main file from the path. If both latex_main_file_path and latex_main_file_url are not None, the library will first try to get the main file from the path.

  • latex_main_file_url (str | None, optional) – URL to download a single LaTeX main file. It will download the file directly to root_path. Default to None. If None, doesn’t try getting the main file from the URL.

  • latex_template_path (str | None, optional) – Path to the LaTeX template files. It will copy the templates files to root_path. Default to None. If None, doesn’t try getting the template from the path. If both latex_template_path and latex_template_url are not None, the library will first try to get the template from the path.

  • latex_template_url (str | None, optional) – URL to a GitHub repository containing the template. It will get the latest repository release and extract it to get the template files. Default to None. If None, doesn’t try getting the template from the URL.

  • max_entities (int | None, optional) – Default maximum number of entities used to create the plot. Default 1000. Set to None to disable the limit. This value limits the number of queried entities when doing analysis. For example, when creating the collaboration map, it limits the number of works to query from HAL to extract the collaborating institutions from.

  • max_plotted_entities (int, optional) – Maximum number of bars in the plot or rows in the table. Default to 25.

  • root_path (str) – Path to the root directory where the report and figures will be generated.

  • watermark_text (str) – The text to be used as a watermark in the report. Default to “” (no watermark).

add_marco(name, value)#
create_default_latexmkrc_file()#

Create the default latexmkrc file in the root path of the project.

default_latexmkrc_file_content = "$pdflatex = 'lualatex %O %S --shell-escape';\n$pdf_mode = 1;\n$postscript_mode = $dvi_mode = 0;\n"#
default_plot_main_color = '#004e7d'#
default_visualizations = {'AnrProjects': [{}], 'Chapters': [{}], 'CollaborationMap': [{'countries_to_ignore': ['France'], 'name': 'world', 'stats_to_save': {'collaborations_nb': 'collaborationsnb', 'countries_nb': 'countriesnb', 'institutions_nb': 'institutionsnb'}}, {'map_zoom': True, 'name': 'europe', 'resolution': 50}], 'CollaborationNames': [{'countries_to_exclude': ['fr']}], 'Conferences': [{}], 'EuropeanProjects': [{}], 'Journals': [], 'OpenAccessWorks': [{'stats_to_save': {'oa_works_period': 'oaworksperiod'}}], 'WorksType': [{}]}#
figures_dir_name = 'figures'#
generate_report(visualizations_to_make: dict[str, list[dict]] | None = None, import_default_visualizations=True)#

Generate the report by calling the specified functions with their parameters to create the desired visualizations. To select which visualization to make and configure them, you can use visualizations_to_make as follows:

visualizations_to_make = {
    "AnrProjects": [
        { "name": "anr1", "param1": "value1", "param2": "value2" },
        { "name": "anr2", "param1": "value3", "param2": "value4" }
    ],
    "Chapters": [
        { "name": "chapter1", "param1": "value1", "param2": "value2" }
    ],
    "CollaborationMap": [
        { "name": "collab1", "max_entities": 1000, "resolution": 50, "map_zoom": True },
        { "name": "collab2", "max_entities": 500, "resolution": 100, "map_zoom": False }
    ],
    "CollaborationNames": [
        {}
    ],
    "Conferences": []
}
This example, will create:

  • 2 AnrProjects visualizations (with the parameters defined in the dictionaries)

  • 1 Chapters visualization

  • 2 CollaborationMaps visualizations

  • 1 Conferences CollaborationNames (with the default parameters as there is one empty dictionary)

  • 0 Conferences visualizations (as the list is empty)

Parameters:

  • visualizations_to_make (list[dict[str, Any]]) – A dictionary specifying which visualizations to make and their parameters.

  • import_default_visualizations (bool) – Whether to import default visualizations settings. Defaults to True. To not generate a plot, set its dictionary in import_default_visualizations to an empty list. Example: If you don’t want to generate the Conferences visualization, you can set import_default_visualizations as follows: import_default_visualizations = {"Conferences": []}.

get_file_from_path(file_path, file_type)#

If file_path is not None, get the file from a local path. It copies the file from the specified path to the root path of the project. Checks the file type based on its extension and rename latexmkrc files.

Parameters:

  • file_path (str) – The path to the file.

  • file_type (str) – The file type (“main_tex” or “latexmkrc”).

Returns:

The path to the LaTeX main file.

get_file_from_url(file_url, file_type)#

If file_url is not None, get the file from a URL. It downloads the file from the specified URL to the root path of the project. Checks the file type based on its extension and rename latexmkrc files.

Parameters:

  • file_url (str) – The URL of the file.

  • file_type (str) – The file type (“main_tex” or “latexmkrc”).

Returns:

The path to the LaTeX main file.

get_latex_template_from_github()#

Get the LaTeX template either from a GitHub repository release. It saves the template in the root path of the project.

get_latex_template_from_path()#

Get the LaTeX template from a local path. It copies the template files from the specified path to the root path of the project.