gismap 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

gismap/build.py

@@ -1,4 +1,26 @@
+"""
+Build script for creating the LDB (Local DBLP) database.
+
+Run as a module to download and process the DBLP dataset:
+
+    python -m gismap.build
+
+This will fetch the DBLP RDF dump from the website and create a compressed local database.
+"""
+
 if __name__ == "__main__":
+    import argparse
     from gismap.sources.ldb import LDB
+
+    parser = argparse.ArgumentParser(
+        description="Build LDB database from DBLP TTL dump."
+    )
+    parser.add_argument(
+        "--no-search",
+        action="store_true",
+        help="Exclude search engine from output (for GitHub assets).",
+    )
+    args = parser.parse_args()
+
     LDB.build_db()
-    LDB.dump_db()
+    LDB.dump_db(include_search=not args.no_search)

gismap/gisgraphs/builder.py

@@ -27,22 +27,37 @@ gislink = tags.a(
 
 def make_vis(lab, **kwargs):
     """
+    Generate HTML visualization of a lab's collaboration network.
+
     Parameters
     ----------
     lab: :class:`~gismap.lab.labmap.LabMap`
         Lab to display.
-
-    Other parameters
-    ----------------
-    uid: :class:`str`
-        Unique identifier.
-    vis_url: :class:`str`
-        Location of visJS network.
+    uid: :class:`str`, optional
+        Unique identifier for DOM elements. Auto-generated if not provided.
+    vis_url: :class:`str`, optional
+        URL to vis-network library.
+    groups: :class:`dict`, optional
+        Group styling configuration.
+    draw_legend: :class:`bool`, optional
+        Whether to draw the legend. Defaults to True if multiple groups.
+    physics: :class:`dict`, optional
+        Physics engine configuration.
+    nodes_options: :class:`dict`, optional
+        Node styling options.
+    edges_options: :class:`dict`, optional
+        Edge styling options.
+    interaction_options: :class:`dict`, optional
+        Interaction settings.
+    style: :class:`string.Template`, optional
+        CSS template.
+    script: :class:`string.Template`, optional
+        JavaScript template.
 
     Returns
     -------
     :class:`str`
-        HTML code.
+        HTML code as a string.
     """
     uid = kwargs.pop("uid", None)
     if uid is None:

gismap/gisgraphs/graph.py

@@ -21,6 +21,21 @@ def initials(name):
 
 
 def linkify(name, url):
+    """
+    Wrap a name in an HTML link if URL is provided.
+
+    Parameters
+    ----------
+    name : :class:`str`
+        Display text.
+    url : :class:`str` or None
+        Target URL, or None for no link.
+
+    Returns
+    -------
+    :class:`str`
+        HTML anchor tag or span.
+    """
     if url:
         return f'<a href="{url}" target="_blank">{name}</a>'
     else:

gismap/gisgraphs/widget.py

@@ -33,7 +33,7 @@ def safe_filename(name):
     return f"gismap-{safe_str[:60]}.html"
 
 
-place_holder = "Diego Perino, The-Dang Huynh, François Durand (hal: fradurand, ldb: 38/11269), Rim Kaddah, Leonardo Linguaglossa, Céline Comte"
+place_holder = "Diego Perino, The-Dang Huynh, François Durand (hal: fradurand, dblp: 38/11269), Rim Kaddah, Leonardo Linguaglossa, Céline Comte"
 
 
 class GismapWidget:
@@ -66,7 +66,7 @@ class GismapWidget:
             layout=widgets.Layout(width="50%", height="100px"),
         )
         self.dbs = widgets.RadioButtons(
-            options=["HAL", "LDB", "Both"],
+            options=["HAL", "DBLP", "Both"],
             description="DB(s):",
             layout=widgets.Layout(width="80px", max_width="20%"),
         )
@@ -97,12 +97,20 @@ class GismapWidget:
         self.show = True
 
     def html(self):
+        """
+        Generate the HTML visualization based on widget inputs.
+
+        Returns
+        -------
+        :class:`str`
+            HTML content for the collaboration graph.
+        """
         dbs = (
             "hal"
             if self.dbs.value == "HAL"
-            else "ldb"
-            if self.dbs.value == "LDB"
-            else ["hal", "ldb"]
+            else "dblp"
+            if self.dbs.value == "DBLP"
+            else ["hal", "dblp"]
         )
         name = self.names.value
         pattern = r",\s*(?![^()]*\))"
@@ -128,6 +136,20 @@ class GismapWidget:
         return lab.html()
 
     def compute_function(self, b, show=True):
+        """
+        Handle compute button click and generate visualization.
+
+        Parameters
+        ----------
+        b : :class:`ipywidgets.Button`
+            The button widget that triggered this callback.
+        show : :class:`bool`, default=True
+            Whether to display the result in the widget.
+
+        Returns
+        -------
+        None
+        """
         self.show = show
         full = self.html()
         b64 = base64.b64encode(
@@ -135,9 +157,7 @@ class GismapWidget:
         ).decode("utf8")
         payload = f"data:text/html;base64,{b64}"
         savename = safe_filename(self.names.value)
-        link_html = (
-            f"<a href='{payload}' download='{savename}'>Download the Map!</a>"
-        )
+        link_html = f"<a href='{payload}' download='{savename}'>Download the Map!</a>"
         self.save_link.value = link_html
         if show:
             self.out.clear_output()

gismap/lab/egomap.py

@@ -4,19 +4,27 @@ from gismap.lab.lab_author import LabAuthor
 
 class EgoMap(LabMap):
     """
+    Egocentric view of a researcher's collaboration network.
+
+    Displays the *star* (central researcher), their *planets* (direct co-authors),
+    and optionally *moons* (co-authors of co-authors).
+
     Parameters
     ----------
-    star
-    args
-    kwargs
+    star: :class:`str` or :class:`~gismap.lab.lab_author.LabAuthor`
+        The central researcher. Can be a name string or LabAuthor object.
+    *args
+        Passed to :class:`~gismap.lab.labmap.LabMap`.
+    **kwargs
+        Passed to :class:`~gismap.lab.labmap.LabMap`.
 
     Examples
     --------
 
-    >>> dang = EgoMap("The-Dang Huynh", dbs="hal")
-    >>> dang.build(target=10)
-    >>> sorted(a.name for a in dang.authors.values())  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
-    ['Bruno Kauffmann', 'Chung Shue Chen', 'Fabien Mathieu',...
+    >>> dang = EgoMap("The-Dang Huynh")
+    >>> dang.build(target=20)
+    >>> sorted(a.name for a in dang.authors.values() if len(a.name.split())<3)  # doctest: +NORMALIZE_WHITESPACE +ELLIPSIS
+    ['Bruno Kauffmann', 'Diego Perino', 'Dohy Hong', 'Fabien Mathieu', 'François Baccelli',...]
     """
 
     def __init__(self, star, *args, **kwargs):
@@ -31,6 +39,20 @@ class EgoMap(LabMap):
         yield self.star
 
     def build(self, **kwargs):
+        """
+        Build the ego network by fetching publications and adding planets/moons.
+
+        Parameters
+        ----------
+        target : :class:`int`, default=50
+            Target number of authors in the final map.
+        **kwargs
+            Passed to :meth:`~gismap.lab.labmap.LabMap.expand`.
+
+        Returns
+        -------
+        None
+        """
         target = kwargs.pop("target", 50)
         self.update_authors(desc="Star metadata")
         self.update_publis(desc="Star publications")

gismap/lab/expansion.py

@@ -139,7 +139,14 @@ def get_prospects(lab):
 @dataclass
 class Member:
     """
-    Basic information
+    Basic information about a lab member for name matching.
+
+    Parameters
+    ----------
+    name : :class:`str`
+        Normalized name.
+    key : :class:`str`
+        Author key.
     """
 
     name: str
@@ -190,6 +197,33 @@ def trim_sources(author):
 def proper_prospects(
     lab, length_impact=0.05, threshold=80, n_range=4, max_new=None, trim=True
 ):
+    """
+    Find and rank external collaborators for potential lab expansion.
+
+    Identifies authors from publications who are not already lab members,
+    groups them by name similarity, and ranks by collaboration strength.
+
+    Parameters
+    ----------
+    lab : :class:`~gismap.lab.labmap.LabMap`
+        Reference lab.
+    length_impact : :class:`float`, default=0.05
+        Length impact for name similarity matching.
+    threshold : :class:`int`, default=80
+        Similarity threshold for grouping authors.
+    n_range : :class:`int`, default=4
+        N-gram range for name comparison.
+    max_new : :class:`int`, optional
+        Maximum number of new authors to return.
+    trim : :class:`bool`, default=True
+        If True, keep only one source per database for each author.
+
+    Returns
+    -------
+    :class:`tuple`
+        (existing, new_rosetta) where existing maps external keys to lab member keys,
+        and new_rosetta maps source keys to new LabAuthor objects.
+    """
     member_names = get_member_names(lab)
     prospects = get_prospects(lab)
 

gismap/lab/lab_author.py

@@ -56,6 +56,7 @@ class LabAuthor(SourcedAuthor):
     >>> dummy2.sources
     [HALAuthor(name='My Name', key='key1'), HALAuthor(name='My Name', key='123456', key_type='pid'), HALAuthor(name='My Name', key='My Other Name', key_type='fullname')]
     """
+
     metadata: AuthorMetadata = field(default_factory=AuthorMetadata)
 
     def auto_img(self):
@@ -116,12 +117,41 @@ class LabAuthor(SourcedAuthor):
 
 
 def labify_author(author, rosetta):
+    """
+    Convert a database author to a LabAuthor if possible.
+
+    Parameters
+    ----------
+    author : :class:`~gismap.sources.models.Author`
+        Author to convert.
+    rosetta : :class:`dict`
+        Mapping from keys/names to LabAuthor objects.
+
+    Returns
+    -------
+    :class:`~gismap.lab.lab_author.LabAuthor` or original author
+        LabAuthor if found in rosetta, otherwise the original author.
+    """
     if isinstance(author, LabAuthor):
         return author
     return rosetta.get(author.key, rosetta.get(author.name, author))
 
 
 def labify_publications(pubs, rosetta):
+    """
+    Convert publication authors to LabAuthors in place.
+
+    Parameters
+    ----------
+    pubs : :class:`list`
+        Publications to update.
+    rosetta : :class:`dict`
+        Mapping from keys/names to LabAuthor objects.
+
+    Returns
+    -------
+    None
+    """
     for pub in pubs:
         pub.authors = [labify_author(a, rosetta) for a in pub.authors]
         for source in getattr(pub, "sources", []):

gismap/lab/labmap.py

@@ -91,7 +91,9 @@ class LabMap(MixInIO):
             if not all(f(author) for f in self.author_selectors):
                 continue
             if len(author.sources) == 0:
-                author.auto_sources(dbs=list_of_objects(self.dbs, db_dict, default=default_dbs))
+                author.auto_sources(
+                    dbs=list_of_objects(self.dbs, db_dict, default=default_dbs)
+                )
             if author.sources:
                 self.authors[author.key] = author
             if author.metadata.img is None:
@@ -152,9 +154,36 @@ class LabMap(MixInIO):
         return None
 
     def html(self, **kwargs):
+        """
+        Generate HTML representation of the collaboration graph.
+
+        Parameters
+        ----------
+        **kwargs
+            Passed to :func:`~gismap.gisgraphs.builder.make_vis`.
+
+        Returns
+        -------
+        :class:`str`
+            HTML content as a string.
+        """
         return make_vis(self, **kwargs)
 
     def save_html(self, name=None, **kwargs):
+        """
+        Save the collaboration graph as an HTML file.
+
+        Parameters
+        ----------
+        name: :class:`str`, optional
+            Output filename. Defaults to lab name.
+        **kwargs
+            Passed to :meth:`html`.
+
+        Returns
+        -------
+        None
+        """
         if name is None:
             name = self.name
         name = Path(name).with_suffix(".html")
@@ -162,6 +191,18 @@ class LabMap(MixInIO):
             f.write(self.html(**kwargs))
 
     def show_html(self, **kwargs):
+        """
+        Display the collaboration graph in a Jupyter notebook.
+
+        Parameters
+        ----------
+        **kwargs
+            Passed to :meth:`html`.
+
+        Returns
+        -------
+        None
+        """
         display(HTML(self.html(**kwargs)))
 
 
@@ -174,9 +215,9 @@ class ListMap(LabMap):
     author_list: :class:`list` of :class:`str`
         List of authors names.
     args: :class:`list`
-        Arguments to pass to the :class:`~gismap.lab.lab.Lab` constuctor.
+        Arguments to pass to the :class:`~gismap.lab.lab.Lab` constructor.
     kwargs: :class:`dict`
-        Keyword arguments to pass to the :class:`~gismap.lab.lab.Lab` constuctor.
+        Keyword arguments to pass to the :class:`~gismap.lab.lab.Lab` constructor.
     """
 
     def __init__(self, author_list, *args, **kwargs):

gismap/lab_examples/cedric.py

@@ -10,37 +10,50 @@ class CedricMap(LabMap):
     Class for handling a CNAM Cedric team from its name.
     Default to `roc` team.
     """
+
     name = "roc"
     base_url = "https://cedric.cnam.fr"
 
     def _author_iterator(self):
         soup = Soup(get(f"{self.base_url}/equipes/{self.name}/"), features="lxml")
-        searchers = [li.a for ul in soup.find('div', {'id': 'annuaire'})('ul')[:3] for li in ul('li')]
+        searchers = [
+            li.a
+            for ul in soup.find("div", {"id": "annuaire"})("ul")[:3]
+            for li in ul("li")
+        ]
         done = set()
         for searcher in searchers:
-            name = searcher.text.split('(')[0].strip()
+            name = searcher.text.split("(")[0].strip()
             if name in done:
                 continue
             url = f"{self.base_url}{searcher['href']}"
             sousoup = Soup(get(url), features="lxml")
-            img = sousoup.find('img', {'class': 'photo'})['src']
+            img = sousoup.find("img", {"class": "photo"})["src"]
             response = requests.head(img, allow_redirects=True)
             if int(response.headers.get("Content-Length")) < 3000:
                 img = None
             done.add(name)
-            yield LabAuthor(name=name, metadata=AuthorMetadata(url=url, img=img, group=self.name.upper()))
+            yield LabAuthor(
+                name=name,
+                metadata=AuthorMetadata(url=url, img=img, group=self.name.upper()),
+            )
 
 
 class CedricFull(LabMap):
     """
     Class for handling all CNAM Cedric teams using `https://cedric.cnam.fr/equipes` to get team names.
     """
+
     name = "Cedric"
 
     def _author_iterator(self):
         base = "https://cedric.cnam.fr/equipes/"
-        soup =  Soup(get(base), features="lxml")
-        teams = {a['href'].split('/')[-2] for a in soup('a') if base in a.get('href', "") and len(a['href'])>len(base)}
+        soup = Soup(get(base), features="lxml")
+        teams = {
+            a["href"].split("/")[-2]
+            for a in soup("a")
+            if base in a.get("href", "") and len(a["href"]) > len(base)
+        }
         for team in teams:
             for author in CedricMap(name=team)._author_iterator():
                 yield author

gismap/lab_examples/lamsade.py

@@ -18,8 +18,8 @@ def lamsade_parse(div):
     :class:`tuple`
         name, image url (or None), webpage (or None)
     """
-    img = div.img['src'] if div.img else None
-    url = div.a['href'] if div.a else None
+    img = div.img["src"] if div.img else None
+    url = div.a["href"] if div.a else None
     name = div.h2.text.strip().title()
     name = " ".join(name.split(" ", 1)[::-1])
     return name, img, url
@@ -35,9 +35,11 @@ class Lamsade(LabMap):
     directory = "fr/personnes/enseignants-chercheurs-et-chercheurs.html"
 
     def _author_iterator(self):
-        soup = Soup(get(self.base_url+self.directory), features="lxml")
-        for a in soup('div', class_="dauphinecv-item"):
+        soup = Soup(get(self.base_url + self.directory), features="lxml")
+        for a in soup("div", class_="dauphinecv-item"):
             name, img, url = lamsade_parse(a)
-            img = self.base_url+img if img else None
-            url = self.base_url+url if url else None
-            yield LabAuthor(name=name, metadata=AuthorMetadata(url=url, img=img, group=self.name))
+            img = self.base_url + img if img else None
+            url = self.base_url + url if url else None
+            yield LabAuthor(
+                name=name, metadata=AuthorMetadata(url=url, img=img, group=self.name)
+            )

gismap/lab_examples/toulouse.py

@@ -29,18 +29,22 @@ class LaasMap(LabMap):
                 if "public_avatar" in a.img["class"]
                 else None
             )
-            yield LabAuthor(name=name, metadata=AuthorMetadata(url=url, img=img, group=self.name.upper()))
+            yield LabAuthor(
+                name=name,
+                metadata=AuthorMetadata(url=url, img=img, group=self.name.upper()),
+            )
 
 
 class LaasFull(LabMap):
     """
     Class for handling all LAAS teams using `https://www.laas.fr/fr/equipes/` to get team names.
     """
+
     name = "LAAS"
 
     def _author_iterator(self):
         soup = Soup(get("https://www.laas.fr/fr/equipes/"), features="lxml")
-        teams = [a['href'].split('/')[-2] for a in soup('a', {'class': "badge"})]
+        teams = [a["href"].split("/")[-2] for a in soup("a", {"class": "badge"})]
         for team in teams:
             for author in LaasMap(name=team)._author_iterator():
                 yield author

gismap/search.py

@@ -6,7 +6,17 @@ from gismap.utils.text import reduce_keywords, Corrector
 
 class SearchAction:
     """
-    Blueprint for extracting search results out of a gismo.
+    Base class for extracting search results from a Gismo.
+
+    Subclasses should implement :meth:`process` to define
+    how to extract results from the gismo.
+
+    Parameters
+    ----------
+    name : :class:`str`, optional
+        Name of this action (used as key in results dict).
+    post : callable, optional
+        Post-processing function applied to results.
     """
 
     def __init__(self, name=None, post=None):
@@ -14,9 +24,33 @@ class SearchAction:
         self.post = (lambda x: x) if post is None else post
 
     def process(self, gismo):
+        """
+        Extract results from the gismo. Must be implemented by subclasses.
+
+        Parameters
+        ----------
+        gismo : :class:`~gismo.gismo.Gismo`
+            The gismo to query.
+
+        Returns
+        -------
+        Results (type depends on subclass).
+        """
         raise NotImplementedError
 
     def run(self, gismo):
+        """
+        Execute the action and apply post-processing.
+
+        Parameters
+        ----------
+        gismo : :class:`~gismo.gismo.Gismo`
+            The gismo to query.
+
+        Returns
+        -------
+        Post-processed results.
+        """
         return self.post(self.process(gismo))
 
 
@@ -153,6 +187,19 @@ publi_template = Template("""
 
 
 def publi_to_html(publi):
+    """
+    Convert a publication to an HTML list item.
+
+    Parameters
+    ----------
+    publi : :class:`~gismap.sources.models.Publication`
+        Publication to convert.
+
+    Returns
+    -------
+    :class:`str`
+        HTML list item string.
+    """
     dico = dict()
     for db in ["hal", "dblp"]:
         source = publi.sources.get(db)
@@ -167,6 +214,19 @@ def publi_to_html(publi):
 
 
 def publis_to_html(publis):
+    """
+    Convert a list of publications to an HTML unordered list.
+
+    Parameters
+    ----------
+    publis : :class:`list`
+        List of publications.
+
+    Returns
+    -------
+    :class:`str`
+        HTML unordered list string.
+    """
     rows = "\n".join(publi_to_html(p) for p in publis)
     return f"<ul>\n{rows}\n</ul>"
 

gismap/sources/dblp.py

@@ -98,6 +98,7 @@ class DBLPAuthor(Author, DBLP):
     key='conf/sss/Mathieu07')
 
     """
+
     key: str
     aliases: list = field(default_factory=list)
 
@@ -124,6 +125,27 @@ DBLP_TYPES = {
 
 @dataclass(repr=False)
 class DBLPPublication(Publication, DBLP):
+    """
+    Publication from the DBLP database.
+
+    Parameters
+    ----------
+    title: :class:`str`
+        Publication title.
+    authors: :class:`list`
+        List of :class:`DBLPAuthor` objects.
+    venue: :class:`str`
+        Publication venue.
+    type: :class:`str`
+        Publication type.
+    year: :class:`int`
+        Publication year.
+    key: :class:`str`
+        DBLP record key.
+    metadata: :class:`dict`
+        Additional metadata (pages, volume, etc.).
+    """
+
     key: str
     metadata: dict = field(default_factory=dict)