.. include:: ./includes/external_links.rst

.. include:: ./includes/warning_development.rst

.. _files:

Files
#####################################################################

This page describes the **file system** used in ``plans``.

.. seealso::

   Check out the :ref:`projects` page for more details on how to setup a project.

The file system in ``plans`` is quite straight-forward.
All files are always formatted in two ways:

- ``csv`` format for :ref:`io-table` structure;
- ``GeoTIFF`` format for :ref:<io-raster>` (map) structure.

All files fall into these workflow categories:

#. :ref:`io-input-files`: required and optional data files that users must provide by themselves. Input files lives in the ``data/`` folder of a project.
#. :ref:`io-intermediate-files`: data files generated by ``plans`` as intermediate step to final processing, like *cached* data. Users may also provide this files to skip intermediate steps. Like input files, intermediate files lives in the ``data/`` folder of a project;
#. :ref:`io-output-files`: data files generated by ``plans`` as results of final processing. Output files lives under ``outputs/`` in the respective subfolder of the processing session.

.. admonition:: Files Index
   :class: seealso

   Check out the :ref:`files-index` page for the full list of files and specifications.

.. note::

   All files not listed in the :ref:`files-index` is ignored by ``plans``.

.. admonition:: Data structures and formatting
   :class: seealso

   Check out the :ref:`files-data-structures` page for more details on how to format input data.


.. _io-input-files:

Input Files
***********************************************************************

An **Input File** is a data file that users must provide by themselves. Input Files lives in their respective subfolders under the ``data/`` folder of a project.

.. _io-input-files-required:

Required Input Files
=======================================================================

A **Required Input File** is an Input File that are necessary for a viable simulation run of ``plans``.
In other words: it is impossible to run without the file.

.. csv-table::
   :file: ./data/files_input_required.csv
   :header-rows: 1
   :widths: auto
   :delim: ;


.. _io-input-files-optional:

Optional Input Files
=======================================================================

An **Optional Input File** is an Input File that are used in ``plans`` for extra simulation or assessments. If not provided, ``plans`` may skip the extra simulation or parse default built-in data.

.. csv-table::
   :file: ./data/files_input_optional.csv
   :header-rows: 1
   :widths: auto
   :delim: ;

.. _io-intermediate-files:

Intermediate Files
***********************************************************************

An **Intermediate File** is a cached file: a data file that is generated by ``plans`` during **setup processes** prior to simulation or assessment **main process**. They are necessary for a viable simulation run of ``plans``. Like Input Files, Intermediate File lives in under respective subfolders under the ``data/`` folder of a project.

.. admonition:: Skipping setup processes
   :class: note

   Users can skip setup processes by providing Intermediate Files to a project, but it must be consistent with ``plans`` standards.


.. csv-table::
   :file: ./data/files_intermediate.csv
   :header-rows: 1
   :widths: auto
   :delim: ;

.. _io-output-files:

Output Files
***********************************************************************

An **Output File** is a data file generated by ``plans`` during simulation or assessment **main process**. Output Files lives in the respective process folder under ``outputs/`` of a project.

.. csv-table::
   :file: ./data/files_output.csv
   :header-rows: 1
   :widths: auto
   :delim: ;


.. toctree::
   :maxdepth: 1
   :hidden:

   Files <self>
   data_structures
   files_index