.. DO NOT EDIT.
.. THIS FILE WAS AUTOMATICALLY GENERATED BY SPHINX-GALLERY.
.. TO MAKE CHANGES, EDIT THE SOURCE PYTHON FILE:
.. "examples/disciplines/variables/plot_variable_renaming.py"
.. LINE NUMBERS ARE GIVEN BELOW.

.. only:: html

    .. note::
        :class: sphx-glr-download-link-note

        :ref:`Go to the end <sphx_glr_download_examples_disciplines_variables_plot_variable_renaming.py>`
        to download the full example code.

.. rst-class:: sphx-glr-example-title

.. _sphx_glr_examples_disciplines_variables_plot_variable_renaming.py:


Renaming variables
==================

.. GENERATED FROM PYTHON SOURCE LINES 20-30

.. code-block:: Python


    from __future__ import annotations

    from numpy import array

    from gemseo.disciplines.analytic import AnalyticDiscipline
    from gemseo.utils.discipline import VariableRenamer
    from gemseo.utils.discipline import VariableTranslation
    from gemseo.utils.discipline import rename_discipline_variables








.. GENERATED FROM PYTHON SOURCE LINES 31-53

In the context of a multidisciplinary study,
the disciplines must use a common naming convention
so that GEMSEO can automatically connect them.

Unfortunately,
model suppliers sometimes use different conventions.
For example,
the output of one model and the input of another model
represent the same parameter in the study.

The :mod:`gemseo.utils.discipline` module includes capabilities
enabling these models to be connected automatically using a set of translations.

Renaming discipline variables from translators
----------------------------------------------
:func:`.rename_discipline_variables` is a function
to rename some discipline variables from a dictionary of translators
of the form ``{discipline_name: {variable_name: new_variable_name}}``.
For example,
let us consider four analytic disciplines.
There is the first discipline, named ``"A"``,
for which we would like to rename ``"a"`` to ``"x"`` and ``"c"`` to ``"z"``:

.. GENERATED FROM PYTHON SOURCE LINES 53-54

.. code-block:: Python

    disciplines = [AnalyticDiscipline({"c": "2*a"}, name="A")]







.. GENERATED FROM PYTHON SOURCE LINES 55-56

the second discipline, named ``"C"``, to be used as is:

.. GENERATED FROM PYTHON SOURCE LINES 56-57

.. code-block:: Python

    disciplines.append(AnalyticDiscipline({"t": "3*g"}, name="C"))







.. GENERATED FROM PYTHON SOURCE LINES 58-61

the third disciplines, also named ``"A"``,
for which we would like to rename ``"a"`` to ``"x"`` and ``"c"`` to ``"z"``
(as said above):

.. GENERATED FROM PYTHON SOURCE LINES 61-62

.. code-block:: Python

    disciplines.append(AnalyticDiscipline({"c": "4*a"}, name="A"))







.. GENERATED FROM PYTHON SOURCE LINES 63-65

and the last one, named ``"B"``,
for which we would like to rename ``"b"`` to ``"y"``:

.. GENERATED FROM PYTHON SOURCE LINES 65-66

.. code-block:: Python

    disciplines.append(AnalyticDiscipline({"b": "5*j"}, name="B"))







.. GENERATED FROM PYTHON SOURCE LINES 67-69

The following nested dictionary indexed by the discipline names
defines the translators:

.. GENERATED FROM PYTHON SOURCE LINES 69-70

.. code-block:: Python

    translators = {"A": {"a": "x", "c": "z"}, "B": {"b": "y"}}







.. GENERATED FROM PYTHON SOURCE LINES 71-73

Finally,
we can rename the input and output variables of the disciplines:

.. GENERATED FROM PYTHON SOURCE LINES 73-74

.. code-block:: Python

    rename_discipline_variables(disciplines, translators)







.. GENERATED FROM PYTHON SOURCE LINES 75-76

and verify that the renaming has been done correctly:

.. GENERATED FROM PYTHON SOURCE LINES 76-81

.. code-block:: Python

    disc_a, disc_c, other_disc_a, disc_b = disciplines
    assert disc_a.execute({"x": array([3.0])})["z"] == array([6.0])
    assert disc_c.execute({"g": array([3.0])})["t"] == array([9.0])
    assert other_disc_a.execute({"x": array([3.0])})["z"] == array([12.0])
    assert disc_b.execute({"j": array([3.0])})["y"] == array([15.0])







.. GENERATED FROM PYTHON SOURCE LINES 82-95

.. tip::

   Creating the nested dictionary ``translators`` can be a pain
   when there is a lot of disciplines and a lot of variables to rename.
   The following sections present some tools to facilitate its creation.

Create translators easily
-------------------------
Variable translation
~~~~~~~~~~~~~~~~~~~~
First,
we need to introduce the notion of :class:`.VariableTranslation`
to translate a discipline variable name according to a global taxonomy:

.. GENERATED FROM PYTHON SOURCE LINES 95-100

.. code-block:: Python

    variable_translation = VariableTranslation(
        discipline_name="A", variable_name="a", new_variable_name="x"
    )
    variable_translation





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    'A'.'a'='x'



.. GENERATED FROM PYTHON SOURCE LINES 101-107

Variable renamer
~~~~~~~~~~~~~~~~
Then,
we can create a :class:`.VariableRenamer` from a set of translations
that can include both :class:`.VariableTranslation` instances
and tuples of the form ``(discipline_name, variable_name, new_variable_name)``:

.. GENERATED FROM PYTHON SOURCE LINES 107-114

.. code-block:: Python

    renamer = VariableRenamer.from_translations(
        variable_translation,
        ("B", "b", "y"),
        VariableTranslation(discipline_name="A", variable_name="c", new_variable_name="z"),
    )
    renamer






.. raw:: html

    <div class="output_subarea output_html rendered_html output_result">
    <div style='margin: 1em;'><table>
        <thead>
            <tr>
                <th>Discipline name</th>
                <th>Variable name</th>
                <th>New variable name</th>
            </tr>
        </thead>
        <tbody>
            <tr>
                <td>A</td>
                <td>a</td>
                <td>x</td>
            </tr>
            <tr>
                <td>B</td>
                <td>b</td>
                <td>y</td>
            </tr>
            <tr>
                <td>A</td>
                <td>c</td>
                <td>z</td>
            </tr>
        </tbody>
    </table></div>
    </div>
    <br />
    <br />

.. GENERATED FROM PYTHON SOURCE LINES 115-118

This object offers a :attr:`.translators` property
mapping from discipline names to dictionaries,
themselves mapping from the discipline variable names to the global variable names:

.. GENERATED FROM PYTHON SOURCE LINES 118-120

.. code-block:: Python

    renamer.translators





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    defaultdict(<class 'dict'>, {'A': {'a': 'x', 'c': 'z'}, 'B': {'b': 'y'}})



.. GENERATED FROM PYTHON SOURCE LINES 121-125

You can use these translators to rename the corresponding discipline variables,
by calling the :func:`.rename_discipline_variables` function
presented in the first section:
``rename_discipline_variables(disciplines, renamer.translators)``.

.. GENERATED FROM PYTHON SOURCE LINES 127-128

You can also access the :attr:`.translations`:

.. GENERATED FROM PYTHON SOURCE LINES 128-130

.. code-block:: Python

    renamer.translations





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ('A'.'a'='x', 'B'.'b'='y', 'A'.'c'='z')



.. GENERATED FROM PYTHON SOURCE LINES 131-140

Add translations
~~~~~~~~~~~~~~~~
Finally,
you can add translations to a :class:`.VariableRenamer`.

One by one
..........
You can add them one by one
using its :meth:`~.VariableRenamer.add_translation` method:

.. GENERATED FROM PYTHON SOURCE LINES 140-145

.. code-block:: Python

    renamer.add_translation(
        VariableTranslation(discipline_name="Y", variable_name="x", new_variable_name="b")
    )
    renamer.translations





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ('A'.'a'='x', 'B'.'b'='y', 'A'.'c'='z', 'Y'.'x'='b')



.. GENERATED FROM PYTHON SOURCE LINES 146-152

By discipline
.............
You can add several translations associated with the same discipline
using its :meth:`~.VariableRenamer.add_translations_by_discipline` method
from a discipline name
and a dictionary of the form ``{variable_name: new_variable_name}``:

.. GENERATED FROM PYTHON SOURCE LINES 152-155

.. code-block:: Python

    renamer.add_translations_by_discipline("T", {"x": "e", "o": "p"})
    renamer.translations





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ('A'.'a'='x', 'B'.'b'='y', 'A'.'c'='z', 'Y'.'x'='b', 'T'.'x'='e', 'T'.'o'='p')



.. GENERATED FROM PYTHON SOURCE LINES 156-163

By variable
...........
You add several translations,
indicating which variables in which disciplines are to be renamed in the same way,
using its :meth:`~.VariableRenamer.add_translations_by_variable` method
from a new variable name
and a dictionary of the form ``{discipline_name: variable_name}``:

.. GENERATED FROM PYTHON SOURCE LINES 163-166

.. code-block:: Python

    renamer.add_translations_by_discipline("i", {"A": "r", "B": "m"})
    renamer.translations





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    ('A'.'a'='x', 'B'.'b'='y', 'A'.'c'='z', 'Y'.'x'='b', 'T'.'x'='e', 'T'.'o'='p', 'i'.'A'='r', 'i'.'B'='m')



.. GENERATED FROM PYTHON SOURCE LINES 167-172

Define the renamer from a dictionary
------------------------------------
You can also use a nested dictionary
of the form ``{discipline_name: {variable_name: new_variable_name}}``
to create the :class:`.VariableRenamer`:

.. GENERATED FROM PYTHON SOURCE LINES 172-175

.. code-block:: Python

    renamer = VariableRenamer.from_dictionary({"A": {"a": "x", "c": "z"}, "B": {"b": "y"}})
    renamer.translators





.. rst-class:: sphx-glr-script-out

 .. code-block:: none


    defaultdict(<class 'dict'>, {'A': {'a': 'x', 'c': 'z'}, 'B': {'b': 'y'}})



.. GENERATED FROM PYTHON SOURCE LINES 176-225

Define the renamer from a file
------------------------------
Lastly,
The :class:`.VariableRenamer` can easily be created from a file,
which may be more convenient from a user point of view.

From a CSV file
~~~~~~~~~~~~~~~
Given a CSV file
whose rows are translations
and columns denote
the name of the source discipline,
the name of the variable within the source discipline,
the name of the target discipline
and the name of the variable with the target discipline:

.. code-block:: console

   A,a,x
   B,b,y
   A,c,z

we can create this object with the following lines:

.. code-block:: python

   renamer = VariableRenamer.from_csv(file_path)
   translators = renamer.translators

.. tip::
    Use the ``sep`` argument to use a separator character other than ``","``.

From a spreadsheet file
~~~~~~~~~~~~~~~~~~~~~~~
Given a spreadsheet file
whose rows are translations
and columns denote
the name of the discipline,
the name of the variable,
and the new name of the discipline:

.. figure:: /_images/renaming_spreadsheet.png

we can create this object with the following lines:

.. code-block:: python

   renamer = VariableRenamer.from_spread_sheet(file_path)
   translators = renamer.translators


.. rst-class:: sphx-glr-timing

   **Total running time of the script:** (0 minutes 0.020 seconds)


.. _sphx_glr_download_examples_disciplines_variables_plot_variable_renaming.py:

.. only:: html

  .. container:: sphx-glr-footer sphx-glr-footer-example

    .. container:: sphx-glr-download sphx-glr-download-jupyter

      :download:`Download Jupyter notebook: plot_variable_renaming.ipynb <plot_variable_renaming.ipynb>`

    .. container:: sphx-glr-download sphx-glr-download-python

      :download:`Download Python source code: plot_variable_renaming.py <plot_variable_renaming.py>`

    .. container:: sphx-glr-download sphx-glr-download-zip

      :download:`Download zipped: plot_variable_renaming.zip <plot_variable_renaming.zip>`


.. only:: html

 .. rst-class:: sphx-glr-signature

    `Gallery generated by Sphinx-Gallery <https://sphinx-gallery.github.io>`_