[R-sig-Geo] API documentation?

Tue Jul 1 00:39:00 CEST 2008

On Mon, 30 Jun 2008, David Hugh-Jones wrote:

> Guys
>
> I don't mean to rant, but believe me, I've spent plenty of time with
> the documentation and it's really not helping.
>
> Partly this is a problem of R's doc format which treats package
> documentation as an alphabetical list of functions - which gives me no
> idea where to start.

This is an inherent (and perhaps ugly) characteristic of the S4 
object/class structure as you suggest below. New style classes are not as 
well integrated into the documentation as straight functions are. Here, 
coerce is as(), but the issue of how to improve documentation is not 
resolved.

>
> This then interacts badly with the OO structure. For example, look at
> the 20+ pages on "coerce". Hmm, what does "coerce" actually do? In
> fact that's in a whole different library. But I didn't know that, so I
> click on a page at random, say
>
> coerce,SpatialGrid,data.frame-method
>
> and this takes me to SpatialGrid class - which doesn't mention coerce
> at all. (Nor does it tell me what SpatialGrid is, or what it is used
> for.)
>
> On the other hand, maybe I might guess that to get a list of
> coordinates, I'd use "coordinates". So I click on that method, and it
> tells me yes, this "retrieves spatial coordinates". But unfortunately
> it retrieves them hidden inside another object ("an object of class
> SpatialPointsDataFrame"). OK, but how do I get the _actual_data_?
> Maybe the SpatialPointsDataFrame class page will tell me. Nope. Et
> cetera.
>
> Rick: yes, I agree that using the internal data structures is how to
> do things, but this is broken isn't it? The whole point of having OO
> is to be able to use it _without_ understanding the internal data
> structures. The ideal, in other words, would be to have a "thin.lines"
> method that I could just run on any polygon or set of polygons.
> Failing that, then I should be able to get at the internal data
> without hours of head scratching.
>

No, because the underlying understanding of dp and other methods for 
thinning is that the objects implement an arc-node topological model, so 
that each arc can be thinned without different thinning happening on 
otherwise identical boundaries of neighbouring polygons. But we do not 
have an arc-node representation, so there cannot be line thinning for 
polygon boundaries in a spaghetti world.

> Right now, it's like, everything is hidden behind a layer of classes
> and slots and methods, but I still need to go behind that layer to get
> at the actual raw data, and this is so complicated and confusing that
> it would be easier just to work with the raw data.
>

You need to build topology first, so if need be take the data out to a GIS 
that does topology properly, do the arc line thinning there, and bring it 
back in. Building topology from a stream of straight line segments is a 
serious challenge, especially if you want to retain the association with 
attribute data.

Roger

> OK, I'll stop venting. If there's anything I could do to improve this
> situation, I would gladly try.
>
> David Hugh-Jones
> PhD Candidate
> Essex University Department of Government
> http://davidhughjones.googlepages.com
>
>
> 2008/6/30 Virgilio Gomez-Rubio <v.gomezrubio at imperial.ac.uk>:
>> Dear David,
>>
>> Probably the best way to start is by checking the HTML documentation. It
>> should be installed locally but it is also accesible, for example, here:
>>
>> http://finzi.psych.upenn.edu/R/library/sp/html/00Index.html
>>
>> Hope this helps.
>>
>> Virgilio
>>
>> On Mon, 2008-06-30 at 18:48 +0200, David Hugh-Jones wrote:
>>> Thanks David for his comment about dp.
>>>
>>> Quick question: is there any reasonably comprehensible API
>>> documentation for the "sp" package? I have just spent about an hour
>>> trying to get a list of points from a SpatialPolygons object. I
>>> eventually just printed everything out and found the data by hand, so
>>> now I am doing:
>>>
>>> coords <- myobject at polygons[[1]]@Polygons[[1]]@coords
>>>
>>> but I don't assume that is right. Surely there must be some simple way
>>> to get a list of x and y coords out of any object?
>>>
>>> in frustration,
>>> David Hugh-Jones
>>> PhD Candidate
>>> Essex University Department of Government
>>> http://davidhughjones.googlepages.com
>>>
>>>
>>> 2008/6/30 David PINAUD <pinaud at cebc.cnrs.fr>:
>>>> maybe you can try the function dp() in the package "shapefiles", which is an
>>>> implementation of the Douglas-Peucker polyLine simplification algorithm.
>>>> Hope it helps
>>>> David
>>>>
>>>> David Hugh-Jones a écrit :
>>>>>
>>>>> Hi all
>>>>>
>>>>> I have a big dataset of points and am doing stuff on them that takes a
>>>>> lot of time. To speed it up, I would like to use "thinlines" from
>>>>> RArcinfo, which basically makes the maps "rougher" by throwing away
>>>>> points. Is there an equivalent function for SpatialPolygon type
>>>>> objects? (I assume that there's no way to convert _to_ Arcinfo, though
>>>>> I know it's possible to read from it).
>>>>>
>>>>> Cheers
>>>>>
>>>>> David Hugh-Jones
>>>>> PhD Candidate
>>>>> Essex University Department of Government
>>>>> http://davidhughjones.googlepages.com
>>>>>
>>>>> _______________________________________________
>>>>> R-sig-Geo mailing list
>>>>> R-sig-Geo at stat.math.ethz.ch
>>>>> https://stat.ethz.ch/mailman/listinfo/r-sig-geo
>>>>>
>>>>>
>>>>>
>>>>>
>>>>
>>>> --
>>>> ***************************************************
>>>> David PINAUD
>>>> Ingénieur de Recherche "Analyses spatiales"
>>>>
>>>> Centre d'Etudes Biologiques de Chizé - CNRS UPR1934
>>>> 79360 Villiers-en-Bois, France poste 485
>>>> Tel: +33 (0)5.49.09.35.58
>>>> Fax: +33 (0)5.49.09.65.26
>>>> http://www.cebc.cnrs.fr/
>>>>
>>>> ***************************************************
>>>>
>>>>
>>>>
>>>>
>>>> ________ Information from NOD32 ________
>>>> This message was checked by NOD32 Antivirus System for Linux Mail Servers.
>>>> http://www.eset.com
>>>
>>> _______________________________________________
>>> R-sig-Geo mailing list
>>> R-sig-Geo at stat.math.ethz.ch
>>> https://stat.ethz.ch/mailman/listinfo/r-sig-geo
>>
>>
>
> _______________________________________________
> R-sig-Geo mailing list
> R-sig-Geo at stat.math.ethz.ch
> https://stat.ethz.ch/mailman/listinfo/r-sig-geo
>

-- 
Roger Bivand
Economic Geography Section, Department of Economics, Norwegian School of
Economics and Business Administration, Helleveien 30, N-5045 Bergen,
Norway. voice: +47 55 95 93 55; fax +47 55 95 95 43
e-mail: Roger.Bivand at nhh.no