.. _file_paths:

FILE_PATHS
###########

This required field, defines where any input files can be found and where the results of the computation are to be stored.

.. _file_paths_example:

Example from FILE_PATHS from a Fit Script
==========================================

.. code-block:: pyml

    FILE_PATHS:
        # path to input comma separated value file in popy data format
        input_data_file: builtin_fit_example_data.csv

        # Output folder - results of computation stored here
        output_folder: auto

        # Temp folder - temporary files stored here
        temp_folder: auto

        # Output file extension - determines graphical output file format.
        output_file_ext: ['svg', 'pdf']

        # Solution containing f[X] values from a previous run.
        input_solution_file: none

.. _file_paths_main_fields:
        
Main FILE_PATH Fields
=======================

.. _file_paths_input_file_spec:

input_file
-----------

Required path to input a .csv file in popy data format:-

.. code-block:: pyml

    input_data_file: builtin_fit_example_data.csv

Note that this field is required and the .csv file **must** exist else |popy| will throw an error message.

.. _file_paths_output_folder_spec:

output_folder
--------------

Optional field that specifies the output folder, where the results of computation are stored.

The default is:-

.. code-block:: pyml
 
    output_folder: auto

Using **auto** will specify an output folder based on the script name. E.g if your script is called 'my_fit_script.pyml', the output folder will be:-

.. code-block:: console

    my_fit_script.pyml.output
    
Using **auto** is safest, as then it is impossible to over-write the output from other scripts.

.. _file_paths_temp_folder_spec:

temp_folder
-----------------

Optional field that specifies the temp folder, where temporary functions generated by |popy| are stored.

The default is:-

.. code-block:: pyml
 
    temp_folder: auto

The default folder name is '_temp' within the :ref:`file_paths_output_folder_spec`. If you have a script named 'my_fit_script.pyml' and miss out the 'output_folder' and 'temp_folder' you will end up with temporary functions in this folder:-

.. code-block:: console

    my_fit_script.pyml.output
        /fit
            /_temp
            
Note the subfolders within '_temp' have random names, this is to avoid re-using old temporary functions if the same script is run twice (and altered slightly).


.. _file_paths_output_file_ext_spec:

output_file_ext
-----------------

This is an optional list of file types to output when plotting. The default is:-

.. code-block:: pyml
    
    output_file_ext: ['svg']
    
This outputs plots in .svg format, which stands for scalable vector graphics, see:-

https://en.wikipedia.org/wiki/Scalable_Vector_Graphics

.svg is a good format because it can be displayed at any resolution without being pixelated. For example if you used .png or any other raster format.

The input is a |python| :term:`list`. This is to enable you to output plots in multiple formats. For example many of the documentation examples use the following:-

.. code-block:: pyml
    
    output_file_ext: ['svg', 'pdf']
    
To generate plots in .svg and also .pdf format. We do this with the documentation so that the :term:`HTML` documentation can display .svg and the pdf version can use .pdf plots.

.. _file_paths_input_solution_file_ext_spec:

input_solution_file
----------------------

This field is only available in the :ref:`fit_script`. It is an optional link to a 'solution.pyml' file to initialise the |fx| starting values during a fit. The default is:-

.. code-block:: pyml
    
    input_solution_file: none
    
This does nothing and uses the |fx| starting values specified in the |effects| section of the script.

If a solution file is specified, |eg|:-

.. code-block:: pyml

    input_solution_file: ./previous_fit_script.pyml_output/fit/solN/solution.pyml

Then the 'solution.pyml' file will be loaded, specifically the 'fx_params.csv' part of the solution.

.. code-block:: pyml

    FILE_PATHS:
        fx_params_path: fx_params.csv

The |fx| params are used as new starting values.

You can use the 'input_solution_file' to restart a :ref:`fit_script` from a previous fitting script. This is useful if the previous script fails, for example if the machine is accidentally switched off or some other system failure.

