FindStat - the search engine for combinatorial statistics and maps - Databases

Skip to content
Back to top
View this page
Edit this page

# FindStat - the search engine for combinatorial statistics and maps

The interface to the FindStat database is

Sage

    sage: findstat()
    The Combinatorial Statistic Finder (https://www.findstat.org/)

Python

    >>> from sage.all import *
    >>> findstat()
    The Combinatorial Statistic Finder (https://www.findstat.org/)

We use the following three notions

- A combinatorial collection is a set \(S\) with interesting combinatorial properties,

- a combinatorial map is a combinatorially interesting map \(f: S \to S'\) between combinatorial collections, and

- a combinatorial statistic is a combinatorially interesting map \(s: S \to \ZZ\).

You can use the FindStat interface to

- identify a combinatorial statistic or map given the values on a few small objects,

- obtain more terms, formulae, references, etc. for a given statistic or map,

- edit statistics and maps and submit new statistics.

The main entry points to the database are

- `findstat()` to search for matching statistics,

- `findmap()` to search for matching maps.

## A guided tour

### Retrieving information

The most straightforward application of the FindStat interface is to gather information about a combinatorial statistic. To do this, we supply `findstat()` with a list of `(object, value)` pairs. For example:

Sage

    sage: PM = PerfectMatchings
    sage: r = findstat([(m, m.number_of_nestings()) for n in range(6) for m in PM(2*n)], depth=1); r # optional -- internet
    0: St000042oMp00116 (quality [100, 100])
    1: St000041 (quality [20, 100])
    ...

Python

    >>> from sage.all import *
    >>> PM = PerfectMatchings
    >>> r = findstat([(m, m.number_of_nestings()) for n in range(Integer(6)) for m in PM(Integer(2)*n)], depth=Integer(1)); r # optional -- internet
    0: St000042oMp00116 (quality [100, 100])
    1: St000041 (quality [20, 100])
    ...

The result of this query is a list (presented as a `sage.databases.oeis.FancyTuple`) of matches. Each match consists of a `FindStatCompoundStatistic` \(s: S \to \ZZ\) and an indication of the quality of the match.

The precise meaning of the result is as follows:

> The composition \(f_n \circ ... \circ f_2 \circ f_1\) applied to the objects sent to FindStat agrees with all `(object, value)` pairs of \(s\) in the database. The optional parameter `depth=1` limits the output to \(n=1\).

> Suppose that the quality of the match is \((q_a, q_d)\). Then \(q_a\) is the percentage of `(object, value)` pairs that are in the database among those which were sent to FindStat, and \(q_d\) is the percentage of `(object, value)` pairs with distinct values in the database among those which were sent to FindStat.

Put differently, if `quality` is not too small it is likely that the statistic sent to FindStat equals \(s \circ f_n \circ ... \circ f_2 \circ f_1\). If \(q_a\) is large, but \(q_b\) is small, then there were many matches, but while the sought for statistic attains many distinct values, the match found by FindStat covers only `(object, value)` pairs for few values.

In the case at hand, for the match `St000041`, the list of maps is empty. We can retrieve the description of the statistic from the database as follows:

Sage

    sage: print(r[1].statistic().description())                                 # optional -- internet
    The number of nestings of a perfect matching.

    This is the number of pairs of edges $((a,b), (c,d))$ such that $a\le c\le d\le b$. i.e., the edge $(c,d)$ is nested inside $(a,b)$...

[Python]

    >>> from sage.all import *
    >>> print(r[Integer(1)].statistic().description())                                 # optional -- internet
    The number of nestings of a perfect matching.
    <BLANKLINE>
    <BLANKLINE>
    This is the number of pairs of edges $((a,b), (c,d))$ such that $a\le c\le d\le b$. i.e., the edge $(c,d)$ is nested inside $(a,b)$...

We can check the references:

Sage

    sage: r[1].statistic().references()                                         # optional -- internet
    0: [1]  de Médicis, A., Viennot, X. G., Moments des $q$-polynômes de Laguerre et la bijection de Foata-Zeilberger [[MathSciNet:1288802]]
    1: [2]  Simion, R., Stanton, D., Octabasic Laguerre polynomials and permutation statistics [[MathSciNet:1418763]]...

Python

    >>> from sage.all import *
    >>> r[Integer(1)].statistic().references()                                         # optional -- internet
    0: [1]  de Médicis, A., Viennot, X. G., Moments des $q$-polynômes de Laguerre et la bijection de Foata-Zeilberger [[MathSciNet:1288802]]
    1: [2]  Simion, R., Stanton, D., Octabasic Laguerre polynomials and permutation statistics [[MathSciNet:1418763]]...

If you prefer, you can look at this information also in your browser:

Sage

    sage: r[1].statistic().browse()                                             # optional -- webbrowser

[Python]

    >>> from sage.all import *
    >>> r[Integer(1)].statistic().browse()                                             # optional -- webbrowser

Another interesting possibility is to look for equidistributed statistics. Instead of submitting a list of `(object, value)` pairs, we pass a list of pairs `(objects, values)`:

Sage

    sage: data = [(PM(2*n), [m.number_of_nestings() for m in PM(2*n)]) for n in range(5)]
    sage: findstat(data, depth=0)                                               # optional -- internet
    0: St000041 (quality [99, 100])
    1: St000042 (quality [99, 100])

Python

    >>> from sage.all import *
    >>> data = [(PM(Integer(2)*n), [m.number_of_nestings() for m in PM(Integer(2)*n)]) for n in range(Integer(5))]
    >>> findstat(data, depth=Integer(0))                                               # optional -- internet
    0: St000041 (quality [99, 100])
    1: St000042 (quality [99, 100])

This results tells us that the database contains another entry that is equidistributed with the number of nestings on perfect matchings of size at most \(10\), namely the number of crossings. Note that there is a limit on the number of elements FindStat accepts for a query, which is currently \(1000\). Queries with more than \(1000\) elements are truncated.

Let us now look at a slightly more complicated example, where the submitted statistic is the composition of a sequence of combinatorial maps and a statistic known to FindStat. We use the occasion to advertise yet another way to pass values to FindStat:

Sage

    sage: r = findstat(Permutations, lambda pi: pi.saliances()[0], depth=2); r  # optional -- internet
    0: St000740oMp00066 with offset 1 (quality [100, 100])
    1: St000740oMp00087 with offset 1 (quality [100, 100])
    ...

[Python]

    >>> from sage.all import *
    >>> r = findstat(Permutations, lambda pi: pi.saliances()[Integer(0)], depth=Integer(2)); r  # optional -- internet
    0: St000740oMp00066 with offset 1 (quality [100, 100])
    1: St000740oMp00087 with offset 1 (quality [100, 100])
    ...

Note that some of the matches are up to a global offset. For example, we have:

Sage

    sage: r[1].info()                                                           # optional -- internet
    after adding 1 to every value
    and applying
        Mp00087: inverse first fundamental transformation: Permutations -> Permutations
    to the objects (see `.compound_map()` for details)

    your input matches
        St000740: The last entry of a permutation.

    among the values you sent, 100 percent are actually in the database,
    among the distinct values you sent, 100 percent are actually in the database

Python

    >>> from sage.all import *
    >>> r[Integer(1)].info()                                                           # optional -- internet
    after adding 1 to every value
    and applying
        Mp00087: inverse first fundamental transformation: Permutations -> Permutations
    to the objects (see `.compound_map()` for details)
    <BLANKLINE>
    your input matches
        St000740: The last entry of a permutation.
    <BLANKLINE>
    among the values you sent, 100 percent are actually in the database,
    among the distinct values you sent, 100 percent are actually in the database

Let us pick another particular result:

Sage

    sage: s = findstat("St000051oMp00061oMp00069")                              # optional -- internet
    sage: s.info()                                                              # optional -- internet
        Mp00069: complement: Permutations -> Permutations
        Mp00061: to increasing tree: Permutations -> Binary trees
        St000051: The size of the left subtree of a binary tree.

[Python]

    >>> from sage.all import *
    >>> s = findstat("St000051oMp00061oMp00069")                              # optional -- internet
    >>> s.info()                                                              # optional -- internet
        Mp00069: complement: Permutations -> Permutations
        Mp00061: to increasing tree: Permutations -> Binary trees
        St000051: The size of the left subtree of a binary tree.

To obtain the value of the statistic sent to FindStat on a given object, apply the maps in the list in the given order to this object, and evaluate the statistic on the result. For example, let us check that the result given by FindStat agrees with our statistic on the following permutation:

Sage

    sage: pi = Permutation([3,1,4,5,2]); pi.saliances()[0]
    3

Python

    >>> from sage.all import *
    >>> pi = Permutation([Integer(3),Integer(1),Integer(4),Integer(5),Integer(2)]); pi.saliances()[Integer(0)]
    3

We first have to find out, what the maps and the statistic actually do:

Sage

    sage: print(s.statistic().description())                                    # optional -- internet
    The size of the left subtree of a binary tree.

    sage: print(s.statistic().sage_code())                                      # optional -- internet
    def statistic(T):
        return T[0].node_number()

    sage: print("\n\n".join(m.sage_code() for m in s.compound_map()))           # optional -- internet
    def mapping(sigma):
        return sigma.complement()

    def mapping(sigma):
        return sigma.increasing_tree_shape()

[Python]

    >>> from sage.all import *
    >>> print(s.statistic().description())                                    # optional -- internet
    The size of the left subtree of a binary tree.

    >>> print(s.statistic().sage_code())                                      # optional -- internet
    def statistic(T):
        return T[0].node_number()

    >>> print("\n\n".join(m.sage_code() for m in s.compound_map()))           # optional -- internet
    def mapping(sigma):
        return sigma.complement()
    <BLANKLINE>
    def mapping(sigma):
        return sigma.increasing_tree_shape()

So, the following should coincide with what we sent FindStat:

Sage

    sage: pi.complement().increasing_tree_shape()[0].node_number()
    3

Python

    >>> from sage.all import *
    >>> pi.complement().increasing_tree_shape()[Integer(0)].node_number()
    3

### Editing and submitting statistics

Of course, often a statistic will not be in the database:

Sage

    sage: s = findstat([(d, randint(1,1000)) for d in DyckWords(4)]); s         # optional -- internet
    St000000: a new statistic on Dyck paths

Python

    >>> from sage.all import *
    >>> s = findstat([(d, randint(Integer(1),Integer(1000))) for d in DyckWords(Integer(4))]); s         # optional -- internet
    St000000: a new statistic on Dyck paths

In this case, and if the statistic might be “interesting”, please consider submitting it to the database using `FindStatStatistic.submit()`.

Also, you may notice omissions, typos or even mistakes in the description, the code and the references. In this case, simply replace the value by using `FindStatFunction.set_description()`, `FindStatStatistic.set_code()` or `FindStatFunction.set_references_raw()`, and then `FindStatStatistic.submit()` your changes for review by the FindStat team.

AUTHORS:

- Martin Rubey (2015): initial version

- Martin Rubey (2020): rewrite, adapt to new FindStat API

class sage.databases.findstat.FindStat

  Bases: `UniqueRepresentation`, `SageObject`

  The Combinatorial Statistic Finder.

  `FindStat` is a class preserving user information.

  browse()

    Open the FindStat web page in a browser.

    EXAMPLES:

    Sage

        sage: findstat().browse()                                           # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> findstat().browse()                                           # optional -- webbrowser

  login()

    Open the FindStat login page in a browser.

    EXAMPLES:

    Sage

        sage: findstat().login()                                            # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> findstat().login()                                            # optional -- webbrowser

  set_user(name=None, email=None)

    Set the user for the session.

    INPUT:

    - `name` – the name of the user

    - `email` – an email address of the user

    This information is used when submitting a statistic with `FindStatStatistic.submit()`.

    EXAMPLES:

    Sage

        sage: findstat().set_user(name='Anonymous', email='invalid@org')

    Python

        >>> from sage.all import *
        >>> findstat().set_user(name='Anonymous', email='invalid@org')

    Note

    It is usually more convenient to login into the FindStat web page using the `login()` method.

  user_email()

    Return the user name used for submissions.

    EXAMPLES:

    Sage

        sage: findstat().set_user(name='Anonymous', email='invalid@org')
        sage: findstat().user_email()
        'invalid@org'

    Python

        >>> from sage.all import *
        >>> findstat().set_user(name='Anonymous', email='invalid@org')
        >>> findstat().user_email()
        'invalid@org'

  user_name()

    Return the user name used for submissions.

    EXAMPLES:

    Sage

        sage: findstat().set_user(name='Anonymous', email='invalid@org')
        sage: findstat().user_name()
        'Anonymous'

    Python

        >>> from sage.all import *
        >>> findstat().set_user(name='Anonymous', email='invalid@org')
        >>> findstat().user_name()
        'Anonymous'

class sage.databases.findstat.FindStatCollection(parent, id, data, sageconstructor_overridden)

  Bases: `Element`

  A FindStat collection.

  `FindStatCollection` is a class representing a combinatorial collection available in the FindStat database.

  Its main use is to allow easy specification of the combinatorial collection when using `findstat`. It also provides methods to quickly access its FindStat web page (`browse()`), check whether a particular element is actually in the range considered by FindStat (`in_range()`), etc.

  INPUT:

  One of the following:

  - a string eg. ‘Dyck paths’ or ‘DyckPaths’, case-insensitive, or

  - an integer designating the FindStat id of the collection, or

  - a Sage object belonging to a collection, or

  - an iterable producing a Sage object belonging to a collection.

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatCollection
      sage: FindStatCollection("Dyck paths")                                  # optional -- internet
      Cc0005: Dyck paths

      sage: FindStatCollection(5)                                             # optional -- internet
      Cc0005: Dyck paths

      sage: FindStatCollection(DyckWord([1,0,1,0]))                           # optional -- internet
      Cc0005: Dyck paths

      sage: FindStatCollection(DyckWords(2))                                  # optional -- internet
      a subset of Cc0005: Dyck paths

      sage: FindStatCollection(DyckWords)                                     # optional -- internet
      Cc0005: Dyck paths

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatCollection
      >>> FindStatCollection("Dyck paths")                                  # optional -- internet
      Cc0005: Dyck paths

      >>> FindStatCollection(Integer(5))                                             # optional -- internet
      Cc0005: Dyck paths

      >>> FindStatCollection(DyckWord([Integer(1),Integer(0),Integer(1),Integer(0)]))                           # optional -- internet
      Cc0005: Dyck paths

      >>> FindStatCollection(DyckWords(Integer(2)))                                  # optional -- internet
      a subset of Cc0005: Dyck paths

      >>> FindStatCollection(DyckWords)                                     # optional -- internet
      Cc0005: Dyck paths

  See also

  `FindStatCollections`

  browse()

    Open the FindStat web page of the collection in a browser.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: FindStatCollection("Permutations").browse()                   # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> FindStatCollection("Permutations").browse()                   # optional -- webbrowser

  element_level(element)

    Return the level of an element.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        sage: cc.element_level(PerfectMatching([[1,2],[3,4],[5,6]]))        # optional -- internet
        6

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        >>> cc.element_level(PerfectMatching([[Integer(1),Integer(2)],[Integer(3),Integer(4)],[Integer(5),Integer(6)]]))        # optional -- internet
        6

  elements_on_level(level)

    Return an iterable over the elements on the given level.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: FindStatCollection("Perfect Matchings").elements_on_level(4)  # optional -- internet
        Perfect matchings of {1, 2, 3, 4}

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> FindStatCollection("Perfect Matchings").elements_on_level(Integer(4))  # optional -- internet
        Perfect matchings of {1, 2, 3, 4}

  first_terms(function, level=None)

    Compute the first few terms of the given function, possibly restricted to a level, as a lazy list.

    INPUT:

    - `function` – a callable

    - `level` – (optional), the level to restrict to

    OUTPUT:

    A lazy list of pairs of the form `(object, value)`.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        sage: c.first_terms(lambda x: 1)[:10].list()                        # optional -- internet
        [([[1, 0], [0]], 1),
         ([[1, 0], [1]], 1),
         ([[2, 0], [0]], 1),
         ([[2, 0], [1]], 1),
         ([[2, 0], [2]], 1),
         ([[1, 1], [1]], 1),
         ([[1, 0, 0], [0, 0], [0]], 1),
         ([[1, 0, 0], [1, 0], [0]], 1),
         ([[1, 0, 0], [1, 0], [1]], 1),
         ([[3, 0], [0]], 1)]

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        >>> c.first_terms(lambda x: Integer(1))[:Integer(10)].list()                        # optional -- internet
        [([[1, 0], [0]], 1),
         ([[1, 0], [1]], 1),
         ([[2, 0], [0]], 1),
         ([[2, 0], [1]], 1),
         ([[2, 0], [2]], 1),
         ([[1, 1], [1]], 1),
         ([[1, 0, 0], [0, 0], [0]], 1),
         ([[1, 0, 0], [1, 0], [0]], 1),
         ([[1, 0, 0], [1, 0], [1]], 1),
         ([[3, 0], [0]], 1)]

  from_string()

    Return a function that returns the object given a FindStat representation.

    OUTPUT:

    The function that produces the Sage object given its FindStat representation as a string.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: c = FindStatCollection("Posets")                              # optional -- internet
        sage: p = c.from_string()('([(0, 2), (2, 1)], 3)')                  # optional -- internet
        sage: p.cover_relations()                                           # optional -- internet
        [[0, 2], [2, 1]]

        sage: c = FindStatCollection("Binary Words")                        # optional -- internet
        sage: w = c.from_string()('010101')                                 # optional -- internet
        sage: w in c._data["Code"].elements_on_level(6)                     # optional -- internet
        True

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> c = FindStatCollection("Posets")                              # optional -- internet
        >>> p = c.from_string()('([(0, 2), (2, 1)], 3)')                  # optional -- internet
        >>> p.cover_relations()                                           # optional -- internet
        [[0, 2], [2, 1]]

        >>> c = FindStatCollection("Binary Words")                        # optional -- internet
        >>> w = c.from_string()('010101')                                 # optional -- internet
        >>> w in c._data["Code"].elements_on_level(Integer(6))                     # optional -- internet
        True

  id()

    Return the FindStat identifier of the collection.

    OUTPUT: the FindStat identifier of the collection as an integer

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        sage: c.id()                                                        # optional -- internet
        18

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        >>> c.id()                                                        # optional -- internet
        18

  id_str()

    Return the FindStat identifier of the collection.

    OUTPUT: the FindStat identifier of the collection as a string

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        sage: c.id_str()                                                    # optional -- internet
        'Cc0018'

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> c = FindStatCollection("GelfandTsetlinPatterns")              # optional -- internet
        >>> c.id_str()                                                    # optional -- internet
        'Cc0018'

  in_range(element)

    Check whether an element of the collection is in FindStat’s precomputed range.

    INPUT:

    - `element` – a Sage object that belongs to the collection

    OUTPUT: `True`, if `element` is used by the FindStat search engine, and `False` if it is ignored

    EXAMPLES:

    Sage

        sage: # optional - internet
        sage: from sage.databases.findstat import FindStatCollection
        sage: c = FindStatCollection("GelfandTsetlinPatterns")
        sage: c.in_range(GelfandTsetlinPattern([[2, 1], [1]]))
        True
        sage: c.in_range(GelfandTsetlinPattern([[3, 1], [1]]))
        True
        sage: c.in_range(GelfandTsetlinPattern([[7, 1], [1]]))
        False

    Python

        >>> from sage.all import *
        >>> # optional - internet
        >>> from sage.databases.findstat import FindStatCollection
        >>> c = FindStatCollection("GelfandTsetlinPatterns")
        >>> c.in_range(GelfandTsetlinPattern([[Integer(2), Integer(1)], [Integer(1)]]))
        True
        >>> c.in_range(GelfandTsetlinPattern([[Integer(3), Integer(1)], [Integer(1)]]))
        True
        >>> c.in_range(GelfandTsetlinPattern([[Integer(7), Integer(1)], [Integer(1)]]))
        False

  is_element(element)

    Return whether the element belongs to the collection.

    If the collection is not yet supported, return whether element is a string.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        sage: cc.is_element(PerfectMatching([[1,2],[3,4],[5,6]]))           # optional -- internet
        True

        sage: cc.is_element(SetPartition([[1,2],[3,4],[5,6]]))              # optional -- internet
        False

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        >>> cc.is_element(PerfectMatching([[Integer(1),Integer(2)],[Integer(3),Integer(4)],[Integer(5),Integer(6)]]))           # optional -- internet
        True

        >>> cc.is_element(SetPartition([[Integer(1),Integer(2)],[Integer(3),Integer(4)],[Integer(5),Integer(6)]]))              # optional -- internet
        False

  is_supported()

    Check whether the collection is fully supported by the interface.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: FindStatCollection(1).is_supported()                          # optional -- internet
        True

        sage: FindStatCollection(24).is_supported()                         # optional -- internet, random
        False

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> FindStatCollection(Integer(1)).is_supported()                          # optional -- internet
        True

        >>> FindStatCollection(Integer(24)).is_supported()                         # optional -- internet, random
        False

  levels_with_sizes()

    Return a dictionary from levels to level sizes.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        sage: cc.levels_with_sizes()                                        # optional -- internet
        {2: 1, 4: 3, 6: 15, 8: 105, 10: 945}

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> cc = FindStatCollection("Perfect Matchings")                  # optional -- internet
        >>> cc.levels_with_sizes()                                        # optional -- internet
        {2: 1, 4: 3, 6: 15, 8: 105, 10: 945}

  name(style='singular')

    Return the name of the FindStat collection.

    INPUT:

    - `style` – string (default: `'singular'`); can be `'singular'`, or `'plural'`

    OUTPUT: the name of the FindStat collection, in singular or in plural

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: FindStatCollection("Binary trees").name()                     # optional -- internet
        'Binary tree'

        sage: FindStatCollection("Binary trees").name(style='plural')       # optional -- internet
        'Binary trees'

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> FindStatCollection("Binary trees").name()                     # optional -- internet
        'Binary tree'

        >>> FindStatCollection("Binary trees").name(style='plural')       # optional -- internet
        'Binary trees'

  to_string()

    Return a function that returns a FindStat representation given an object.

    If the collection is not yet supported, return the identity.

    OUTPUT:

    The function that produces the string representation as needed by the FindStat search webpage.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCollection
        sage: p = Poset((range(3), [[0, 1], [1, 2]]))                       # optional -- internet
        sage: c = FindStatCollection("Posets")                              # optional -- internet
        sage: c.to_string()(p)                                              # optional -- internet
        '([(0, 1), (1, 2)], 3)'

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCollection
        >>> p = Poset((range(Integer(3)), [[Integer(0), Integer(1)], [Integer(1), Integer(2)]]))                       # optional -- internet
        >>> c = FindStatCollection("Posets")                              # optional -- internet
        >>> c.to_string()(p)                                              # optional -- internet
        '([(0, 1), (1, 2)], 3)'

class sage.databases.findstat.FindStatCollections

  Bases: `UniqueRepresentation`, `Parent`

  The class of FindStat collections.

  The elements of this class are combinatorial collections in FindStat as of January 2020. If a new collection was added to the web service since then, the dictionary `_SupportedFindStatCollections` in this module has to be updated accordingly.

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatCollections
      sage: sorted(c for c in FindStatCollections() if c.is_supported())      # optional -- internet
      [Cc0001: Permutations,
       Cc0002: Integer partitions,
       Cc0005: Dyck paths,
       Cc0006: Integer compositions,
       Cc0007: Standard tableaux,
       Cc0009: Set partitions,
       Cc0010: Binary trees,
       Cc0012: Perfect matchings,
       Cc0013: Cores,
       Cc0014: Posets,
       Cc0017: Alternating sign matrices,
       Cc0018: Gelfand-Tsetlin patterns,
       Cc0019: Semistandard tableaux,
       Cc0020: Graphs,
       Cc0021: Ordered trees,
       Cc0022: Finite Cartan types,
       Cc0023: Parking functions,
       Cc0024: Binary words,
       Cc0025: Plane partitions,
       Cc0026: Decorated permutations,
       Cc0027: Signed permutations,
       Cc0028: Skew partitions,
       Cc0029: Lattices,
       Cc0030: Ordered set partitions]

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatCollections
      >>> sorted(c for c in FindStatCollections() if c.is_supported())      # optional -- internet
      [Cc0001: Permutations,
       Cc0002: Integer partitions,
       Cc0005: Dyck paths,
       Cc0006: Integer compositions,
       Cc0007: Standard tableaux,
       Cc0009: Set partitions,
       Cc0010: Binary trees,
       Cc0012: Perfect matchings,
       Cc0013: Cores,
       Cc0014: Posets,
       Cc0017: Alternating sign matrices,
       Cc0018: Gelfand-Tsetlin patterns,
       Cc0019: Semistandard tableaux,
       Cc0020: Graphs,
       Cc0021: Ordered trees,
       Cc0022: Finite Cartan types,
       Cc0023: Parking functions,
       Cc0024: Binary words,
       Cc0025: Plane partitions,
       Cc0026: Decorated permutations,
       Cc0027: Signed permutations,
       Cc0028: Skew partitions,
       Cc0029: Lattices,
       Cc0030: Ordered set partitions]

  Element

    alias of `FindStatCollection`

class sage.databases.findstat.FindStatCombinatorialMap

  Bases: `SageObject`

  A class serving as common ancestor of `FindStatStatistic` and `FindStatCompoundStatistic`.

class sage.databases.findstat.FindStatCombinatorialStatistic

  Bases: `SageObject`

  A class providing methods to retrieve the first terms of a statistic.

  This class provides methods applicable to instances of `FindStatStatistic`, `FindStatCompoundStatistic` and `FindStatStatisticQuery`.

  first_terms()

    Return the first terms of the (compound) statistic as a dictionary.

    OUTPUT:

    A dictionary from Sage objects representing an element of the appropriate collection to integers.

    This method is overridden in `FindStatStatisticQuery`.

    EXAMPLES:

    Sage

        sage: findstat(41).first_terms()[PerfectMatching([(1,6),(2,5),(3,4)])]        # optional -- internet
        3

    Python

        >>> from sage.all import *
        >>> findstat(Integer(41)).first_terms()[PerfectMatching([(Integer(1),Integer(6)),(Integer(2),Integer(5)),(Integer(3),Integer(4))])]        # optional -- internet
        3

  first_terms_str(max_values=1200)

    Return the first terms of the statistic in the format needed for a FindStat query.

    OUTPUT:

    A string, where each line is of the form `object => value`, where `object` is the string representation of an element of the appropriate collection as used by FindStat and value is an integer.

    EXAMPLES:

    Sage

        sage: print(findstat(41).first_terms_str(max_values=4))             # optional -- internet
        [(1,2)] => 0
        [(1,2),(3,4)] => 0
        [(1,3),(2,4)] => 0
        [(1,4),(2,3)] => 1

    Python

        >>> from sage.all import *
        >>> print(findstat(Integer(41)).first_terms_str(max_values=Integer(4)))             # optional -- internet
        [(1,2)] => 0
        [(1,2),(3,4)] => 0
        [(1,3),(2,4)] => 0
        [(1,4),(2,3)] => 1

  generating_functions(style='polynomial', max_values=1200)

    Return the generating functions of the statistic as a dictionary.

    The keys of this dictionary are the levels for which the generating function of the statistic can be computed from the known data. Each value represents a generating function for one level, as a polynomial, as a dictionary, or as a list of coefficients.

    INPUT:

    - `style` – string (default: `'polynomial'`); can be `'polynomial'`, `'dictionary'`, or `'list'`

    OUTPUT:

    - if `style` is `'polynomial'`, the generating function is returned as a polynomial

    - if `style` is `'dictionary'`, the generating function is returned as a dictionary representing the monomials of the generating function

    - if `style` is `'list'`, the generating function is returned as a list of coefficients of the generating function. In this case, leading and trailing zeros are omitted.

    EXAMPLES:

    Sage

        sage: st = findstat(41)                                             # optional -- internet
        sage: st.generating_functions()                                     # optional -- internet
        {2: 1,
         4: q + 2,
         6: q^3 + 3*q^2 + 6*q + 5,
         8: q^6 + 4*q^5 + 10*q^4 + 20*q^3 + 28*q^2 + 28*q + 14}

        sage: st.generating_functions(style='dictionary')                   # optional -- internet
        {2: {0: 1},
         4: {0: 2, 1: 1},
         6: {0: 5, 1: 6, 2: 3, 3: 1},
         8: {0: 14, 1: 28, 2: 28, 3: 20, 4: 10, 5: 4, 6: 1}}

        sage: st.generating_functions(style='list')                         # optional -- internet
        {2: [1], 4: [2, 1], 6: [5, 6, 3, 1], 8: [14, 28, 28, 20, 10, 4, 1]}

    Python

        >>> from sage.all import *
        >>> st = findstat(Integer(41))                                             # optional -- internet
        >>> st.generating_functions()                                     # optional -- internet
        {2: 1,
         4: q + 2,
         6: q^3 + 3*q^2 + 6*q + 5,
         8: q^6 + 4*q^5 + 10*q^4 + 20*q^3 + 28*q^2 + 28*q + 14}

        >>> st.generating_functions(style='dictionary')                   # optional -- internet
        {2: {0: 1},
         4: {0: 2, 1: 1},
         6: {0: 5, 1: 6, 2: 3, 3: 1},
         8: {0: 14, 1: 28, 2: 28, 3: 20, 4: 10, 5: 4, 6: 1}}

        >>> st.generating_functions(style='list')                         # optional -- internet
        {2: [1], 4: [2, 1], 6: [5, 6, 3, 1], 8: [14, 28, 28, 20, 10, 4, 1]}

  oeis_search(search_size=32, verbose=True)

    Search the OEIS for the generating function of the statistic.

    INPUT:

    - `search_size` – (default: 32) the number of integers in the sequence. If this is chosen too big, the OEIS result may be corrupted.

    - `verbose` – boolean (default: `True`); if `True`, some information about the search are printed

    OUTPUT: a tuple of OEIS sequences, see `sage.databases.oeis.OEIS.find_by_description()` for more information

    EXAMPLES:

    Sage

        sage: st = findstat(41)                                             # optional -- internet

        sage: st.oeis_search()                                              # optional -- internet
        Searching the OEIS for "1  2,1  5,6,3,1  14,28,28,20,10,4,1"
        0: A067311: Triangle read by rows: T(n,k) gives number of ways of arranging n chords on a circle with k simple intersections ...

    Python

        >>> from sage.all import *
        >>> st = findstat(Integer(41))                                             # optional -- internet

        >>> st.oeis_search()                                              # optional -- internet
        Searching the OEIS for "1  2,1  5,6,3,1  14,28,28,20,10,4,1"
        0: A067311: Triangle read by rows: T(n,k) gives number of ways of arranging n chords on a circle with k simple intersections ...

class sage.databases.findstat.FindStatCompoundMap(id, domain=None, codomain=None, check=True)

  Bases: `Element`, `FindStatCombinatorialMap`

  Initialize a compound statistic.

  INPUT:

  - `id` – a padded identifier

  - `domain` – (optional), the domain of the compound map

  - `codomain` – (optional), the codomain of the compound map

  - `check` – whether to check that domains and codomains fit

  If domain and codomain are given and `check` is `False`, they are not fetched from FindStat.

  If `id` is the empty string, `domain` must be provided, and the identity map on this collection is returned.

  browse()

    Open the FindStat web page of the compound map in a browser.

    EXAMPLES:

    Sage

        sage: findmap(62).browse()                                          # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> findmap(Integer(62)).browse()                                          # optional -- webbrowser

  codomain()

    Return the codomain of the compound map.

    EXAMPLES:

    Sage

        sage: findmap("Mp00099oMp00127").codomain()                         # optional -- internet
        Cc0005: Dyck paths

    Python

        >>> from sage.all import *
        >>> findmap("Mp00099oMp00127").codomain()                         # optional -- internet
        Cc0005: Dyck paths

  domain()

    Return the domain of the compound map.

    EXAMPLES:

    Sage

        sage: findmap("Mp00099oMp00127").domain()                           # optional -- internet
        Cc0001: Permutations

    Python

        >>> from sage.all import *
        >>> findmap("Mp00099oMp00127").domain()                           # optional -- internet
        Cc0001: Permutations

  id_str()

    Return the padded identifier of the compound map.

    EXAMPLES:

    Sage

        sage: findmap("Mp00099oMp00127").id_str()                           # optional -- internet
        'Mp00099oMp00127'

    Python

        >>> from sage.all import *
        >>> findmap("Mp00099oMp00127").id_str()                           # optional -- internet
        'Mp00099oMp00127'

  info()

    Print a detailed explanation of the compound map.

    EXAMPLES:

    Sage

        sage: findmap("Mp00099oMp00127").info()                             # optional -- internet
            Mp00127: left-to-right-maxima to Dyck path: Permutations -> Dyck paths
            Mp00099: bounce path: Dyck paths -> Dyck paths

    Python

        >>> from sage.all import *
        >>> findmap("Mp00099oMp00127").info()                             # optional -- internet
            Mp00127: left-to-right-maxima to Dyck path: Permutations -> Dyck paths
            Mp00099: bounce path: Dyck paths -> Dyck paths

  maps()

    Return the maps occurring in the compound map as a list.

    EXAMPLES:

    Sage

        sage: findmap("Mp00099oMp00127").maps()                             # optional -- internet
        [Mp00127: left-to-right-maxima to Dyck path, Mp00099: bounce path]

    Python

        >>> from sage.all import *
        >>> findmap("Mp00099oMp00127").maps()                             # optional -- internet
        [Mp00127: left-to-right-maxima to Dyck path, Mp00099: bounce path]

class sage.databases.findstat.FindStatCompoundStatistic(id, domain=None, check=True)

  Bases: `Element`, `FindStatCombinatorialStatistic`

  Initialize a compound statistic.

  A compound statistic is a sequence of maps followed by a statistic.

  INPUT:

  - `id` – a padded identifier

  - `domain` – (optional), the domain of the compound statistic

  - `check` – whether to check that domains and codomains fit

  If the domain is given and `check` is `False`, it is not fetched from FindStat.

  browse()

    Open the FindStat web page of the compound statistic in a browser.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatCompoundStatistic
        sage: FindStatCompoundStatistic("St000042oMp00116").browse()        # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatCompoundStatistic
        >>> FindStatCompoundStatistic("St000042oMp00116").browse()        # optional -- webbrowser

  compound_map()

    Return the compound map which is part of the compound statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000051oMp00061oMp00069").compound_map()           # optional -- internet
        Mp00061oMp00069

    Python

        >>> from sage.all import *
        >>> findstat("St000051oMp00061oMp00069").compound_map()           # optional -- internet
        Mp00061oMp00069

  domain()

    Return the domain of the compound statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000042oMp00116").domain()                         # optional -- internet
        Cc0012: Perfect matchings

    Python

        >>> from sage.all import *
        >>> findstat("St000042oMp00116").domain()                         # optional -- internet
        Cc0012: Perfect matchings

  id_str()

    Return the padded identifier of the compound statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000042oMp00116").id_str()                         # optional -- internet
        'St000042oMp00116'

    Python

        >>> from sage.all import *
        >>> findstat("St000042oMp00116").id_str()                         # optional -- internet
        'St000042oMp00116'

  info()

    Print a detailed description of the compound statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000042oMp00116").info()                           # optional -- internet
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings
            St000042: The number of crossings of a perfect matching.

    Python

        >>> from sage.all import *
        >>> findstat("St000042oMp00116").info()                           # optional -- internet
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings
            St000042: The number of crossings of a perfect matching.

  statistic()

    Return the statistic of the compound statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000041oMp00116").statistic()                      # optional -- internet
        St000041: The number of nestings of a perfect matching.

    Python

        >>> from sage.all import *
        >>> findstat("St000041oMp00116").statistic()                      # optional -- internet
        St000041: The number of nestings of a perfect matching.

class sage.databases.findstat.FindStatFunction(id, data=None, function=None)

  Bases: `SageObject`

  A class providing the common methods of `FindStatMap` and `FindStatStatistic`.

  This class provides methods to access and modify properties of a single statistic or map of the FindStat database.

  description()

    Return the description of the statistic or map.

    OUTPUT: string; for statistics, the first line is used as name

    EXAMPLES:

    Sage

        sage: print(findstat(51).description())                             # optional -- internet
        The size of the left subtree of a binary tree.

    Python

        >>> from sage.all import *
        >>> print(findstat(Integer(51)).description())                             # optional -- internet
        The size of the left subtree of a binary tree.

  domain()

    Return the FindStat domain of the statistic or map.

    OUTPUT:

    The domain of the statistic or map as an instance of `FindStatCollection`.

    EXAMPLES:

    Sage

        sage: findstat(51).domain()                                         # optional -- internet
        Cc0010: Binary trees

        sage: findmap(62).domain()                                          # optional -- internet
        Cc0001: Permutations

    Python

        >>> from sage.all import *
        >>> findstat(Integer(51)).domain()                                         # optional -- internet
        Cc0010: Binary trees

        >>> findmap(Integer(62)).domain()                                          # optional -- internet
        Cc0001: Permutations

  id()

    Return the FindStat identifier of the statistic or map.

    OUTPUT: the FindStat identifier of the statistic or map, as an integer

    EXAMPLES:

    Sage

        sage: findstat(51).id()                                             # optional -- internet
        51

    Python

        >>> from sage.all import *
        >>> findstat(Integer(51)).id()                                             # optional -- internet
        51

  id_str()

    Return the FindStat identifier of the statistic or map.

    OUTPUT: the FindStat identifier of the statistic or map, as a string

    EXAMPLES:

    Sage

        sage: findstat(51).id_str()                                         # optional -- internet
        'St000051'

    Python

        >>> from sage.all import *
        >>> findstat(Integer(51)).id_str()                                         # optional -- internet
        'St000051'

  name()

    Return the name of the statistic or map.

    OUTPUT:

    A string. For statistics, this is just the first line of the description.

    EXAMPLES:

    Sage

        sage: findstat(51).name()                                           # optional -- internet
        'The size of the left subtree of a binary tree.'

    Python

        >>> from sage.all import *
        >>> findstat(Integer(51)).name()                                           # optional -- internet
        'The size of the left subtree of a binary tree.'

  references()

    Return the references associated with the statistic or map.

    OUTPUT:

    An instance of `sage.databases.oeis.FancyTuple`, each item corresponds to a reference.

    EXAMPLES:

    Sage

        sage: findstat(41).references()                                     # optional -- internet
        0: [1]  de Médicis, A., Viennot, X. G., Moments des $q$-polynômes de Laguerre et la bijection de Foata-Zeilberger [[MathSciNet:1288802]]
        1: [2]  Simion, R., Stanton, D., Octabasic Laguerre polynomials and permutation statistics [[MathSciNet:1418763]]

    Python

        >>> from sage.all import *
        >>> findstat(Integer(41)).references()                                     # optional -- internet
        0: [1]  de Médicis, A., Viennot, X. G., Moments des $q$-polynômes de Laguerre et la bijection de Foata-Zeilberger [[MathSciNet:1288802]]
        1: [2]  Simion, R., Stanton, D., Octabasic Laguerre polynomials and permutation statistics [[MathSciNet:1418763]]

  references_raw()

    Return the unrendered references associated with the statistic or map.

    EXAMPLES:

    Sage

        sage: print(findstat(41).references_raw())                          # optional -- internet
        [1]  [[MathSciNet:1288802]]
        [2]  [[MathSciNet:1418763]]

    Python

        >>> from sage.all import *
        >>> print(findstat(Integer(41)).references_raw())                          # optional -- internet
        [1]  [[MathSciNet:1288802]]
        [2]  [[MathSciNet:1418763]]

  reset()

    Discard all modification of the statistic or map.

    EXAMPLES:

    Sage

        sage: s = findmap(62)                                               # optional -- internet
        sage: s.set_name(u"Möbius"); s                                      # optional -- internet
        Mp00062(modified): Möbius
        sage: s.reset(); s                                                  # optional -- internet
        Mp00062: Lehmer-code to major-code bijection

    Python

        >>> from sage.all import *
        >>> s = findmap(Integer(62))                                               # optional -- internet
        >>> s.set_name(u"Möbius"); s                                      # optional -- internet
        Mp00062(modified): Möbius
        >>> s.reset(); s                                                  # optional -- internet
        Mp00062: Lehmer-code to major-code bijection

  sage_code()

    Return the Sage code associated with the statistic or map.

    OUTPUT: an empty string or a string of the form:

        def statistic(x):
            ...

    or:

        def mapping(x):
            ...

    EXAMPLES:

    Sage

        sage: print(findstat(51).sage_code())                               # optional -- internet
        def statistic(T):
            return T[0].node_number()

    Python

        >>> from sage.all import *
        >>> print(findstat(Integer(51)).sage_code())                               # optional -- internet
        def statistic(T):
            return T[0].node_number()

  set_description(value)

    Set the description of the statistic or map.

    INPUT:

    - `value` – string; for statistics, this is the name of the statistic followed by its description on a separate line

    This information is used when submitting the statistic or map with `submit()`.

    EXAMPLES:

    Sage

        sage: q = findstat([(d, randint(1, 1000)) for d in DyckWords(4)])             # optional -- internet
        sage: q.set_description("Random values on Dyck paths.\nNot for submission.")  # optional -- internet
        sage: print(q.description())                                                  # optional -- internet
        Random values on Dyck paths.
        Not for submission.

    Python

        >>> from sage.all import *
        >>> q = findstat([(d, randint(Integer(1), Integer(1000))) for d in DyckWords(Integer(4))])             # optional -- internet
        >>> q.set_description("Random values on Dyck paths.\nNot for submission.")  # optional -- internet
        >>> print(q.description())                                                  # optional -- internet
        Random values on Dyck paths.
        Not for submission.

  set_references_raw(value)

    Set the references associated with the statistic or map.

    INPUT:

    - `value` – string; each reference should be on a single line, and consist of one or more links to the same item

    FindStat will automatically resolve the links, if possible. A complete list of supported services can be found at <https://findstat.org/NewStatistic>.

    This information is used when submitting the statistic with `submit()`.

    EXAMPLES:

    Sage

        sage: q = findstat([(d, randint(1, 1000)) for d in DyckWords(4)])   # optional -- internet
        sage: q.set_references_raw("[[arXiv:1102.4226]]\n[[oeis:A000001]]") # optional -- internet
        sage: q.references()                                                # optional -- internet
        0: [[arXiv:1102.4226]]
        1: [[oeis:A000001]]

    Python

        >>> from sage.all import *
        >>> q = findstat([(d, randint(Integer(1), Integer(1000))) for d in DyckWords(Integer(4))])   # optional -- internet
        >>> q.set_references_raw("[[arXiv:1102.4226]]\n[[oeis:A000001]]") # optional -- internet
        >>> q.references()                                                # optional -- internet
        0: [[arXiv:1102.4226]]
        1: [[oeis:A000001]]

  set_sage_code(value)

    Set the code associated with the statistic or map.

    INPUT:

    - `value` – string; SageMath code producing the values of the statistic or map

    Contributors are encouraged to submit code for statistics using `FindStatStatistic.set_code()`. Modifying the “verified” SageMath code using this method is restricted to members of the FindStatCrew, for all other contributors this method has no effect.

    EXAMPLES:

    Sage

        sage: q = findstat([(d, randint(1,1000)) for d in DyckWords(4)])              # optional -- internet
        sage: q.set_sage_code("def statistic(x):\n    return randint(1, 1000)")       # optional -- internet
        sage: print(q.sage_code())                                                    # optional -- internet
        def statistic(x):
            return randint(1, 1000)

    Python

        >>> from sage.all import *
        >>> q = findstat([(d, randint(Integer(1),Integer(1000))) for d in DyckWords(Integer(4))])              # optional -- internet
        >>> q.set_sage_code("def statistic(x):\n    return randint(1, 1000)")       # optional -- internet
        >>> print(q.sage_code())                                                    # optional -- internet
        def statistic(x):
            return randint(1, 1000)

class sage.databases.findstat.FindStatMap(parent, id)

  Bases: `Element`, `FindStatFunction`, `FindStatCombinatorialMap`

  A FindStat map.

  `FindStatMap` is a class representing a combinatorial map available in the FindStat database.

  This class provides methods to inspect various properties of these maps, in particular `code()`.

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatMap
      sage: FindStatMap(116)                                                  # optional -- internet
      Mp00116: Kasraoui-Zeng

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatMap
      >>> FindStatMap(Integer(116))                                                  # optional -- internet
      Mp00116: Kasraoui-Zeng

  See also

  `FindStatMaps`

  browse()

    Open the FindStat web page of the map in a browser.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMap
        sage: FindStatMap(116).browse()                                     # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMap
        >>> FindStatMap(Integer(116)).browse()                                     # optional -- webbrowser

  codomain()

    Return the FindStat collection which is the codomain of the map.

    OUTPUT: the codomain of the map as a `FindStatCollection`

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMap               # optional -- internet
        sage: FindStatMap(27).codomain()                                    # optional -- internet
        Cc0002: Integer partitions

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMap               # optional -- internet
        >>> FindStatMap(Integer(27)).codomain()                                    # optional -- internet
        Cc0002: Integer partitions

  edit()

    alias of `submit()`.

  info()

    Print a detailed description of the map.

    EXAMPLES:

    Sage

        sage: findmap("Mp00116").info()                                     # optional -- internet
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings

    Python

        >>> from sage.all import *
        >>> findmap("Mp00116").info()                                     # optional -- internet
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings

  properties_raw()

    Return the properties of the map.

    OUTPUT: the properties as a string

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMap               # optional -- internet
        sage: FindStatMap(61).properties_raw()                              # optional -- internet
        'surjective, graded'

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMap               # optional -- internet
        >>> FindStatMap(Integer(61)).properties_raw()                              # optional -- internet
        'surjective, graded'

  set_name(value)

    Set the name of the map.

    INPUT:

    - `value` – string; the new name of the map

    This information is used when submitting the map with `submit()`.

  set_properties_raw(value)

    Set the properties of the map.

    EXAMPLES:

    Sage

        sage: # optional - internet
        sage: from sage.databases.findstat import FindStatMap
        sage: FindStatMap(61).set_properties_raw('surjective')
        sage: FindStatMap(61).properties_raw()
        'surjective'
        sage: FindStatMap(61)
        Mp00061(modified): to increasing tree
        sage: FindStatMap(61).reset()
        sage: FindStatMap(61)
        Mp00061: to increasing tree

    Python

        >>> from sage.all import *
        >>> # optional - internet
        >>> from sage.databases.findstat import FindStatMap
        >>> FindStatMap(Integer(61)).set_properties_raw('surjective')
        >>> FindStatMap(Integer(61)).properties_raw()
        'surjective'
        >>> FindStatMap(Integer(61))
        Mp00061(modified): to increasing tree
        >>> FindStatMap(Integer(61)).reset()
        >>> FindStatMap(Integer(61))
        Mp00061: to increasing tree

  submit()

    Open the FindStat web page for editing the map in a browser.

class sage.databases.findstat.FindStatMapQuery(data=None, values_of=None, distribution_of=None, domain=None, codomain=None, known_terms=None, function=None, depth=2, debug=False)

  Bases: `FindStatMap`

  A class representing a query for FindStat (compound) maps.

class sage.databases.findstat.FindStatMaps(domain=None, codomain=None)

  Bases: `UniqueRepresentation`, `Parent`

  The class of FindStat maps.

  The elements of this class are combinatorial maps currently in FindStat.

  EXAMPLES:

  We can print a sample map for each domain and codomain:

  Sage

      sage: from sage.databases.findstat import FindStatCollections, FindStatMaps
      sage: ccs = sorted(FindStatCollections())[:3]                           # optional -- internet
      sage: for cc_dom in ccs:                                                # optional -- internet
      ....:     for cc_codom in ccs:
      ....:         print(cc_dom.name(style='plural') + " -> " + cc_codom.name(style='plural'))
      ....:         try:
      ....:             print("    " + next(iter(FindStatMaps(cc_dom, cc_codom))).name())
      ....:         except StopIteration:
      ....:             pass
      Permutations -> Permutations
          Lehmer-code to major-code bijection
      Permutations -> Integer partitions
          Robinson-Schensted tableau shape
      Permutations -> Dyck paths
          left-to-right-maxima to Dyck path
      Integer partitions -> Permutations
      Integer partitions -> Integer partitions
          conjugate
      Integer partitions -> Dyck paths
          to Dyck path
      Dyck paths -> Permutations
          to non-crossing permutation
      Dyck paths -> Integer partitions
          to partition
      Dyck paths -> Dyck paths
          reverse

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatCollections, FindStatMaps
      >>> ccs = sorted(FindStatCollections())[:Integer(3)]                           # optional -- internet
      >>> for cc_dom in ccs:                                                # optional -- internet
      ...     for cc_codom in ccs:
      ...         print(cc_dom.name(style='plural') + " -> " + cc_codom.name(style='plural'))
      ...         try:
      ...             print("    " + next(iter(FindStatMaps(cc_dom, cc_codom))).name())
      ...         except StopIteration:
      ...             pass
      Permutations -> Permutations
          Lehmer-code to major-code bijection
      Permutations -> Integer partitions
          Robinson-Schensted tableau shape
      Permutations -> Dyck paths
          left-to-right-maxima to Dyck path
      Integer partitions -> Permutations
      Integer partitions -> Integer partitions
          conjugate
      Integer partitions -> Dyck paths
          to Dyck path
      Dyck paths -> Permutations
          to non-crossing permutation
      Dyck paths -> Integer partitions
          to partition
      Dyck paths -> Dyck paths
          reverse

  Element

    alias of `FindStatMap`

class sage.databases.findstat.FindStatMatchingMap(matching_map, quality, domain=None, codomain=None)

  Bases: `FindStatCompoundMap`

  Initialize a FindStat map match.

  INPUT:

  - `matching_map` – a compound map identifier

  - `quality` – the quality of the match, as provided by FindStat

  - `domain` – (optional) the domain of the compound map

  - `codomain` – (optional), the codomain of the compound map

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatMatchingMap
      sage: FindStatMatchingMap("Mp00099oMp00127", [83])                  # optional -- internet
      Mp00099oMp00127 (quality [83])

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatMatchingMap
      >>> FindStatMatchingMap("Mp00099oMp00127", [Integer(83)])                  # optional -- internet
      Mp00099oMp00127 (quality [83])

  info()

    Print a detailed explanation of the match.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMatchingMap
        sage: FindStatMatchingMap("Mp00099oMp00127", [83]).info()           # optional -- internet
        your input matches
            Mp00127: left-to-right-maxima to Dyck path: Permutations -> Dyck paths
            Mp00099: bounce path: Dyck paths -> Dyck paths

        among the values you sent, 83 percent are actually in the database

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMatchingMap
        >>> FindStatMatchingMap("Mp00099oMp00127", [Integer(83)]).info()           # optional -- internet
        your input matches
            Mp00127: left-to-right-maxima to Dyck path: Permutations -> Dyck paths
            Mp00099: bounce path: Dyck paths -> Dyck paths
        <BLANKLINE>
        among the values you sent, 83 percent are actually in the database

  quality()

    Return the quality of the match, as provided by FindStat.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMatchingMap
        sage: FindStatMatchingMap("Mp00099oMp00127", [83]).quality()        # optional -- internet
        [83]

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMatchingMap
        >>> FindStatMatchingMap("Mp00099oMp00127", [Integer(83)]).quality()        # optional -- internet
        [83]

class sage.databases.findstat.FindStatMatchingStatistic(matching_statistic, offset, quality, domain=None)

  Bases: `FindStatCompoundStatistic`

  Initialize a FindStat statistic match.

  INPUT:

  - `matching_statistic` – a compound statistic identifier

  - `offset` – the offset of the values, as provided by FindStat

  - `quality` – the quality of the match, as provided by FindStat

  - `domain` – (optional) the domain of the compound statistic

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatMatchingStatistic
      sage: FindStatMatchingStatistic("St000042oMp00116", 1, [17, 83])    # optional -- internet
      St000042oMp00116 with offset 1 (quality [17, 83])

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatMatchingStatistic
      >>> FindStatMatchingStatistic("St000042oMp00116", Integer(1), [Integer(17), Integer(83)])    # optional -- internet
      St000042oMp00116 with offset 1 (quality [17, 83])

  info()

    Print a detailed explanation of the match.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMatchingStatistic
        sage: r = FindStatMatchingStatistic("St000042oMp00116", 1, [17, 83])          # optional -- internet
        sage: r.info()                                                      # optional -- internet
        after adding 1 to every value
        and applying
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings
        to the objects (see `.compound_map()` for details)

        your input matches
            St000042: The number of crossings of a perfect matching.

        among the values you sent, 17 percent are actually in the database,
        among the distinct values you sent, 83 percent are actually in the database

        sage: r = FindStatMatchingStatistic("St000042", 1, [17, 83])        # optional -- internet
        sage: r.info()                                                      # optional -- internet
        after adding 1 to every value

        your input matches
            St000042: The number of crossings of a perfect matching.

        among the values you sent, 17 percent are actually in the database,
        among the distinct values you sent, 83 percent are actually in the database

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMatchingStatistic
        >>> r = FindStatMatchingStatistic("St000042oMp00116", Integer(1), [Integer(17), Integer(83)])          # optional -- internet
        >>> r.info()                                                      # optional -- internet
        after adding 1 to every value
        and applying
            Mp00116: Kasraoui-Zeng: Perfect matchings -> Perfect matchings
        to the objects (see `.compound_map()` for details)
        <BLANKLINE>
        your input matches
            St000042: The number of crossings of a perfect matching.
        <BLANKLINE>
        among the values you sent, 17 percent are actually in the database,
        among the distinct values you sent, 83 percent are actually in the database

        >>> r = FindStatMatchingStatistic("St000042", Integer(1), [Integer(17), Integer(83)])        # optional -- internet
        >>> r.info()                                                      # optional -- internet
        after adding 1 to every value
        <BLANKLINE>
        your input matches
            St000042: The number of crossings of a perfect matching.
        <BLANKLINE>
        among the values you sent, 17 percent are actually in the database,
        among the distinct values you sent, 83 percent are actually in the database

  offset()

    Return the offset which has to be added to each value of the compound statistic to obtain the desired value.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMatchingStatistic
        sage: r = FindStatMatchingStatistic("St000042oMp00116", 1, [17, 83])          # optional -- internet
        sage: r.offset()                                                    # optional -- internet
        1

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMatchingStatistic
        >>> r = FindStatMatchingStatistic("St000042oMp00116", Integer(1), [Integer(17), Integer(83)])          # optional -- internet
        >>> r.offset()                                                    # optional -- internet
        1

  quality()

    Return the quality of the match, as provided by FindStat.

    The quality of a statistic match is a pair of percentages \((q_a, q_d)\), where \(q_a\) is the percentage of `(object, value)` pairs that are in the database among those which were sent to FindStat, and \(q_d\) is the percentage of `(object, value)` pairs with distinct values in the database among those which were sent to FindStat.

    EXAMPLES:

    Sage

        sage: from sage.databases.findstat import FindStatMatchingStatistic
        sage: r = FindStatMatchingStatistic("St000042oMp00116", 1, [17, 83])          # optional -- internet
        sage: r.quality()                                                   # optional -- internet
        [17, 83]

    Python

        >>> from sage.all import *
        >>> from sage.databases.findstat import FindStatMatchingStatistic
        >>> r = FindStatMatchingStatistic("St000042oMp00116", Integer(1), [Integer(17), Integer(83)])          # optional -- internet
        >>> r.quality()                                                   # optional -- internet
        [17, 83]

class sage.databases.findstat.FindStatStatistic(parent, id)

  Bases: `Element`, `FindStatFunction`, `FindStatCombinatorialStatistic`

  A FindStat statistic.

  `FindStatStatistic` is a class representing a combinatorial statistic available in the FindStat database.

  This class provides methods to inspect and update various properties of these statistics.

  EXAMPLES:

  Sage

      sage: from sage.databases.findstat import FindStatStatistic
      sage: FindStatStatistic(41)                                             # optional -- internet
      St000041: The number of nestings of a perfect matching.

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatStatistic
      >>> FindStatStatistic(Integer(41))                                             # optional -- internet
      St000041: The number of nestings of a perfect matching.

  See also

  `FindStatStatistics`

  browse()

    Open the FindStat web page of the statistic in a browser.

    EXAMPLES:

    Sage

        sage: findstat(41).browse()                                         # optional -- webbrowser

    Python

        >>> from sage.all import *
        >>> findstat(Integer(41)).browse()                                         # optional -- webbrowser

  code()

    Return the code associated with the statistic or map.

    OUTPUT: string

    Contributors are encouraged to submit Sage code in the form:

        def statistic(x):
            ...

    but the string may also contain code for other computer algebra systems.

    EXAMPLES:

    Sage

        sage: print(findstat(41).code())                                    # optional -- internet
        def statistic(x):
            return len(x.nestings())

        sage: print(findstat(118).code())                                   # optional -- internet
        (* in Mathematica *)
        tree = {{{{}, {}}, {{}, {}}}, {{{}, {}}, {{}, {}}}};
        Count[tree, {{___}, {{___}, {{___}, {___}}}}, {0, Infinity}]

    Python

        >>> from sage.all import *
        >>> print(findstat(Integer(41)).code())                                    # optional -- internet
        def statistic(x):
            return len(x.nestings())

        >>> print(findstat(Integer(118)).code())                                   # optional -- internet
        (* in Mathematica *)
        tree = {{{{}, {}}, {{}, {}}}, {{{}, {}}, {{}, {}}}};
        Count[tree, {{___}, {{___}, {{___}, {___}}}}, {0, Infinity}]

  edit(max_values=1200)

    alias of `submit()`.

  info()

    Print a detailed description of the statistic.

    EXAMPLES:

    Sage

        sage: findstat("St000042").info()                                   # optional -- internet
            St000042: The number of crossings of a perfect matching.

    Python

        >>> from sage.all import *
        >>> findstat("St000042").info()                                   # optional -- internet
            St000042: The number of crossings of a perfect matching.

  set_code(value)

    Set the code associated with the statistic.

    INPUT:

    - `value` – string; code producing the values of the statistic

    Contributors are encouraged to submit SageMath code in the form:

        def statistic(x):
            ...

    However, code for any other platform is accepted also.

    This information is used when submitting the statistic with `submit()`.

    EXAMPLES:

    Sage

        sage: q = findstat([(d, randint(1,1000)) for d in DyckWords(4)])    # optional -- internet
        sage: q.set_code("def statistic(x):\n    return randint(1,1000)")   # optional -- internet
        sage: print(q.code())                                               # optional -- internet
        def statistic(x):
            return randint(1,1000)

    Python

        >>> from sage.all import *
        >>> q = findstat([(d, randint(Integer(1),Integer(1000))) for d in DyckWords(Integer(4))])    # optional -- internet
        >>> q.set_code("def statistic(x):\n    return randint(1,1000)")   # optional -- internet
        >>> print(q.code())                                               # optional -- internet
        def statistic(x):
            return randint(1,1000)

  set_first_terms(values)

    Update the first terms of the statistic.

    INPUT:

    - `values` – list of pairs of the form `(object, value)` where `object` is a Sage object representing an element of the appropriate collection and `value` is an integer

    This information is used when submitting the statistic with `submit()`.

    Warning

    This method cannot check whether the given values are actually correct. Moreover, it does not even perform any sanity checks.

  submit(max_values=1200)

    Open the FindStat web page for editing the statistic or submitting a new statistic in a browser.

class sage.databases.findstat.FindStatStatisticQuery(data=None, values_of=None, distribution_of=None, domain=None, known_terms=None, function=None, depth=2, debug=False)

  Bases: `FindStatStatistic`

  A class representing a query for FindStat (compound) statistics.

  first_terms(max_values=1200)

    Return the pairs of the known terms which contain singletons, as a dictionary.

    EXAMPLES:

    Sage

        sage: PM = PerfectMatchings
        sage: l = [(PM(2*n), [m.number_of_nestings() for m in PM(2*n)]) for n in range(5)]
        sage: r = findstat(l, depth=0); r                                  # optional -- internet
        0: St000041 (quality [99, 100])
        1: St000042 (quality [99, 100])
        sage: r.first_terms()                                              # optional -- internet
        {[]: 0, [(1, 2)]: 0}

    Python

        >>> from sage.all import *
        >>> PM = PerfectMatchings
        >>> l = [(PM(Integer(2)*n), [m.number_of_nestings() for m in PM(Integer(2)*n)]) for n in range(Integer(5))]
        >>> r = findstat(l, depth=Integer(0)); r                                  # optional -- internet
        0: St000041 (quality [99, 100])
        1: St000042 (quality [99, 100])
        >>> r.first_terms()                                              # optional -- internet
        {[]: 0, [(1, 2)]: 0}

class sage.databases.findstat.FindStatStatistics(domain=None)

  Bases: `UniqueRepresentation`, `Parent`

  The class of FindStat statistics.

  The elements of this class are combinatorial statistics currently in FindStat.

  EXAMPLES:

  We can print a list of the first few statistics currently in FindStat in a given domain:

  Sage

      sage: from sage.databases.findstat import FindStatStatistics
      sage: for st, _ in zip(FindStatStatistics("Perfect Matchings"), range(3)):        # optional -- internet
      ....:     print("    " + st.name())
      The number of nestings of a perfect matching.
      The number of crossings of a perfect matching.
      The number of crossings plus two-nestings of a perfect matching.

  Python

      >>> from sage.all import *
      >>> from sage.databases.findstat import FindStatStatistics
      >>> for st, _ in zip(FindStatStatistics("Perfect Matchings"), range(Integer(3))):        # optional -- internet
      ...     print("    " + st.name())
      The number of nestings of a perfect matching.
      The number of crossings of a perfect matching.
      The number of crossings plus two-nestings of a perfect matching.

  Element

    alias of `FindStatStatistic`

sage.databases.findstat.findmap(*args, **kwargs)

  Return matching maps.

  INPUT:

  Valid keywords are: `domain`, `codomain`, `values`, `distribution`, `depth` and `max_values`. They have the following meanings:

  - `depth` – nonnegative integer (default: `FINDSTAT_DEFAULT_DEPTH`); specifying how many maps to apply to generate the given map

  - `max_values` – integer (default: `FINDSTAT_MAX_VALUES`); specifying how many values are sent to the finder

  - `domain`, `codomain` – integer or string of the form `Cc1234`, designates the domain and codomain of the sought for maps

  - `values`, `distribution` – data specifying the values or distribution of values of the sought for maps. The keyword arguments `depth` and `max_values` are passed to the finder. The data may be specified in one of the following forms:

    > - a list of pairs of the form `(object, value)`, or a dictionary from Sage objects to Sage objects.

    > - a list of pairs of the form `(list of objects, list of values)`, or a single pair of the form `(list of objects, list of values)`. In each pair there should be as many objects as values.

    > - a callable. In this case, the domain must be specified, also. The callable is then used to generate `max_values` `(object, value)` pairs.

    >   The number of terms generated may also be controlled by passing an iterable collection, such as `Permutations(3)`.

  `findmap` also accepts at most three positional arguments as follows:

  - a single positional argument, if none of `domain`, `codomain`, `values` or `distribution` are specified, is interpreted as a FindStat map identifier. If further arguments are given and it is a string, it is interpreted as a domain. If all this fails, it is interpreted as the specification of values.

  - if two positional arguments are given, the first is interpreted as domain, and the second either as codomain or the specification of values.

  - if three positional arguments are given, the first two are interpreted as domain and codomain, and the third as the specification of values.

  OUTPUT:

  An instance of a `FindStatMap`, `FindStatMapQuery` or `FindStatMaps`.

  EXAMPLES:

  A particular map can be retrieved by its Mp-identifier or number:

  Sage

      sage: findmap('Mp00062')                                                # optional -- internet
      Mp00062: Lehmer-code to major-code bijection

      sage: findmap(62)                                                       # optional -- internet
      Mp00062: Lehmer-code to major-code bijection

      sage: findmap("Mp00099oMp00127")                                        # optional -- internet
      Mp00099oMp00127

  Python

      >>> from sage.all import *
      >>> findmap('Mp00062')                                                # optional -- internet
      Mp00062: Lehmer-code to major-code bijection

      >>> findmap(Integer(62))                                                       # optional -- internet
      Mp00062: Lehmer-code to major-code bijection

      >>> findmap("Mp00099oMp00127")                                        # optional -- internet
      Mp00099oMp00127

  The database can be searched by providing a list of pairs:

  Sage

      sage: l = [pi for n in range(5) for pi in Permutations(n)]
      sage: findmap([(pi, pi.complement().increasing_tree_shape()) for pi in l], depth=2) # optional -- internet
      0: Mp00061oMp00069 (quality [...])

  [Python]

      >>> from sage.all import *
      >>> l = [pi for n in range(Integer(5)) for pi in Permutations(n)]
      >>> findmap([(pi, pi.complement().increasing_tree_shape()) for pi in l], depth=Integer(2)) # optional -- internet
      0: Mp00061oMp00069 (quality [...])

  or a dictionary:

  Sage

      sage: findmap({pi: pi.complement().increasing_tree_shape() for pi in l}, depth=2) # optional -- internet
      0: Mp00061oMp00069 (quality [...])

  Python

      >>> from sage.all import *
      >>> findmap({pi: pi.complement().increasing_tree_shape() for pi in l}, depth=Integer(2)) # optional -- internet
      0: Mp00061oMp00069 (quality [...])

  Note however, that the results of these two queries need not compare equal, because we compare queries by the data sent, and the ordering of the data might be different.

  Another possibility is to send a collection and a function. In this case, the function is applied to the first few objects of the collection:

  Sage

      sage: findmap("Permutations", lambda pi: pi.increasing_tree_shape(), depth=1)     # optional -- internet
      0: Mp00061 (quality [100])

  [Python]

      >>> from sage.all import *
      >>> findmap("Permutations", lambda pi: pi.increasing_tree_shape(), depth=Integer(1))     # optional -- internet
      0: Mp00061 (quality [100])

  In rare cases, it may not be possible to guess the codomain of a map, in which case it can be provided as second argument or keyword argument:

  Sage

      sage: findmap("Dyck paths", "Perfect matchings", lambda D: [(a+1, b) for a,b in D.tunnels()]) # optional -- internet
      0: Mp00146 (quality [100])

      sage: findmap("Dyck paths", "Set partitions", lambda D: [(a+1, b) for a,b in D.tunnels()]) # optional -- internet
      0: Mp00092oMp00146 (quality [...])

  Python

      >>> from sage.all import *
      >>> findmap("Dyck paths", "Perfect matchings", lambda D: [(a+Integer(1), b) for a,b in D.tunnels()]) # optional -- internet
      0: Mp00146 (quality [100])

      >>> findmap("Dyck paths", "Set partitions", lambda D: [(a+Integer(1), b) for a,b in D.tunnels()]) # optional -- internet
      0: Mp00092oMp00146 (quality [...])

  Finally, we can also retrieve all maps with a given domain or codomain:

  Sage

      sage: findmap("Cc0024")                                                 # optional -- internet
      Set of combinatorial maps with domain Cc0024: Binary words used by FindStat

      sage: findmap(codomain='Cores')                                         # optional -- internet
      Set of combinatorial maps with codomain Cc0013: Cores used by FindStat

  [Python]

      >>> from sage.all import *
      >>> findmap("Cc0024")                                                 # optional -- internet
      Set of combinatorial maps with domain Cc0024: Binary words used by FindStat

      >>> findmap(codomain='Cores')                                         # optional -- internet
      Set of combinatorial maps with codomain Cc0013: Cores used by FindStat

sage.databases.findstat.findstat(query=None, values=None, distribution=None, domain=None, depth=2, max_values=1000)

  Return matching statistics.

  INPUT:

  One of the following:

  - an integer or a string representing a valid FindStat identifier (e.g. 45 or ‘St000045’). The keyword arguments `depth` and `max_values` are ignored, `values` and `distribution` must be `None`.

  - a list of pairs of the form `(object, value)`, or a dictionary from Sage objects to integer values. The keyword arguments `depth` and `max_values` are passed to the finder, `values` and `distribution` must be `None`.

  - a list of pairs of the form (list of objects, list of values), or a single pair of the form (list of objects, list of values). In each pair there should be as many objects as values. The keyword arguments `depth` and `max_values` are passed to the finder.

  - a collection and a list of pairs of the form (string, value), or a dictionary from strings to integer values. The keyword arguments `depth` and `max_values` are passed to the finder. This should only be used if the collection is not yet supported.

  - a collection and a callable. The callable is used to generate `max_values` `(object, value)` pairs. The number of terms generated may also be controlled by passing an iterable collection, such as `Permutations(3)`. The keyword arguments `depth` and `max_values` are passed to the finder.

  OUTPUT: an instance of a `FindStatStatistic`, represented by

  - the FindStat identifier together with its name, or

  - a list of triples, each consisting of

    > - the statistic

    > - a list of strings naming certain maps

    > - a number which says how many of the values submitted agree with the values in the database, when applying the maps in the given order to the object and then computing the statistic on the result.

  EXAMPLES:

  A particular statistic can be retrieved by its St-identifier or number:

  Sage

      sage: findstat('St000041')                                              # optional -- internet
      St000041: The number of nestings of a perfect matching.

      sage: findstat(51)                                                      # optional -- internet
      St000051: The size of the left subtree of a binary tree.

      sage: findstat('St000042oMp00116')                                      # optional -- internet
      St000042oMp00116

  Python

      >>> from sage.all import *
      >>> findstat('St000041')                                              # optional -- internet
      St000041: The number of nestings of a perfect matching.

      >>> findstat(Integer(51))                                                      # optional -- internet
      St000051: The size of the left subtree of a binary tree.

      >>> findstat('St000042oMp00116')                                      # optional -- internet
      St000042oMp00116

  The database can be searched by providing a list of pairs:

  Sage

      sage: l = [m for n in range(1, 4) for m in PerfectMatchings(2*n)]
      sage: findstat([(m, m.number_of_nestings()) for m in l], depth=0)       # optional -- internet
      0: St000041 (quality [100, 100])

  [Python]

      >>> from sage.all import *
      >>> l = [m for n in range(Integer(1), Integer(4)) for m in PerfectMatchings(Integer(2)*n)]
      >>> findstat([(m, m.number_of_nestings()) for m in l], depth=Integer(0))       # optional -- internet
      0: St000041 (quality [100, 100])

  or a dictionary:

  Sage

      sage: findstat({m: m.number_of_nestings() for m in l}, depth=0)         # optional -- internet
      0: St000041 (quality [100, 100])

  Python

      >>> from sage.all import *
      >>> findstat({m: m.number_of_nestings() for m in l}, depth=Integer(0))         # optional -- internet
      0: St000041 (quality [100, 100])

  Note however, that the results of these two queries need not compare equal, because we compare queries by the data sent, and the ordering of the data might be different.

  Another possibility is to send a collection and a function. In this case, the function is applied to the first few objects of the collection:

  Sage

      sage: findstat("Perfect Matchings", lambda m: m.number_of_nestings(), depth=0)    # optional -- internet
      0: St000041 (quality [20, 100])

  [Python]

      >>> from sage.all import *
      >>> findstat("Perfect Matchings", lambda m: m.number_of_nestings(), depth=Integer(0))    # optional -- internet
      0: St000041 (quality [20, 100])

  To search for a distribution, send a list of lists, or a single pair:

  Sage

      sage: PM = PerfectMatchings(10); findstat((PM, [m.number_of_nestings() for m in PM]), depth=0) # optional -- internet
      0: St000042 (quality [100, 100])
      1: St000041 (quality [9, 100])

  Python

      >>> from sage.all import *
      >>> PM = PerfectMatchings(Integer(10)); findstat((PM, [m.number_of_nestings() for m in PM]), depth=Integer(0)) # optional -- internet
      0: St000042 (quality [100, 100])
      1: St000041 (quality [9, 100])

  Alternatively, specify the `distribution` parameter:

  Sage

      sage: findstat(12, distribution=lambda m: m.number_of_nestings(), depth=0) # optional -- internet
      0: St000041 (quality [100, 100])
      1: St000042 (quality [100, 100])

  [Python]

      >>> from sage.all import *
      >>> findstat(Integer(12), distribution=lambda m: m.number_of_nestings(), depth=Integer(0)) # optional -- internet
      0: St000041 (quality [100, 100])
      1: St000042 (quality [100, 100])

  Note that there is a limit, `FINDSTAT_MAX_VALUES`, on the number of elements that may be submitted to FindStat, which is currently 1000. Therefore, the interface tries to truncate queries appropriately, but this may be impossible, especially with distribution searches:

  Sage

      sage: PM = PerfectMatchings(12); PM.cardinality()                       # optional -- internet
      10395
      sage: findstat((PM, [1 for m in PM]))                                   # optional -- internet
      Traceback (most recent call last):
      ...
      ValueError: E016: The statistic finder was unable to perform a search on your data. The following errors have occured:

      You passed too few elements (0 < 3) to FindStat!

  Python

      >>> from sage.all import *
      >>> PM = PerfectMatchings(Integer(12)); PM.cardinality()                       # optional -- internet
      10395
      >>> findstat((PM, [Integer(1) for m in PM]))                                   # optional -- internet
      Traceback (most recent call last):
      ...
      ValueError: E016: The statistic finder was unable to perform a search on your data. The following errors have occured:
      <BLANKLINE>
      You passed too few elements (0 < 3) to FindStat!

  Finally, we can also retrieve all statistics with a given domain:

  Sage

      sage: findstat("Cc0024")                                                # optional -- internet
      Set of combinatorial statistics with domain Cc0024: Binary words in FindStat

      sage: findstat(domain='Cores')                                          # optional -- internet
      Set of combinatorial statistics with domain Cc0013: Cores in FindStat

  [Python]

      >>> from sage.all import *
      >>> findstat("Cc0024")                                                # optional -- internet
      Set of combinatorial statistics with domain Cc0024: Binary words in FindStat

      >>> findstat(domain='Cores')                                          # optional -- internet
      Set of combinatorial statistics with domain Cc0013: Cores in FindStat