natcap.invest.datastack

Functions for reading and writing InVEST model parameters.

A datastack for InVEST is a compressed archive that includes the arguments for a model, all of the data files referenced by the arguments, and a logfile with some extra information about how the archive was created. The resulting archive can then be extracted on a different computer and should have all of the information it needs to run an InVEST model in its entirity.

A parameter set for InVEST is a JSON-formatted text file that contains all of the parameters needed to run the current model, where the parameters are located on the local hard disk. Paths to files may be either relative or absolute. If paths are relative, they are interpreted as relative to the location of the parameter set file.

A logfile for InVEST is a text file that is written to disk for each model run.

class natcap.invest.datastack.ParameterSet(args, model_id)

Bases: tuple

args

Alias for field number 0

model_id

Alias for field number 1

natcap.invest.datastack.build_datastack_archive(args, model_id, datastack_path)

Build an InVEST datastack from an arguments dict.

Parameters:

  • args (dict) – The arguments dictionary to include in the datastack.

  • model_id (string) – The id the model these args are for. For core models, this is the regular id. For plugins, this has the format model_id@version

  • datastack_path (string) – The path to where the datastack archive should be written.

Returns:

None

natcap.invest.datastack.build_parameter_set(args, model_id, paramset_path, relative=False)

Record a parameter set to a file on disk.

Parameters:

  • args (dict) – The args dictionary to record to the parameter set.

  • model_id (string) – An identifier string for the callable or InVEST model that would accept the arguments given.

  • paramset_path (string) – The path to the file on disk where the parameters should be recorded.

  • relative (bool) – Whether to save the paths as relative. If True, The datastack assumes that paths are relative to the parent directory of paramset_path.

Returns:

parameter dictionary saved in paramset_path

Raises:

ValueError if creating a relative path fails. –

natcap.invest.datastack.extract_datastack_archive(datastack_path, dest_dir_path)

Extract a datastack to a given folder.

Parameters:

  • datastack_path (string) – The path to a datastack archive on disk.

  • dest_dir_path (string) – The path to a directory. The contents of the demonstration datastack archive will be extracted into this directory. If the directory does not exist, it will be created.

Returns:

A dictionary of arguments from the extracted

archive. Paths to files are absolute paths.

Return type:

args (dict)

natcap.invest.datastack.extract_parameter_set(paramset_path)

Extract and return attributes from a parameter set.

Any string values found will have environment variables expanded. See :py:ref:os.path.expandvars and :py:ref:os.path.expanduser for details.

Parameters:

paramset_path (string) – The file containing a parameter set.

Returns:

A ParameterSet namedtuple with these attributes:

args (dict): The arguments dict for the callable
model_id (string): the ID of the model that these parameters are for

natcap.invest.datastack.extract_parameters_from_logfile(logfile_path)

Parse an InVEST logfile for the parameters (args) dictionary.

Argument key-value pairs are parsed, one pair per line, starting the line after the line starting with "Arguments", and ending with a blank line. If no such section exists within the logfile, ValueError will be raised.

If possible, the model name and InVEST version will be parsed from the same line as "Arguments", but IUI-formatted logfiles (without model name and InVEST version information) are also supported.

Parameters:

logfile_path (string) – The path to an InVEST logfile on disk.

Returns:

An instance of the ParameterSet namedtuple.

Raises:

ValueError - when no arguments could be parsed from the logfile. –

natcap.invest.datastack.get_datastack_info(filepath, extract_path=None)

Get information about a datastack.

Parameters:

  • filepath (string) – The path to a file on disk that can be extracted as a datastack, parameter set, or logfile.

  • extract_path (str) – Path to a directory to extract the datastack, if provided as an archive. Will be overwritten if it already exists, or created if it does not already exist.

Returns:

  • "archive" when the file is a datastack archive.

    • "json" when the file is a json parameter set.

    • "logfile" when the file is a text logfile.

The second item of the tuple is a ParameterSet namedtuple with the raw parsed args, model id and invest version that the file was built with.

Return type:

A 2-tuple. The first item of the tuple is one of