flopy.utils.formattedfile Module

Module to read MODFLOW formatted output files. The module contains one important classes that can be accessed by the user.

  • FormattedHeadFile (Formatted head file. Can also be used for drawdown)
class flopy.utils.formattedfile.FormattedHeadFile(filename, text='head', precision='single', verbose=False, **kwargs)

FormattedHeadFile Class.

Parameters:

filename : string

Name of the formatted head file

text : string

Name of the text string in the formatted head file. Default is ‘head’

precision : string

‘single’ or ‘double’. Default is ‘single’.

verbose : bool

Write information to the screen. Default is False.

Notes

The FormattedHeadFile class provides simple ways to retrieve 2d and 3d head arrays from a MODFLOW formatted head file and time series arrays for one or more cells.

The FormattedHeadFile class is built on a record array consisting of headers, which are record arrays of the modflow header information (kstp, kper, pertim, totim, text, nrow, ncol, ilay) and long integers, which are pointers to first bytes of data for the corresponding data array.

FormattedHeadFile can only read formatted head files containing headers. Use the LABEL option in the output control file to generate head files with headers.

Examples

>>> import flopy.utils.formattedfile as ff
>>> hdobj = ff.FormattedHeadFile('model.fhd', precision='single')
>>> hdobj.list_records()
>>> rec = hdobj.get_data(kstpkper=(1, 50))
>>> rec2 = ddnobj.get_data(totim=100.)
close()

Close the file handle.

get_alldata(mflay=None, nodata=-9999)

Get all of the data from the file.

Parameters:

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

nodata : float

The nodata value in the data array. All array values that have the nodata value will be assigned np.nan.

Returns:

data : numpy array

Array has size (ntimes, nlay, nrow, ncol) if mflay is None or it has size (ntimes, nrow, ncol) if mlay is specified.

get_data(kstpkper=None, idx=None, totim=None, mflay=None)

Get data from the file for the specified conditions.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

Returns:

data : numpy array

Array has size (nlay, nrow, ncol) if mflay is None or it has size (nrow, ncol) if mlay is specified.

Notes

if both kstpkper and totim are None, will return the last entry Examples ——–

get_kstpkper()

Get a list of unique stress periods and time steps in the file

Returns:

out : list of (kstp, kper) tuples

List of unique kstp, kper combinations in binary file. kstp and kper values are presently zero-based.

get_times()

Get a list of unique times in the file

Returns:

out : list of floats

List contains unique simulation times (totim) in binary file.

get_ts(idx)

Get a time series from the formatted file.

Parameters:

idx : tuple of ints, or a list of a tuple of ints

idx can be (layer, row, column) or it can be a list in the form [(layer, row, column), (layer, row, column), ...]. The layer, row, and column values must be zero based.

Returns:

out : numpy array

Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).

Notes

The layer, row, and column values must be zero-based, and must be within the following ranges: 0 <= k < nlay; 0 <= i < nrow; 0 <= j < ncol

list_records()

Print a list of all of the records in the file obj.list_records()

plot(axes=None, kstpkper=None, totim=None, mflay=None, filename_base=None, **kwargs)

Plot 3-D model output data in a specific location in LayerFile instance

Parameters:

axes : list of matplotlib.pyplot.axis

List of matplotlib.pyplot.axis that will be used to plot data for each layer. If axes=None axes will be generated. (default is None)

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : int

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)

filename_base : str

Base file name that will be used to automatically generate file names for output image files. Plots will be exported as image files if file_name_base is not None. (default is None)

**kwargs : dict

pcolor
: bool

Boolean used to determine if matplotlib.pyplot.pcolormesh plot will be plotted. (default is True)

colorbar
: bool

Boolean used to determine if a color bar will be added to the matplotlib.pyplot.pcolormesh. Only used if pcolor=True. (default is False)

contour
: bool

Boolean used to determine if matplotlib.pyplot.contour plot will be plotted. (default is False)

clabel
: bool

Boolean used to determine if matplotlib.pyplot.clabel will be plotted. Only used if contour=True. (default is False)

grid
: bool

Boolean used to determine if the model grid will be plotted on the figure. (default is False)

masked_values
: list

List of unique values to be excluded from the plot.

file_extension
: str

Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.plot(totim=times[-1])
to_shapefile(filename, kstpkper=None, totim=None, mflay=None, attrib_name='lf_data')
Export model output data to a shapefile at a specific location
in LayerFile instance.
Parameters:

filename : str

Shapefile name to write

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then layer 1 will be written

attrib_name : str

Base name of attribute columns. (default is ‘lf_data’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.to_shapefile('test_heads_sp6.shp', totim=times[-1])
class flopy.utils.formattedfile.FormattedHeader(text_ident, precision='single')

The TextHeader class is a class to read in headers from MODFLOW formatted files.

Parameters:

text_ident is the text string in the header that identifies the type of data (eg. ‘head’)

precision is the precision of the floating point data in the file

get_dtype()

Return the dtype

get_names()

Return the dtype names

get_values()

Return the header values

read_header(text_file)

Read header information from a formatted file

Parameters:

text_file is an open file object currently at the beginning of the header

Returns:

out : numpy array of header information

also stores the header’s format string as self.format_string

class flopy.utils.formattedfile.FormattedLayerFile(filename, precision, verbose, kwargs)

The FormattedLayerFile class is the super class from which specific derived classes are formed. This class should not be instantiated directly

close()

Close the file handle.

get_alldata(mflay=None, nodata=-9999)

Get all of the data from the file.

Parameters:

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

nodata : float

The nodata value in the data array. All array values that have the nodata value will be assigned np.nan.

Returns:

data : numpy array

Array has size (ntimes, nlay, nrow, ncol) if mflay is None or it has size (ntimes, nrow, ncol) if mlay is specified.

get_data(kstpkper=None, idx=None, totim=None, mflay=None)

Get data from the file for the specified conditions.

Parameters:

idx : int

The zero-based record number. The first record is record 0.

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (Default is None.)

Returns:

data : numpy array

Array has size (nlay, nrow, ncol) if mflay is None or it has size (nrow, ncol) if mlay is specified.

Notes

if both kstpkper and totim are None, will return the last entry Examples ——–

get_kstpkper()

Get a list of unique stress periods and time steps in the file

Returns:

out : list of (kstp, kper) tuples

List of unique kstp, kper combinations in binary file. kstp and kper values are presently zero-based.

get_times()

Get a list of unique times in the file

Returns:

out : list of floats

List contains unique simulation times (totim) in binary file.

get_ts(idx)

Get a time series from the formatted file.

Parameters:

idx : tuple of ints, or a list of a tuple of ints

idx can be (layer, row, column) or it can be a list in the form [(layer, row, column), (layer, row, column), ...]. The layer, row, and column values must be zero based.

Returns:

out : numpy array

Array has size (ntimes, ncells + 1). The first column in the data array will contain time (totim).

Notes

The layer, row, and column values must be zero-based, and must be within the following ranges: 0 <= k < nlay; 0 <= i < nrow; 0 <= j < ncol

list_records()

Print a list of all of the records in the file obj.list_records()

plot(axes=None, kstpkper=None, totim=None, mflay=None, filename_base=None, **kwargs)

Plot 3-D model output data in a specific location in LayerFile instance

Parameters:

axes : list of matplotlib.pyplot.axis

List of matplotlib.pyplot.axis that will be used to plot data for each layer. If axes=None axes will be generated. (default is None)

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : int

MODFLOW zero-based layer number to return. If None, then all all layers will be included. (default is None)

filename_base : str

Base file name that will be used to automatically generate file names for output image files. Plots will be exported as image files if file_name_base is not None. (default is None)

**kwargs : dict

pcolor
: bool

Boolean used to determine if matplotlib.pyplot.pcolormesh plot will be plotted. (default is True)

colorbar
: bool

Boolean used to determine if a color bar will be added to the matplotlib.pyplot.pcolormesh. Only used if pcolor=True. (default is False)

contour
: bool

Boolean used to determine if matplotlib.pyplot.contour plot will be plotted. (default is False)

clabel
: bool

Boolean used to determine if matplotlib.pyplot.clabel will be plotted. Only used if contour=True. (default is False)

grid
: bool

Boolean used to determine if the model grid will be plotted on the figure. (default is False)

masked_values
: list

List of unique values to be excluded from the plot.

file_extension
: str

Valid matplotlib.pyplot file extension for savefig(). Only used if filename_base is not None. (default is ‘png’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.plot(totim=times[-1])
to_shapefile(filename, kstpkper=None, totim=None, mflay=None, attrib_name='lf_data')
Export model output data to a shapefile at a specific location
in LayerFile instance.
Parameters:

filename : str

Shapefile name to write

kstpkper : tuple of ints

A tuple containing the time step and stress period (kstp, kper). These are zero-based kstp and kper values.

totim : float

The simulation time.

mflay : integer

MODFLOW zero-based layer number to return. If None, then layer 1 will be written

attrib_name : str

Base name of attribute columns. (default is ‘lf_data’)

Returns:

None

Examples

>>> import flopy
>>> hdobj = flopy.utils.HeadFile('test.hds')
>>> times = hdobj.get_times()
>>> hdobj.to_shapefile('test_heads_sp6.shp', totim=times[-1])