Merge pull request #247 from mcwdsi/copy-wiki-docs-to-docs

Copy wiki docs to docs and some initial edits and organization

docs/modeling/Home.md

@@ -0,0 +1,15 @@
+# Welcome to the OMRSE wiki!
+
+Read an [overview](OMRSE-Overview.md) of the OMRSE ontology
+
+## Specific modeling decisions:
+ -  [Healthcare facilities](Typology-of-Health-Care-Facilities.md)
+ -  [Hospital discharge & discharge status](Modeling-Discharge-and-Discharge-Status.md)
+ -  [Householder](Householder.md)
+ -  [Housing unit & household](Housing-unit-and-Household.md)
+ -  [Insurance, especially health insurance](Insurance.md)
+ -  [Language](OMRSE-Language-and-Language-Individuals.md)
+ -  [Language as codified by ISO-639](Representing-Languages-as-codified-by--ISO-639.md)
+ -  [Race and ethnicity](Race-And-Ethnicity.md)
+ -  [Relation between a role and the organization that creates it](What-is-the-relation-between-a-role-and-the-organization-that-creates-sanctions-confers-it.md)
+ -  [Smoking status](PCORNet-Smoking-Status.md)

docs/modeling/Householder.md

@@ -0,0 +1,24 @@
+# US Census Householder 
+
+US Census
+"The householder refers to the person (or one of the people) in whose name the housing unit is owned or rented (maintained) or, if there is no such person, any adult member, excluding roomers, boarders, or paid employees. If the house is owned or rented jointly by a married couple, the householder may be either the husband or the wife. The person designated as the householder is the "reference person" to whom the relationship of all other household members, if any, is recorded.
+
+"The number of householders is equal to the number of households. Also, the number of family householders is equal to the number of families.
+
+"Head versus householder. Beginning with the 1980 CPS, the Bureau of the Census discontinued the use of the terms "head of household" and "head of family." Instead, the terms "householder" and "family householder" are used. Recent social changes have resulted in greater sharing of household responsibilities among the adult members and, therefore, have made the term "head" increasingly inappropriate in the analysis of household and family data. Specifically, beginning in 1980, the Census Bureau discontinued its longtime practice of always classifying the husband as the reference person (head) when he and his wife are living together."
+http://www.census.gov/cps/about/cpsdef.html
+
+* Sufficient condition - being the only person who maintains (owns or rents) the housing unit in their name.
+
+* Necessary conditions: adult, member of the household, not paying another member of the household to live there; not a paid employee of the household.
+
+Notes: There is one householder to household.  The householder role is individuated by households.  Can one person by the householder of many households?  (Look at Utah census data.) The householder also plays the role of US Census reference person.
+
+Proposed definition:
+A US Census householder role is a human social role that inheres in a Homo sapiens and is realized by that person being a member of a household and either owning or renting the housing unit in which that household resides and being designated as the householder.  If there is only one member of the household who owns or rents the housing unit, that person is designated the householder by default.  
+
+# US Census Reference Person
+
+"The reference person is the person to whom the relationship of other people in the household is recorded. The household reference person is the person listed as the householder (see definition of "Householder"). The subfamily reference person is either the single parent or the husband/wife in a married-couple situation."
+
+Do we need to model "US Census reference person"?

docs/modeling/Housing-unit-and-Household.md

@@ -0,0 +1,52 @@
+## Background
+We have a use case to represent households and housing units in the Modeling Infectious Disease Agent Study (MIDAS) Informatics Services Group (ISG). Specifically, we are representing synthetic ecosystem datasets, which are datasets that are derived from so-called "micro-samples" of actual census data.  To build agent-based epidemic simulators, researchers will often take samples of census data and expand them back up to the size of the entire population according to statistical algorithms that ensure the re-created overall population dataset matches the actual population in terms of race, gender, ethnicity, geographical distribution, and so on.
+
+For modelers, finding a synthetic ecosystem that meets their needs in terms of geography, other entities represented (such as households, schools, and workplaces) is a key issue.  We are building the Ontology-based Catalog for Infectious Disease Epidemiology (OBC.ide) to help modelers and analysts find synthetic ecosystems and other information resources.
+
+We wish to transform some existing synthetic ecosystem data into RDF and need key ontology classes for it.  Two of these classes are housing unit and household.
+
+## Preliminaries 
+Because our synthetic ecosystem data are based on US Census data, we propose initially to use definitions from the US Census:
+
+**household**: The Census defines it as ...<em>all the people who occupy a housing unit.</em>  Source: http://www.census.gov/cps/about/cpsdef.html.
+
+**housing unit**: The Census says  <em>A house, an apartment or other group of rooms, or a single room, is regarded as a housing unit when it is occupied or intended for occupancy as separate living quarters; that is, when the occupants do not live with any other persons in the structure and there is direct access from the outside or through a common hall.</em>
+
+Per OMRSE, the entire apartment building would be an instance of **architectural structure**.  So each apartment unit in it is not an architectural structure.  It is a part of it.  However, in the case of a detached, single-family home, the housing unit is indeed an architectural structure.
+
+So at minimum, a housing unit is a part of an architectural structure (the reflexivity of part of handles the single-family home case).
+
+The Census criterion of direct access from outside or through a hall common to other housing units is a good one.  Also we note that mobile homes are sufficiently attached to the ground when serving as a housing unit to meet the definition of 'architectural structure'.
+
+One key issue to decide is what about house boats and recreational vehicles?  They clearly are not architectural structures (lack connection to ground).  But they serve a particular housing function.
+
+Here is how the US Census addresses the issue: <em>Both occupied and vacant housing units are included in the housing unit inventory, except that recreational vehicles, boats, vans, tents, railroad cars, and the like are included only if they are occupied as someone's usual place of residence. Vacant mobile homes are included provided they are intended for occupancy on the site where they stand. Vacant mobile homes on dealer's sales lots, at the factory, or in storage yards are excluded from the housing unit inventory.</em>  Source: https://www.census.gov/popest/about/terms/housing.html.
+
+So a house boat or a recreational vehicle is only a housing unit if it is someone's "usual place of residence", else it is not.  A mobile home is only a housing unit if it is an architectural structure.
+
+## Definitions
+housing unit: a material entity that has as parts one or more sites that serve to (1) protect persons and their possessions from weather (wind, rain, sun, snow) and (2) are designed for sleeping of said persons.
+
+In this sense a cave is not a housing unit until someone adapts it for sleeping there regularly.  This definition seems to cover vehicular residences, architectural residences, and natural geological (and maybe other natural?) formation residences.
+
+Many residences also serve as places to prepare and eat food.
+
+**Residence function** - the function of a material entity, with one ore more sites as proper parts and that are large enough to contain humans, to protect persons and their possessions from weather and for one ore more of its sites to be the place where humans sleep.
+
+For the U.S. Census then, architectural structures that bear a residence function and vehicles that are realizing a residence function, are housing units.  Also, the U.S. Census says a mobile home does not bear a residence function until it becomes an architectural structure (it is suitably sited and anchored to the ground).
+
+Remaining issue: tents.  For U.S. Census, tents are not housing units unless they are realizing a residence function.  A tent does not have as "firm [a] connection between its foundation and the ground" so we would exclude them as architectural structures.  They don't fit category of vehicle or natural formation either.  
+
+housing unit - a material entity that bears a residence function and that has one or more sites as proper parts that contribute to the realization of this function, whereby 
+
+Okay, so key problem is capturing doors to common hallways.  The idea is that sites are connected to outside via doors (they're connected by windows, too, but let's assume we can define the difference adequately) or they're connected to a common, public area.  Wow, what do we mean by public?  Do we need to include the idea of privacy in the definition of housing unit?
+
+A housing unit could have both a door to a common hallway and a door outside to a private, fenced in area.  Or even a door out to a deck.
+
+Plus, per the definition of 'site' in BFO, each room is a site.
+
+So if we say door has to be outside, we cannot define apartments adequately.  If we say also that door could be to another site, that's too inclusive (then every room is a housing unit).  
+
+So the key is to differentiate the common apartment hallway from the foyer of your house.  Which I think brings us back to privacy.
+
+After discussion, we have figured out that the solution is that a housing unit is distinguished by being the bearer of exactly one residence function, which is designed into the structure by humans.  So, each apartment, house, townhouse, tent, RV, etc. is a collection of sites that is the bearer of one residence function.

docs/modeling/How-are-household-and-housing-unit-related?.md

@@ -0,0 +1,14 @@
+The members of the household are participants of a process that realizes the residence function.  Whether they or the housing unit itself is the agent of the process is an interesting question.
+
+So if we had particulars as follows:
+
+hh1 - household #1
+hu1 - housing unit #1
+rf1 - residence function #1
+p1 - process #1
+
+hh1 'is participant of'  p1
+p1  'realizes'     rf1
+rf1 'inheres in'   hu1
+
+One issue is that it means that there is no connection between a household and the housing unit until at least one member of the household sleeps there.  Based on my (Bill Hogan) own experience with moving to Gainesville last year, I'm down with it.

docs/modeling/Insurance.md

@@ -0,0 +1,49 @@
+This page discusses questions relevant to modeling insurance and insurance policies in OMRSE
+
+In Clarke v Clarke, (1993) 84 BCLR 2d 98, the BC Supreme Court accepted this definition (of life or disability insurance):
+"A contract by which one party undertakes, in consideration for a payment (called a premium), to secure the other against pecuniary loss, by payment of a sum of money in the event of the death or disablement of a person."(http://www.duhaime.org/LegalDictionary/I/Insurance.aspx, accessed July 20, 2015)
+
+And 
+
+"A contract whereby, for specified consideration, one party undertakes to compensate the other for a loss relating to a particular subject as a result of the occurrence of designated hazards. … A contract is considered to be insurance if it distributes risk among a large number of persons through an enterprise that is engaged primarily in the business of insurance. Warranties or service contracts for merchandise, for example, do not constitute insurance. They are not issued by insurance companies, and the risk distribution in the transaction is incidental to the purchase of the merchandise. Warranties and service contracts are thus exempt from strict insurance laws and regulations.” (http://legal-dictionary.thefreedictionary.com/insurance, accessed July 20, 2015)
+
+"A contract (an insurance contract) whereby one person, the insurer, promises and undertakes, in exchange for consideration of a set or assessed amount of money (called a "premium"), to make a payment to either the insured or a third-party if a specified event occurs, also known as "occurrences"." (http://www.duhaime.org/LegalDictionary/I/Insurance.aspx, accessed July 20, 2015)
+
+From Couch on Insurance, 3rd Edition: "while a policy of insurance, other than life or accident insurance, is basically a contract of indemnity, not all contracts of indemnity are insurance contracts; rather, an insurance contract is one type of indemnity contract.”
+
+1. An **insurance policy** is a **contract**.  More specifically, it's a type of **indemnity contract**.
+* What's the relationship between a contract and a document act?  An insurance policy is a contract that is a document that has as parts action, conditional, plan, and objective specifications.  It is the specified output of a document act.
+2. It is distinguished from other indemnity contracts by distributing the risk among a group of persons through an organization.
+3. Insurance policies are the specified output of a document act. (Is this right?)
+4. That document act has as participants (1) a group of persons (the **insured parties**) and (2) the organization that issues the plan. (From 2) The organization and the **primary insured persons on the policy** are parties to a legal agreement (an insurance policy).  
+5.  An insurance company is an organization and bearer_of some **payor_role** that is realized by making a payment to the insured or a third party once (in the case of health insurance) health services are provided to the insured.  The payor role (in this case, not generally) is the concretization of a socio-legal generically dependent_continuant that is the specified output of some document act and inheres in an organization that is party to a insurance policy.  The payor role is the subject of the action specification that is a part of the insurance policy as is the payment.
+6. The enrollment date is the day that the payor and insured roles came into existence.  Or perhaps the SLGDCs that the roles concretize. (Note that the insured role is not generically dependent since one cannot transfers one's insurance benefits to another person.)
+7. An insured party role is the subject of a conditional specification that is a part of some insurance policy and is the specified output of the document act that also has the insurance policy as specified output.
+8. An enrollment start date is a date that contains the left boundary of the existence of the insured party role. 
+9. A date is a temporal interval that has a scalar measurement datum whose value is equivalent to one day.
+10. An enrollment in an insurance policy period is a temporal interval during which an organism is the bearer of an insured party role.  The enrollment in an insurance policy period is also a part of the temporal interval occupied by the life of that organism.
+
+## New Terms 
+* **contract** - Superclass: Document and (is_specified_output_of some 'document act')
+* **indemnity contract** - Superclass: contract and ('has part' some 'action specification') and ('has part' some 'objective specification') and ('has part' some 'plan specification') and ('has part' some 'conditional specification')
+* **insurance policy** - Superclass: 'indemnity contract' and is_specified_output_of some ('document act' and (has_agent some 'insurance company') and (has_agent some ('collection of humans' and 'has member' only (bearer_of some 'policy holder role')))) 
+['and has_specified_output some 'insured party role'' should modify 'document act', but this is not possible while declaration is defined as having a SLGDC as specified output since roles are not generically dependent.]
+* **insured party role** - Superclass: 'role in human social processes' and (inverse 'is about' some ('conditional specification' and 'part of' some 'insurance policy')) and (is_specified_output_of some ('document act' and (has_specified_output some 'insurance policy')))
+* **insurance company** - Superclass: organization and
+('bearer of' some ('payer role' and (concretizes some ('socio-legal generically dependent continuant' and is_specified_output_of some 'document act')))) and ('bearer of' some 'party to an insurance policy') 
+and (inverse 'is about' some ('action specification' and 'part of' some 'insurance policy'))
+* **policy holder role** - Superclass: 'insured party role' and ('inheres in' some ('bearer of' some 'party to an insurance policy'))
+* **payer role** - Superclass: 'role in human social processes' 
+* **party to an insurance policy** - Superclass: 'party to a legal agreement' 
+* **enrollment in an insurance policy period** - Subclass: 'temporal interval' and (inverse(exists at) ('insured part role' and 'inheres in' (some organism))) and ('part of' some ('temporal interval' and 'is temporal location of' [life of an organism]) 
+* **enrollment start date** - date and 'is occupied by' some ('history part' and 'has left process boundary' some ('process boundary' and ('part of' some 'enrollment in an insurance policy period'))
+* **enrollment end date** - date and 'is occupied by' some ('history part' and 'has right process boundary' some ('process boundary' and ('part of' some 'enrollment in an insurance policy period'))
+* **date** - 'temporal interval' and inverse 'is duration of' some ('measurement datum' and 'has value specification' some ('scalar value specification' and 'has value' '1' and 'has measurement unit label' 'day') 
+
+##PCORNet Enrollment
+"ENROLLMENT Domain Description: Enrollment is a concept that defines a period of time during which all medically-attended events are expected to be observed. This concept is often insurance-based, but other methods of defining enrollment are possible."
+
+"The ENROLLMENT table contains one record per unique combination of PATID, ENR_START_DATE, and BASIS.
+* What are "medically-attended events"?
+* The enrollment dates specify a period of complete data capture. This is a different notion from enrollment in an insurance plan although enrollment in an insurance plan can be the "basis" of the complete data capture.  Also, notice that the purpose of enrollment dates is to support a closed-world assumption. ("The ENROLLMENT table provides an important analytic basis for identifying periods during which medical care should be observed, for calculating person-time, and for inferring the meaning of unobserved care (ie, if care is not observed, it likely did not happen).")
+

docs/modeling/Modeling-Discharge-and-Discharge-Status.md

@@ -0,0 +1,4 @@
+# Discharge as Document Act
+A discharge is a document act that involves a document that concretizes a directive information entity.  That directive information entity has as parts a plan specification, an action specification, and an objective specification.  Usually the objective specification is about where the patient will go upon discharge, e.g., home, a rehab facility, etc.
+
+Discharges have as agents humans who are the bearer of a health care provider role.