Install

Besoins pour l'installation

PyCoA nécessite Python version >= 3 et une version de Bokeh >=2.4.0 est conseillée.
Nous rappelons que l'outil fonctionne actuellement au sein de notebooks type jupyter/jupyterlab, notamment pour des fins de sorties graphiques dont les rendus sont assurés par le navigateur hôte.

De nombreuses libraires sont requises, mais leur installation explicite n'est nécessaire que lors de l'installation par l'intermédiaire d'un fichier d'archive ou d'un clonage git.

Installation de PyCoA

Installation avec pip

C'est de loin l'installation la plus aisée. Elle s'applique soit localement en ligne de commande soit au sein d'un notebook fonctionnant sur un jupyter externalisé.

Besoins :

• pip
• git

En ligne de commande

• Pour installer la dernière version stable, on lance la commande

pip3 install --user git+https://github.com/coa-project/pycoa.git

qui assure l'installation de toutes les librairies requises pour PyCoA ainsi que pycoa lui-même pour l'utilisateur.

Options

• Si l'on souhaite installer pycoa pour tous les utilisateurs de la machine, on enlèvera l'option --user soit :

pip3 install git+https://github.com/coa-project/pycoa.git

• Pour récupérer une version particulière, on précisera dans la commande pip install le tag de la façon suivante

pip3 install --user git+https://github.com/coa-project/pycoa.git@v1.0

assurant l'installation de la version taggée v1.0.

• Enfin, pour ne avoir les détails de l'installation, on pourra ajouter l'option --quiet à la commande pip.

Installation sur un Jupyter externalisé

Cas de Google colab ou autre jupyter

Si l'on utilise un jupyter externalisé, comme google colaboratory, on utilisera également une installation via l'outil pip. On lancera ainsi à l'invite python :

pip3 install git+https://github.com/coa-project/pycoa.git

De même que précédemment, on pourra préciser le numéro de tag souhaité.

À noter que sur certains système, l'installation ne peut se faire qu'explicitement pour l'utilisateur. L'option --user est alors nécessaire.

Dans le notebook de démonstration disponible sur google-colab demo_pycoa.ipynb, la première partie concerne justement l'installation dans cet environnement.

Cas de binder

Encore plus simplement, il est possible de travailler directement sur les notebooks à disposition dans git et les faire tourner sur binder. Pour cela, on pointera directement (pour la version dev) vers . Pour avoir accés à l'ensemble des notebooks (c.f. le dossier coabook). Aucune installation ne sera nécessaire, la machine virtuelle, une fois lancée, comportera tout l'environnement indispensable au fonctionnement de PyCoA.

Installation manuelle des sources

Besoin en librairies

Outre les librairies standard, vous devrez avoir sur votre système :

• python3
• numpy
• pip

et les paquets suivants accessibles depuis une simple commande pip3 install <nom du package>

• pip:
  • nbgitpuller
  • sphinx-gallery
  • pandas
  • matplotlib
  • bokeh
  • branca
  • bs4
  • datascroller
  • datetime
  • folium
  • lxml
  • geopandas
  • matplotlib
  • numpy
  • pandas
  • pycountry
  • pycountry_convert
  • requests
  • scipy
  • shapely
  • pytest
  • unidecode

À noter qu'un certain nombre de ces librairies viennent automatiquement lors de l'installation de l'outil pip.

Installation avec un fichier d'archive

Ils sont disponibles en format zip ou tarball, éventuellement directement sur la page github du projet pycoa.

Télécharger l'archive et la décompresser dans l'endroit de votre choix pour les packages python sur votre système. En cas de besoin, préciser explicitement dans vos notebooks utilisant pycoa le chemin d'installation :

import sys
sys.path.insert(1, '/quelque/part/pycoa')  # remplacer /quelque/part par le vrai chemin d'installation

Clonage git

Vous pouvez aussi récupérer les sources en clonant le projet localement. Soit avec une commande

git clone https://github.com/coa-project/pycoa.git

Ici aussi, vous devrez préciser, si besoin, le chemin d'installation.

Tester la bonne installation

Dans python :

• Pour tester que la librairie existe bien dans le chemin :

# testing the correct install of pycoa
import importlib
coa_module_info = importlib.util.find_spec("coa")
if coa_module_info == None:
  raise ModuleNotFoundError("The coa module is not found. Please check your install")

• Pour tester la version de pycoa

C'est possible en utilisant le frontend coa.front

import coa.front as cf
cf.getversion()

ou bien directement sans charger le frontend

import coa
print(coa.__version__ )

Remarque sur l'accès aux données

Les données sont récupérées à condition d'avoir accès à internet. Si tel n'est pas le cas, PyCoA fonctionnera soit en mode dégradé soit ne fonctionnera pas. Lorsque des données sont récupérées sur l'internet, elles sont stockées dans un répertoire temporaire (dont le locus est propre à chaque système) afin d'accélérer les requêtes ultérieures. Vous en saurez plus si vous demandez un mode plus verbeux :

import coa.tools as ct
ct.set_verbose_mode(2)

En pratique, les données requises sont de deux types.

• Les données qui ont un caractère universel. Une fois récupérées, seule la version enregistrée localement est utilisée.
• les données évoluant souvent, ce qui est le cas des bases de données. Une fois récupérées, la version locale n'est utilisée que pendant 2 heures. Au delà, une nouvelle version est récupérée. Dans ce cas, si l'internet n'est plus actif, PyCoA fonctionnera malgré tout mais avec des données anciennes. Un avertissement sera alors donné à l'utilisateur.

Pour les premières données, il peut être pratique et plus efficace de récupérer localement à l'avance ce dont PyCoA a besoin. C'est le rôle du package coadata que l'on retrouve à https://github.com/coa-project/coadata. Si l'on a installé le package coadata, pour peu qu'il soit disponible dans le PATH, les données qui y sont seront utilisées directement.

L'installation s'effectue comme pour PyCoA (voir les commandes analogues ci-dessous, avec pip ou un tarbal du git). Pour une commande pip, il s'agira :

pip3 install --user git+https://github.com/coa-project/coadata.git

Puis l'ajout dans le chemin actif avec une commande du type :

sys.path.insert(1, '../coadata')