== [https://datamining.anu.edu.au/anuga ANUGA]/[InternalArchitecture Internal Architecture]/[wiki:Classes Classes] == ----- = Class Geospatial_data = Defined in file geospatial_data/geospatial_data.py. == Discussion == == Class Attributes == || '''data_points''' || The points data in the object. || || '''geo_reference''' || Current origin the points data is relative to. || || '''attributes''' || Dictionary of key:values attributes for the point data. Each '''values''' is a list/array of attributes values of the same dimensionality as the point data.|| || '''file_name''' || Name of .pts or .txt file that the points data was read from or is being read from (blocking). || || '''max_read_lines''' || Maximum number of text lines that are read each step during blocking reads. || || '''default_attribute_name''' || The name of the default attribute if attribute name not specified. || || '''verbose''' || True if instance methods are to be verbose. Instance methods shouldn't take a '''verbose''' parameter - it should come from this attribute. || || '''blocking_georef''' || ?? || || '''blocking_keys''' || ?? || || '''number_of_points''' || ?? || || '''fid''' || ?? || || '''start_row''' || ?? || || '''last_row''' || ?? || || '''show_verbose''' || ?? || || '''verbose_block_size''' || ?? || || '''block_number''' || ?? || || '''number_of_blocks''' || ?? || || '''header''' || ?? || || '''file_pointer''' || ?? || == Class Methods == || '''_ _init_ _(data_points=None, attributes=None, geo_reference=None, default_attribute=None, file_name=None, latitudes=None, longitudes=None, points_are_lats_longs=False, max_read_lines=None, load_file_now=True, verbose=False)''' || '''data_points''' is either a 2-dimensional (Mx2) set of points or a filename (ending in .pts, .csv or .txt) of a file containing the point data. '''attributes''' contains the attribute value to be stored at each data point and must be either a list or vector array (length M, assumed attribute 'elevation') or a dictionary with multiple attribute name keys and value lists. '''geo_reference''' is the Geo_reference reference defining the origin of the points in this object. '''default_attribute_name''' is the name of the attribute considered to be default in the get_attribute() method. '''file_name''' is the name of a NetCDF (or .txt) file to load points data from. '''latitudes''' and '''longitudes''' are lists/vectors defining points as lats/longs rather then the '''data_points''' parameter. '''points_are_lats_longs''' is a boolean which is True if the points data are actually lats/longs and not UTM coordinates. '''max_read_lines''' sets the number of lines to read in a 'block' if blocking data from a file. '''load_file_now''' is True if the file data is to be automatically loaded into memory (used if blocking). '''verbose''' is True if this class is to be verbose. || || '''_ _len_ _()''' || Returns the length of the '''data_points''' attribute. || || '''_ _repr_ _()''' || Returns a string representation of '''get_data_points(absolute=True)'''. || || '''check_data_points(data_points)''' || Populate the '''data_points''' attribute dataset. || || '''set_attributes(attributes)''' || Assign attributes data to this instance. '''attributes''' is either list/array of attributes values (default name '''elevation''') or a dictionary of attribute name:values pairs. || || '''set_geo-reference()''' || Set or change the Geo_reference reference for this instance. If changing, ensure that absolute coordinate values are unchanged. || || '''set_default_attribute(default_attribute_name)''' || Set the instance default attribute name (used in get_attribute()). || || '''set_verbose(verbose=False)''' || Set the verbose attribute for this instance. || || '''clip(polygon, closed=True, verbose=False)''' || Clip the instance points set by a given polygon. '''polygon''' is either a list or array of points (Nx2) or a Geospatial_data instance. '''closed''' is True if any points `on` the bounding polygon are to be considered `inside` the polygon. '''verbose''' - not sure why this is here - class has a '''verbose''' attribute. Method returns the point set inside the clipping polygon. || || '''clip_outside(polygon, closed=True, verbose=False)''' || Clip the instance points set by a given polygon. '''polygon''' is either a list or array of points (Nx2) or a Geospatial_data instance. '''closed''' is True if any points `on` the bounding polygon are to be considered `inside` the polygon. '''verbose''' - not sure why this is here - class has a '''verbose''' attribute. Method returns the point set outside the clipping polygon. || || '''get_geo_reference()''' || Return the Geo_reference reference assigned to this instance. || || '''get_data_points(absolute=True, geo_reference=None, as_lat_long=False, isSouthHemisphere=True''' || Get coordinates of the points dataset in this instance. Id '''absolute''' is True return absolute UTM coordinates, else return coordinates relative to the associated Geo_reference origin. If '''geo_reference''' is supplied return coordinates relative to that origin. If '''as_lat_long''' is True return coordinates as lat/long points. If '''isSouthHemisphere''' is True return any lat/long coordinates as for the southern hemisphere, else the northern. || || '''get_attributes(attribute_name=None)''' || Return the attribute values for one attribute. If '''attribute_name''' is None return the values for the default attribute.|| || '''get_all_attributes()''' || Return '''all''' attributes as a (possibly empty) dictionary or None (if no attributes). || || '''_ _add_ _(other)''' || Method to allow addition of two Geo_reference instances. In this case, 'add' means concatenate the point datasets and attributes. Throws an exception if the attributes aren't the same in both instances. Returns a new instance of Geo_reference which is '''absolute'''. || || '''_ _radd_ _(other)''' || Method to allow addition of two Geo_reference instances. In this case, 'add' means concatenate the point datasets and attributes. Throws an exception if the attributes aren't the same in both instances. Returns a new instance of Geo_reference which is '''absolute'''. || || '''import_points_file(file_name, delimiter=None, verbose=False)''' || Import a .txt, .csv or .pts file into this instance from '''file_name'''. Also reads attributes and geo_reference data from the input file. '''delimiter''' is unused. '''verbose''' is superfluous. || || '''export_points_file(file_name, absolute=True, as_lat_long=False, isSouthHemisphere=True)''' || Write Geo_reference instance data to a .pts, .csv or .txt file. '''file_name''' is the path to the file to write. If '''absolute''' is True then the point coordinates in the instance are converted to absolute form and then written out. If '''absolute''' is False the Geo_reference point coordinates remain unchanged and written out (note, they may be relative or absolute). If '''is_lat_long''' is True then points are written out as lat/long coordinates, southern hemisphere form if '''isSouthHemisphere''' is True, northern if False. || || '''get_sample(indices)''' || Get a new Geo_reference instance containing a sample of points in this instance. '''indices''' contains the ordinals of the points to be placed in the new instance. Attributes of the sampled points are copied to the new instance. || || '''split(factor=0.5, seed_num=None, verbose=False)''' || Split this instance into two new instances containing a random selection of points. '''factor''' is the fraction of the input instance to be copied into the first split instance. '''seed_num''' is the random seed to use (testing only). If '''verbose''' is True then this method is to be verbose. || || '''_ _iter_ _()''' || Allow iteration of the instance over input blocks. This function sets up ready for the next() method. This means that the '''blocking_georef''', '''blocking_keys''' and '''number_of_points''' are read from the file if it is a .pts file, or the '''header''' and '''file_pointer''' are read from the assumed .csv file. In the .pts case we also initialize variables used for PTS blocking. || || '''next()''' || Read another block of data into memory. Return an instance of a new Geospatial_data object containing the data block read. || == Module Methods == || '''_set_using_lat_long(latitudes, longitudes, geo_reference, data_points, points_are_lats_longs)''' || Set the points data with lat/long values. If '''geo_reference''' is supplied will always throw exception? || || '''_read_pts_file(file_name, verbose=False)''' || Read a NetCDF .pts file and return (dict_points, dict_attributes, geo_reference). || || '''_read_csv_file(file_name, verbose=False)''' || Read a .csv file and return (dict_points, dict_attributes, geo_reference). || || '''_read_csv_file_header(file_pointer, delimiter=CSV_DELIMITER, verbose=False)''' || Read the header form an already open CSV text file. Returns the `cleaned` header and '''file_pointer''' (the open file handle). || || '''_read_csv_file_blocking(file_pointer, header, delimiter=CSV_DELIMITER, max_read_lines=MAX_READ_LINES, verbose=False)''' || Read a .csv file with blocking semantics - will raise StopIteration if no more data. Otherwise return (points, dict_attributes, geo_ref, file_pointer). || || '''_read_pts_file_header(fid, verbose=False)''' || Read .pts file header information from open file '''fid'''. Returns (geo_ref, attribute_keys, number_of_points). || || '''_read_pts_file_blocking(fid, start_row, fin_row, keys)''' || Read the body of a .pts file, with blocking semantics. Returns (point_list, attributes) where '''point_list''' is the points subset defined by ['''start_row''':'''fin_row'''] and '''attributes''' is the attributes from the same subset. || || '''_write_pts_file(file_name, write_data_points, write_attributes=None, write_geo_reference=None''' || Write a .pts data file to a file '''file_name'''. '''write_data_points''' holds the points data to write. '''write_attributes''' contains the attributes to write. '''write_geo_reference''' is the Geo_reference data to write. || || '''_write_csv_file(file_name, write_data_points, write_attributes=None, as_lat_long=False, delimiter=',')''' || Write paoint and attributes data to a .csv file '''file_name'''. If '''as_lat_long''' is True write coordinates out as lat/long. || || '''_write_urs_file(file_name, points, delimiter=' ')''' || Write points data to a URS file '''file_name'''. '''points''' data is in lat/long form. || || '''_point_atts2array(point_atts)''' || Convert a dictionary of points data into a dictionary of num.array data. Input dictionary has keys 'pointlist' of points data and key 'attributelist' which is a dictionary of attributes data. Changes '''point_atts''' in-place. || || '''geospatial_data2points_dictionary(geospatial_data)''' || Convert a geospatial object to a dictionary of points. Dictionary is left with keys 'pointlist' which contains a list/array of points, 'attributelist' which is a dictionary of key:value pairs and 'geo_reference' which is the geo_reference object. || || '''points_dictionary2geospatial_data(geospatial_data)''' || Convert a dictionary of points to a Geo_spatial object. Inverse of geospatial_data2points_dictionary() above. || || '''ensure_absolute(points, geo_reference=None)''' || Ensure that a set of points are in absolute coordinates. If '''geo_reference''' is specified, assume the points are relative to it. || || '''ensure_geospatial(points, geo_reference=None)''' || Convert a set of points to a Geospatial_data instance. '''geo_reference''' may be either a Geo_reference object or a 3-tuple of (zone, easting, northing). || || '''old_find_optimal_smoothing_parameter(data_file, alpha_list=None, mesh_file=None, boundary_poly=None, mesh_resolution=100000, north_boundary=None, south_boundary=None, east_boundary=None, west_boundary=None, plot_name='all_alphas', split_factor=0.1, seed_num=False, cache=False, verbose=False)''' || Using a sample of points from '''data_file''' and a selection of alpha values from '''alpha_list''' returns the alpha value that has the smallest covariance between the predicted value and removed values. || || '''find_optimal_smoothing_parameter()''' || Obsolete version of the above function. || == Notes == This class is defined in the 'old' way. Will need to be changed for python 2.6/3.x. '''Way too overloaded in the constructor.''' For instance, data_points are `either` a 2-dimensional array of points `or` a filename of input data. Yet there is another '''file_name''' parameter!? Maybe better not to fill with data in the constructor but call one of a selection of 'fill_with_data' routines later. Not sure that building blocking into this class is the correct approach. Probably better to override file semantics to provide blocking and then get this class to contain a reference to a file-like object to get data from. See above point. Overloaded way too much in some methods. For instance, get_data_points() should be broken up into a simple method and attributes that control UTM/lat/long coordinates, southern/northern hemisphere, etc. Return values overloaded too much. For instance, get_all_attributes() should '''always''' return an empty dictionary if no attributes, not "either an empty dictionary or None". ----- == [https://datamining.anu.edu.au/anuga ANUGA]/[InternalArchitecture Internal Architecture]/[wiki:Classes Classes] ==