GainPatterns

This package allows manipulation of gain patterns. A gain pattern is a collection of gains (or strengths) versus angle. If you have a vector of angles, and a vector of gains taken at these angles, you can create a GainPattern. You can then create publication-ready plots of these gain patterns using PGF with the GainPatternsTex.jl package.

This package also allows you to manipulate gain patterns as well. For example, you can normalize a gain pattern (subtract mean gain from every element, and divide by std deviation). You can shift a gain pattern by some number of degrees. You can add constant values to gain patterns. You can also sample possible gains from a gain pattern.

This package does not generate gain patterns. That is, given some antenna configuration, this will not calculate what the gain pattern should look like. That would be useful, but is outside the scope of this package (for now). At the moment, the package is mostly a plotting tool.

If you would like to plot GainPatterns, check out the GainPatternsTex.jl package.

A GainPattern has three fields:

• angles, a vector of angles (in degrees) at which the gains are sampled at,
• meangains, a vector of the gains. meangains[i] is the gain measured at angles[i],
• samples, a vector of the samples.

You can create a gain pattern with the samples. You can also create a gain pattern from a csv file, where the first column is the angles at which measurements were taken (in degrees, 0-359), and any subsequent columns are gain values taken at those degrees.

gp1 = GainPattern(angles, gains)
gp2 = GainPattern("file.csv")

A GainPattern can be saved to a csv file using csv. First column is angles, second column is meangains.

csv(gp)						# saves file to temp.csv
csv(gp, "filename.csv")		# saves file to filename.csv

On top of plotting, you can perform the following manipulations on a GainPattern.

normalize!(gp::GainPattern) modifies gp by normalizing its meangains and samples.

rotate!(gp::GainPattern, degrees::Real) adds degrees to gp's angles vector.

sample(gp::GainPattern, angle::Real) randomly samples from gp's samples vector at a given angle. Currently, you must select an angle that exists in gp's angles vector. In the future, we could do some sort of interpolation.

sample(gp::GainPattern, angles::Vector{Real}) allows you to sample from a specified set of angles. Each sample in the angles parameter must exist in gp.

sample(gp::GainPattern) samples from gp's set of angles. A gain is sampled for every angle of gp. This is equivalent to calling sample(gp, gp.angles).

crosscorrelate(ref, sample, angles) performs a cross-correlation of the sample and a reference signal. The idea is that the reference is of length 360, and the sample can be of variable length. angles is a vector of the angles at which sample was sampled.

You can also add and subtract gain patterns. Addition and subtraction return new gain patterns. For example, gp1 + gp2 will create a new GainPattern. gp1 and gp2 need to have the same number of angles for addition/subtraction.

If the length of the sample vectors are the same for both gp1 and gp2, then the sample vectors are added/subtracted. If gp1 and gp2 have sample vectors of different lengths, then only the mean gains are added/subtracted, and the new gain pattern will be created just from this vector of added/subtracted mean gains.

You can also add a constant to a gain pattern. This adds a constant to the meangain and every sample.

If you simply want to combine two gain patterns, use addsamples!, as shown below:

addsamples!(gp1, gp2)

This will add the append the saples of gp2 to the samples of gp1.

Assumes you only have one sample (only looks at meangains). Returns angle corresponding to maximum meangains value. If there are multiple instances of this maximum value, this returns the angle corresponding to the first.

bearing_max(gp::GainPattern)

bearing_cc(test_file, ref_file)
bearing_cc()

angular_error(-5, 5)		# returns 10
angular_error(5, -5)		# returns 10

angular_error(340, 17)		# returns 37
angular_error(17, 340)		# returns 37

angular_error(340, -17)		# returns 3
angular_error(-17, 340)		# returns 3

NOTE: The angles provided must be within 360 degrees of each other or you will get odd behavior. Any of the examples above are ok, but if you did angular_error(5, 720), you will get 355 instead of 5 (the correct answer is 5). I will take care of this some day

You can also call angular_error on vectors.

You can also compute the relative error with angular_error_rel, which preserves a sign to indicate direction. The sign is positive if the shortest path is from the first angle and to the second.

angular_error_rel(5, 355)		# returns -10
angular_error_rel(355, 5)		# returns 10

angular_error_rel(-17, 340)		# returns -3
angular_error_rel(340, -17)		# returns 3

This is currently still very rough. Some things I want to add:

• Overhaul documentation and create Julia notebook with examples
• Create subtraction done
• Create shift! and flip! functions (for angles...)
• Allow log-axis for gains
• Make plots show up immediately (this is a PGFPlots issue)
• Test validgain function and overriding it done
• Create sample function to sample from a gain pattern at a given angle done
• If a samples vector has only one entry, eliminate it? or maybe not. Plotting doesn't seem to have an issue with this
• Group plots (you can't use tex grouplot package for this)
• ~~Sample an entire distribution and return an array (or fill one)~~done
• Normalize function for gainpatternsdone
• Allow for units on axes
• function that also prints samples (not just mean gains)
• Check if file exists with open (csv +elsewhere)
• Handle file extension stuff better (csv +elsewhere)

Future plans (like way down the road):

• Allow the use of PyPlot as well as PGFPlots
• Read in an image of a gain pattern and spit out the resulting values (a bit quixotic, but I suppose it is doable).
• Generate gain patterns for simple antennas. I do not currently have the knowledge to make that happen.

This came default with the package when I made it. Not sure what to do with it or what it does.