-------------------------------------------------------------------------------
help for airnet
-------------------------------------------------------------------------------

Airline Traffic Network Construction

        airnet , [ options ]

Description

    airnet creates weighted and directed inter-airport or inter-city networks
    using data from the Bureau of Transportation Statistics' Origin and
    Destination Survey (DB1D).  (NOTE: This command does not affect the data
    in memory.)


Options
    stub(str) specifies the stub (if any) used to name input (ticketstub.csv
        and couponstub.csv) and output (airnetstub.dta) files.
    alpha(real) sets the alpha-level used for identifying likely business and
        leisure passengers.  The default is 0.05.
    maxfare(real) and minfare(real) sets the maximum and minimum credible
        fares; fares outside these limits are not used in calculations to
        identify business and leisure passengers.  The defaults are $5000 and
        $20.
    legtype separately reports the number of passengers traveling on each
        type of leg in a route network (i.e. first, last, middle, and only).
    matrix saves the route, origin-destination, business, and leisure
        networks in matrix form as separate comma-delimited files.
    metro(new | old) aggregates airports into metropolitan areas (cannot be
        used with intl; see below for details).
    intl(1 | 2 | 3 | 4) constructs a partial, international route network for
        the given quarter (cannot be used with metro; see below for details).
    descriptives returns selected descriptives concerning the raw data in
        r().


Input
    airnet requires two input files, which may be obtained from the BTS
    website.  Both files must be located in the working directory.

      ticketstub.csv - A comma-delimited file generated from the DB1BTicket
      database, containing only the following variables: ItinID, RoundTrip,
      Passengers, ItinFare.  available here
 
      couponstub.csv - A comma-delimited file generated from the DB1BCoupon
      database, containing only the following variables: ItinID, MktID,
      Origin, Dest, SeqNum.  available here


Output
    airnet produces several types of airline traffic networks, each stored in
    edgelist-format as a separate variable in airnetstub.dta:

      Route - Edges indicates the number of passengers that flew from orig to
      dest.  Using the legtype option decomposes this total by the leg's
      position in the passenger's trip: first leg, last leg, a middle leg, or
      the only leg.
 
      Origin-Destination (origdest) - Edges indicate the number of passengers
      that flew from an initial origin in orig to a final destination in
      dest; any intermediate stops are ignored.
 
      Single-Destination Round-Trip (sdrt) - A subset of the
      origin-destination network that includes only passengers taking
      single-destination round-trip flights.
 
      Business Passengers (business) - A subset of the SDRT network that
      includes only passengers that flew alone and paid a significantly
      above-average fare for travel between the same origin and destination
      airports.
 
      Leisure Passengers (leisure) - A subset of the SDRT network that
      includes only passengers that flew with one or more companions and paid
      a significantly below-average fare for travel between the same origin
      and destination airports.


The -metro- option
    Using the metro option aggregates airports into metropolitan areas, and
    thus results in the construction of intercity, rather than interairport,
    networks.  The aggregation is performed only for the 139 airports
    identified by the Federal Aviation Administration as "Primary Hubs" in
    2010.  This option also creates a variable containing the great circle
    distance (in km) between metropolitan areas, which is stored in the
    "distance" variable in the airnetstub.dta and, if the matrix option is
    specified, is saved as a matrix.  The aggregation units are set by the
    suboption:

      metro(old) - Airports are aggregated into Consolidated Metropolitan
      Statistical Areas (CMSAs) and Metropolitan Statistical Areas (MSAs)
      using 1999 US Census definitions.
 
      metro(new) - Airports are aggregated into Consolidated Statistical
      Areas (CSAs) and Metropolitan Statistical Areas (MSAs) using 2009 US
      Census definitions.


The -intl- option
    The intl option constructs a partial, international route network in
    addition to the complete, domestic networks constructed by airnet.  This
    network contains all intra-US route edges and all route edges between US
    and international airports, but does not include route edges between
    international airports.  It is stored in the "routeintl" variable in the
    airnetstub.dta, and if matrix is specified, is also saved as a matrix.
    International origin-destination pairs are coded as missing.  This
    international route network is constructed from supplementary BTS T-100
    data, and requires an additional input file:

      intlstub.csv - A comma-delimited file generated from the T-100
      International Segment database, containing only the following
      variables: Passengers, Origin, Dest, Quarter.

    This file may be obtained from the BTS website (available here) and must
    be located in the working directory.  The downloaded data should cover
    all months in the desired year, and the quarter of the BTS DB1B data
    (i.e. the data in ticketstub.csv and couponstub.csv) should be identified
    in the intl option.  For example, if ticketstub.csv and couponstub.csv
    contain data on air traffic in the 2nd quarter (April-June) of 2010, the
    intlstub.csv file should contain data for all months in 2010 and the
    option should be specified as intl(2).


Saved Results
    If the descriptives option is specified, airnet saves the following in
    r():

      r(movements) - Number of intra-US passenger movements
      r(airports) - Number of US airports
      r(all_pass) - Number of intra-US passengers
      r(sdrt_pass) - Number of intra-US passengers taking single-destination
      round-trips
      r(lowfare) - Number of intra-US passengers paying less than the minimum
      credible fare
      r(highfare) - Number of intra-US passengers paying more that the
      maximum credible fare
      r(time) - Command running time, in seconds.


References
Neal, Z. P. 2010. Refining the air traffic approach: An analysis of the US city
     network, Urban Studies 47: 2195-2215. (CLICK FOR PDF)

Author
Zachary Neal
Department of Sociology
Michigan Sate University
zpneal@msu.edu