PyCDA Submodules

Detectors

class pycda.detectors.CustomDetector(model_path, rec_batch_size=1, in_out_map='center')

Bases: pycda.detectors.DetectorBaseClass

This class allows a user to load a custom detection model into PyCDA. PyCDA will automatically detect input and output dimensions. All models are channels-last; channels-first is not currently supported. You should specify recommended batch size. (if not specified, set to 1.)

Use model_path argument to specify the path to your keras model.

predict(batch)

returns a batch of random-pixel images with appropriate shape.

class pycda.detectors.DetectorBaseClass

Bases: object

This is the base class for a detector object. Attributes in the __init__ method should be specified by child detectors.

predict(batch)

Predict method takes a batch and returns a batch of predictions. Output should be a batch of single-channel images of shape: (batch_size, self.output_dims[0], self.output_dims[1], 1)

class pycda.detectors.TinyDetector

Bases: pycda.detectors.DetectorBaseClass

A tiny version of U-Net downsized for speed. Its output is a per-pixel likelihood that a given pixel is a part of a crater surface feature. Single color channel (grayscale).

predict(batch)

returns a batch of random-pixel images with appropriate shape.

class pycda.detectors.UnetDetector

Bases: pycda.detectors.DetectorBaseClass

U-net convolutional model to generate pixel-wise prediction. Its output is a per-pixel likelihood that a given pixel is a part of a crater surface feature. Single color channel (grayscale).

predict(batch)

returns a batch of random-pixel images with appropriate shape.

pycda.detectors.get(identifier)

handles argument to CDA pipeline for detector specification. returns an initialized detector.

Extractors

class pycda.extractors.ExtractorBaseClass

Bases: object

Base class for an extractor object. The extractor converts a prediction map into a list of crater candidates.

class pycda.extractors.FastCircles(sensitivity=0.5)

Bases: pycda.extractors.ExtractorBaseClass

Circle Extractor assumes all objects in detection map are circles. It identifies groups of pixels, computes their mean location (centroid), and diameter based on the number of pixels in the group. Takes a prediction object and returns a list of proposals.

class pycda.extractors.WatershedCircles(sensitivity=0.5)

Bases: pycda.extractors.ExtractorBaseClass

Takes a prediction object after detection and returns a list of crater proposals (by calling object on prediction.) Performs a ‘watershed’ analysis: -transforms image to binary for some threshold (default .5) -transforms pixel values to min distance to background (0) pixel -uses local maxima as points for ‘water sources’ -uses negative distance values to build ‘basins’ -fills ‘basins’ with water from sources -uses the boundaries where ‘water meets’ as segment boundaries -objects are converted to circles whose center is the centroid of the bounding box of the object, diameter is the mean(width, height) of bounding box.

pycda.extractors.get(identifier)

handles argument to CDA pipeline for extractor specification. returns an initialized extractor.

Classifiers

class pycda.classifiers.ClassifierBaseClass

Bases: object

Base object for crater classifier. Classifiers make a binary prediction on a crater proposal and return a value between zero and one; one represents a true crater and zero represents a false proposal.

predict(batch)

Prediction call should return an array of predictions of length of batch.

class pycda.classifiers.ConvolutionalClassifier

Bases: pycda.classifiers.ClassifierBaseClass

12x12 pixel classifier using 2D convolution implimented with Keras on tensorflow backend. Fast.

predict(batch)

Performs prediction on batch.

class pycda.classifiers.CustomClassifier(model_path, crater_pixels, rec_batch_size=24)

Bases: pycda.classifiers.ClassifierBaseClass

This class allows a user to load a custom classifier into PyCDA. PyCDA will automatically detect input dimensions. Provide crater_size, the number of pixels the crater candidate diameter should occupy in the cropped image. All models are channels-last; channels-first is not currently supported. You should specify recommended batch size. (if not specified, set to 24.) Use model_path argument to specify path to keras model.

predict(batch)

Performs prediction on batch.

class pycda.classifiers.NullClassifier(input_dims=(1, 1), n_channels=1)

Bases: pycda.classifiers.ClassifierBaseClass

For use when classifier is not wanted. Returns a likelihood of 1 for every proposal.

predict(batch)

Returns an array of randomly-generated predictions of length of batch.

pycda.classifiers.get(identifier)

handles argument to CDA pipeline for classifier specification. returns an initialized classifier.

Predictions

class pycda.predictions.Prediction(image, id_no, cda)

Bases: object

A prediction object is a specialized data handler for pycda. It tracks the progress of predictions on an input image, helps the pipeline track information, and can perform auxiliary functions that help the user inspect the prediction, save the results, export csv files, and modify hyperparameters.

get_proposals()

Returns a dataframe with crater proposals and likelihoods from classifier.

set_scale(scale)

User can set scale for statistics in meters. scale should be meters per pixel; pass scale as float or int as argument, saves scale to prediction object.

show(threshold=0.5, include_ticks=True, save_plot=False)

Displays the input image with the predicted craters overlaid.

show_detection(remove_ticks=True)

Plots the detection map alongside the input image.

to_csv(filepath, likelihoods=False, index=False)

Creates a csv file with predictions. If likelihoods is True, a likelihoods column is added to the csv file. Saves csv to filepath usind pd.to_csv method.

Error Stats

class pycda.error_stats.ErrorAnalyzer

Bases: object

Error Analyzer is used to measure predictive performance of cda. It is intended for use on images where all craters have been hand labeled and so are “known”. The PyCDA prediction object accepts known craters as a pandas dataframe under the attribute prediction.known_craters; the columns ‘lat’, ‘long’, and ‘diameter’ should be populated with approprate values for known crater objects for use with ErrorAnalyzer.

analyze(prediction, verbose=True)

Takes a prediction object and performs analysis on it. Raises an exception if no known crater labels are attributed to the input prediction object.

plot_densities(verbose=True)

Generates histogram plot with predicted and actual crater densities by size.

print_report()

Prints performance statistics for prediction.

return_results()

Returns a tuple: one df predictions with additional column (positive) with boolean values; another df with craters and an additional column (detected) with boolean values.

return_stats()

Returns scoring stats: true positive count, false positive count, false negative count, f1-score, and some other binary error statistics.

show()

Displays the input image with predictions and known craters displayed by colors.

Sample Data

pycda.sample_data.get_sample_csv(filename='holdout_tile_labels.csv')

Retrieves hand-labeled crater annotations for image holdout_tile.pgm (default returned by get_sample_image()). Returns pandas dataframe.

pycda.sample_data.get_sample_image(filename='holdout_tile.pgm', choose=False)

Retrieves sample data from the in-package directory. if choose=True, randomly selects sample photo from package.