
% a description of the software itself: main functionalities , algorithms...
% a description of typical applications and use cases
% a comparison with existing software or algorithms
% brief evidence for the ease of use and reuse: documentation, examples of usage, availability, license, software requirements, installation instructions, (plans for) integration in existing platforms (e.g. GAP, Magma, Maple, Mathematica, or SageMath).
% brief evidence for software quality and sustainability: tests, development model, use of collaborative tools, etc.

\MBGen~\cite{MBGen:on} works for datasets that fit the following simple mold.
First, the dataset is composed of some number of lists of mathematical objects of the same type.
Second, for every type, the list consists of either simple objects or of object records.
These records could contain information about a set of mathematical properties or invariants,
provided they can be reasonably represented in a database.
The set of supported types is extensible and currently contains some basic types
(Booleans and integers) as well as some more complex types for demonstration.
An up-to-date description of the system, including the setup and 
a list of supported types is available in the project readme.

\paragraph{Writing a Dataset Declaration}
The schema declaration is written in the Mathematical Data Declaration Language (\MDDL)
and is essentially a list of declarations $c:A$,
where $c$ is a name of a property and $A$ is its type.
Every declaration also needs a codec, which is simply a pair of mappings
(an encoding and a decoding) between a mathematical type and a database type.
\MDDL and its underlying infrastructure were introduced and described in~\cite{CICM}.
For the purpose of this abstract, we only demonstrate how \MDDL can be used through examples,
and briefly describe codecs in the following paragraph.

Codecs are an essential part of the system that handles
the communication between the mathematical level and the database level.
They enable interoperability, which happens at the mathematical level,
and connect it with the storage at the database level.
Note that codecs can be arbitrary code and arbitrarily complex:
consider the example Brendan McKay's graph formats~\cite{GraphFormats},
which are widely used to represent graphs as strings.
These formats are typically used in combination with canonical labelings~\cite{Canonical}
to ensure that two graphs with the same encoding are necessarily also isomorphic.

To set up her project, Mathilde follows the steps described on the project page~\cite{MBGen:on}.
Once she is ready, she starts writing her schema declaration.
First, she just writes down an empty theory called \matrices (Listing~\ref{mmt:empty}).
Next, she will write property declarations for each of the columns in her dataset,
as in Listing~\ref{mmt:property}.

\begin{minipage}[c]{7.5cm}
\begin{mmtcode}[caption={The empty theory},label=mmt:empty]
namespace http://data.mathhub.info/schemas❚
theory Matrices : ?MDDL =
❚
\end{mmtcode}
\end{minipage}\quad
\begin{minipage}[c]{7.5cm}
\begin{mmtcode}[caption={A property declaration},label=mmt:property]
property: propertyMathType ❘
    meta ?Codecs?codec propertyCodec ❘
    propertyTags ❙
\end{mmtcode}
\end{minipage}

She only needs to use types that are already supported, 
and for which codecs have already been defined.
In addition to the required information about the mathematical type
and the codecs, Mathilde can use the optional tags (Table~\ref{tb:metadata})
to specify the interface behaviour.

\begin{table}
\begin{tabular}{ l l p{0.69\textwidth} }
\emph{Database} & \texttt{index} & Column representing a dataset index \\
\noalign{\vskip 1mm}\hline\noalign{\vskip 1mm}
\emph{Frontend} & \texttt{collection} & Collection metadata, e.g. provenance data \\
& \texttt{display} & Display name in the list of filters and in the results table head. \\
& \texttt{hidden} & By default, hide in the results display. \\
& \texttt{opaque} & Do not use for filtering. 
\end{tabular}
\caption{Metadata tags}\label{tb:metadata}
\end{table}

The tag \texttt{hidden} can be used when a dataset has many columns
(like the graph datasets in DiscreteZOO~\cite{DZWeb:on}).
If there are hidden columns, the interface shows an additional widget, 
which lets a visitor choose which columns they want to see.
If the tag \texttt{display} is not present, the column name is used for display.
The tags particularly relevant for the interface the metadata tags and the tags
\texttt{hidden} and \texttt{opaque}.

Now, Mathilde can write down her dataset declaration (Listing~\ref{mmt:schema}).

\begin{mmtcode}[caption={Mathilde's dataset declaration},label=mmt:schema]
theory Matrices : ?MDDL =
meta /schemas?MDDL?datasetName "Mathilde's matrix dataset" ❙
    mat: matrix $\mathbb{Z}$ 2 2 ❘ meta ?Codecs?codec MatrixAsArray IntIdent ❘
        tag ?MDDL?opaque ❙
    trace: $\mathbb{Z}$ ❘ meta ?Codecs?codec IntIdent ❙
    orthogonal: bool ❘ meta ?Codecs?codec BoolIdent ❙
    eigenvalues: list $\mathbb{Z}$ ❘ meta ?Codecs?codec ListAsArray IntIdent ❘
        tag ?MDDL?opaque ❙
    characteristic: Polynomial IntegerRing ❘ meta ?Codecs?codec PolynomialAsSparseArray IntIdent ❘
        tag ?MDDL?opaque ❙   
❚
\end{mmtcode}

\medskip\noindent\begin{minipage}[c]{10.8cm}
\paragraph{Generating and Populating the Database}
For every schema theory $T$, \MBGen  generates an SQL table.
The table name is the theory name and for each declaration $c:A$ in $T$,
it generates a column, whose type is obtained from the codec declaration.
In addition to these, \MBGen generates a primary key column called \texttt{ID} of type \texttt{UUID}.
When Mathilde runs \MBGen on her schema theory from Listing~\ref{mmt:schema}, 
she obtains the database schema on the right.
\end{minipage}\quad
\begin{minipage}[c]{5.2cm}
\begin{lstlisting}[basicstyle=\scriptsize\tt,columns=fixed,caption=Schema]
      Column     |   Type    
 ----------------+----------
  ID             | uuid      
  MAT            | integer[] 
  TRACE          | integer   
  ORTHOGONAL     | boolean   
  EIGENVALUES    | integer[] 
  CHARACTERISTIC | integer[] 
  
 Indexes: "Matrices_pkey" 
 PRIMARY KEY, btree ("ID")
\end{lstlisting}
\end{minipage}

If the dataset has a pre-existing ID-like field, which is not a \texttt{UUID},
the corresponding column should be tagged with \texttt{index}.
She can insert her data using the corresponding SQL \texttt{INSERT} statements, see Listing~\ref{tb:dbtable}.

\begin{lstlisting}[basicstyle=\scriptsize\tt,columns=fixed,caption=Table contents after insert,label=tb:dbtable]
         ID         |    MAT     | TRACE | ORTHOGONAL | EIGENVALUES | CHARACTERISTIC
 -------------------+------------+-------+------------+-------------+----------------
  e278b5e8-4404-... | {2,0,0,1}  |     3 | t          | {2,1}       | {0,2,1,-3,2,1}
  05a30ff0-4405-... | {2,1,1,2}  |     4 | f          | {3,1}       | {0,3,1,-4,2,1}
  1be3f022-4405-... | {-1,0,0,1} |     0 | t          | {1,-1}      | {0,-1,2,1}
\end{lstlisting}

\begin{figure}
\centering
\includegraphics[width=0.8\textwidth]{screenshot.png}
\caption{Screenshot of the website for Mathilde's use dataset}
\end{figure}

\paragraph{Extensions and Customisation}
Mathilde can modify the code and the database after they are generated 
and before running or deploying the website.
We use the project wiki~\cite{MBGen:on} to document how such modifications can be made.
