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_name, invest_version)

Bases: tuple

args

Alias for field number 0

invest_version

Alias for field number 2

model_name

Alias for field number 1

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

Build an InVEST datastack from an arguments dict.

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

  • model_name (string) – The python-importable module string of the model these args are for.

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

Returns

None

natcap.invest.datastack.build_parameter_set(args, model_name, 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_name (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

None

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
invest_version (string): The version of InVEST used to record the
    parameter set.
model_name (string): The name of the callable or model that these
    arguments are intended 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. If a model name and InVEST version cannot be parsed from the Arguments section of the logfile, ParameterSet.model_name and ParameterSet.invest_version will be set to datastack.UNKNOWN.

Raises

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

natcap.invest.datastack.format_args_dict(args_dict, model_name)

Nicely format an arguments dictionary for writing to a stream.

If printed to a console, the returned string will be aligned in two columns representing each key and value in the arg dict. Keys are in ascending, sorted order. Both columns are left-aligned.

Parameters
  • args_dict (dict) – The args dictionary to format.

  • model_name (string) – The model name (in python package import format)

Returns

A formatted, unicode string.

natcap.invest.datastack.get_datastack_info(filepath)

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.

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, modelname and invest version that the file was built with.

Return type

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