is_out_of_china: Detect whether the points are outside China
In madlogos/asesgeo: ASES Analytic Toolkit on Geographics

Description Usage Arguments Details Value Author(s) See Also Examples

Analyzes the coordinates (lat, lon) to check whether they are in or out of China. You can choose to return a logical vector or a ggplot2 object for quick visualization.

isOutOfChina(y, ..., accurate = TRUE, gcs = c("WGS-84", "GCJ-02",
  "BD-09"), plot = FALSE, canvas = c("china", "world"),
  xlim = c(72.004, 137.8347), ylim = c(0.8293, 55.8271),
  auto_fix_latlng = TRUE)

`y`	one of coordinate pair: a list of coordinate vectors `list(lat1, lon1)`, in which case you can provide other coordiante vectors in `...` latitude vector: latitude number(s), in which case you need to provice longitute number(s) in `...` coordinate matrix: a matrix (row 1-2 or col 1-2). The function will choose how to read the data coordinate data.frame: a data.frame (col 1-2)
`...`	one of coordinate pairs: when `y` is a list containing a coordinate pair (e.g., `list(lat1, lon1)`), you can pass other coordinate pairs here (e.g., `list(lat2, lon2), list(lat3, lon3), ...`). longitude vector: when `y` is only latitude vector, you can pass `x` (longitude) here. when `y` is a coordinate matrix or data.frame, `...` is omitted.
`accurate`	logical, whether use accurate China boundary to analyze the coordinates. Default TRUE. When using the accurate China boundary, the function will check if the coordinates (Lat, Lon) are actually inside China's territory. When set FALSE, the function will use a very vague rectangle defined by `xlim` and `ylim` to reprensent China boundary.
`gcs`	character, the geo-coordinate system, 'WGS-84', 'GCJ-02' or 'BD-09'. Default 'WGS-84'. The function will analyze the points (Lat, Lon) under the specific gcs.
`plot`	logical, if generate a plot to show the location of the points.
`canvas`	character, 'china' or 'world'. It is only effective when `plot` == TRUE. If 'china', the plot is restricted to east Asia, with the projection 'azequalarea', orientation of c(30, 105) with no rotation. If 'world', the plot is the full 'world' map, with the projetion 'mercator'.
`xlim`	numeric vector of length 2. The longitude limits of the China map. Default c(72.004, 137.8347). when `accurate` is FALSE, the rectangle made by xlim and ylim will be used as China.
`ylim`	numeric vector of length 2. The latitude limits of the China map. Default c(0.8293, 55.8271). when `accurate` is FALSE, the rectangle made by xlim and ylim will be used as China boundary.
`auto_fix_latlng`	logical, if the lat/lng data is of the opposite order, whether to let the function automatically fix it. Default TRUE.

The most popular open-source coordinate transformation algorithm regards China as a rectangle. Points outside this rectangle are treated as 'outside China', of which case the conversion from WGS-84 ==> GCJ-02 / BD-09 is not conducted. This function inherits this algorithm as well. As a step further, it prepares an 'accurate' method that use the actual China boundary to analyze the input points. Due to the limitation of proj.4 library, it plots the points and China boundary under 'WGS-84' system.

Depends on plot,

TRUE: returns a 'ggplot2' object.
FALSE; returns a logical vector with the same length of Lat (or Lon).

. Note that the point pairs with either lat or lng missing will yield NA anyway.

Yiying Wang, wangy@aetna.com

Refer to transform_coord function family for argument y, ...

## Not run: 
is_out_of_china(c(10, 30, 40, 50, 70), c(100, 120, 100, 140, 160), 
                accurate_=TRUE)  
# 10.00,100.00 30.00,120.00 40.00,100.00 50.00,140.00 70.00,160.00 
# TRUE         FALSE        FALSE        TRUE         TRUE

is_out_of_china(c(10, 30, 40, 50, 70), c(100, 120, 100, 140, 160), 
                accurate=FALSE)
# 10.00,100.00 30.00,120.00 40.00,100.00 50.00,140.00 70.00,160.00 
# FALSE        FALSE        FALSE        TRUE         TRUE 

## visualize the positions
is_out_of_china(c(10, 30, 40, 50, 70), c(100, 120, 100, 140, 160), 
                plot=TRUE, canvas='china')
is_out_of_china(c(10, 30, 40, 50, 70), c(100, 120, 100, 140, 160), 
                plot=TRUE, canvas='world')              

## End(Not run)