docs: refer to examples and specs of the input formats

assets/flux_kcat.metabolism.json

@@ -0,0 +1 @@
+{"reactions": ["ENO", "GAPD", "PFK", "PGI", "PGK", "PGM", "PYK", "TPI"], "colors": [30.0, 10.0, 20.0, 200.0, 100.0, 50.0, 40.0, 120.0], "sizes": [0.2, 0.4, 0.1, 0.5, 0.6, 0.7, 0.3, 0.8]}

docs/source/file_formats.rst

@@ -0,0 +1,72 @@
+File Formats
+============
+
+For a quick start, see the `map example`_ (or any escher map at
+https://escher.github.io/) and the `data example`_.
+
+Map
+---
+
+Shu uses the same format as escher for the maps. Maps from escher can be imported
+using the Map button (web app) or with drag and drop (native app).
+
+The only difference is that the histogram position, rotation and scale (which
+does not exist in escher) can be exported to the map (only native app for now)
+using the `Export` drop down on the `Settings` window. This allows to save a
+map with the correct manually fixed positions where different data can be
+plotted for the same or different projects.
+
+For the full JSON specification (ending with the extension ".json"), please refer
+to the source code represented by the `EscherMap` struct found at `the map source code`_.
+
+Data
+----
+
+The input data that contains the variables to be plotted in the map is a JSON ending withe ".metabolism.json" extension. The full specification is the following struct (source code at `the data source code`_):
+
+.. code-block:: rust
+
+  struct Data {
+      /// Vector of reactions' identifiers
+      reactions: Option<Vec<String>>,
+      /// Numeric values to plot as reaction arrow colors.
+      colors: Option<Vec<Number>>,
+      /// Numeric values to plot as reaction arrow sizes.
+      sizes: Option<Vec<Number>>,
+      /// Numeric values to plot as KDE.
+      y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot as KDE.
+      left_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot on a hovered popup.
+      hover_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot as KDE.
+      kde_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot as KDE.
+      kde_left_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot on a hovered popup.
+      kde_hover_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot as KDE.
+      box_y: Option<Vec<Number>>,
+      /// Numeric values to plot as KDE.
+      box_left_y: Option<Vec<Number>>,
+      /// Categorical values to be associated with conditions.
+      conditions: Option<Vec<String>>,
+      /// Categorical values to be associated with conditions.
+      met_conditions: Option<Vec<String>>,
+      /// Vector of metabolites' identifiers
+      metabolites: Option<Vec<String>>,
+      /// Numeric values to plot as metabolite circle colors.
+      met_colors: Option<Vec<Number>>,
+      /// Numeric values to plot as metabolite circle sizes.
+      met_sizes: Option<Vec<Number>>,
+      /// Numeric values to plot as histogram on hover.
+      met_y: Option<Vec<Vec<Number>>>,
+      /// Numeric values to plot as density on hover.
+      kde_met_y: Option<Vec<Vec<Number>>>,
+  }
+
+
+.. _map example: https://github.com/biosustain/shu/blob/master/assets/ecoli_core_map.json 
+.. _data example: https://github.com/biosustain/shu/blob/master/assets/flux_kcat.metabolism.json 
+.. _the map source code: https://github.com/biosustain/shu/blob/master/src/escher.rs
+.. _the data source code: https://github.com/biosustain/shu/blob/master/src/data.rs

docs/source/index.rst

@@ -8,8 +8,8 @@ Shu is available as a web application at https://biosustain.github.io/shu or as
 application (see `releases`_).
 
 Check out the :doc:`plotting` section for an overview on how to generate and plot data
-into the map. The :doc:`map` explains the map especification (with is fully compatible
-with `escher`_).
+into the map. The :doc:`file_formats` explains the map (with is fully compatible
+with `escher`_) and data especification.
 
 Controls
 --------
@@ -29,7 +29,7 @@ Contents
 .. toctree::
 
    plotting
-   map
+   file_formats
    developers
 
 .. _releases: https://github.com/biosustain/shu/releases/latest

docs/source/plotting.rst

@@ -64,7 +64,7 @@ that can be used by shu.
        + geom_arrow()
    ).to_json("flux_kcat")
 
-The call to ``to_json`` will generate a file called `flux_kcat.metabolism.json`.
+The call to ``to_json`` will generate a file called `flux_kcat.metabolism.json` (which should look like this `data example`_).
 
 Now, go to the `shu website`_ and upload the file `flux_kcat.metabolism.json` and see the result by clicking on the.
 rigth-top corner button "Data".
@@ -242,9 +242,9 @@ Sometimes distributed data is not available but we have different variables that
 Data Format
 -----------
 
-If `ggshu` is not enough, you can check the lower level data format that shu uses (the ouput that `ggshu` generates) in the `API documentation`_.
+If `ggshu` is not enough, you can check the lower level data format that shu uses (the ouput that `ggshu` generates) in the :doc:`file_formats` section.
 
 .. _pandas: http://pandas.pydata.org/
 .. _tidy format: https://vita.had.co.nz/papers/tidy-data.html 
+.. _data example: https://github.com/biosustain/shu/blob/master/assets/flux_kcat.metabolism.json 
 .. _shu website: https://biosustain.github.io/shu
-.. _API documentation: https://docs.rs/shu/latest/shu/data/struct.Data.html